Spanlens MCP Server

Spanlens

Open-source LLM observability. Record every OpenAI / Anthropic / Gemini / Azure OpenAI / Ollama call with one line of code. Plugs into Vercel AI SDK, LangChain, and LlamaIndex too. Query the same data directly from Cursor, Claude Desktop, or Continue via the bundled MCP server. Get cost, latency, tokens, traces, anomalies, PII scan, and model-swap suggestions out of the box. Self-hostable. MIT.

Hosted: spanlens.io · npm: @spanlens/sdk · PyPI: spanlens · CLI: @spanlens/cli · MCP: @spanlens/mcp-server · Status: status.spanlens.io · Changelog: spanlens.io/changelog

---

---

Why Spanlens?

• Helicone was acquired and its roadmap is uncertain.
• Langfuse is powerful but complex to set up and expensive to scale.
• Spanlens ships the 20% of features that cover 80% of real production needs. You get request log, cost tracking, agent tracing, anomaly detection, PII scanning, and prompt versioning with a clean UI, a two-minute setup, and pricing that doesn't punish growth.

Predictable bills, no quota cliff. Free hits a hard 429 at 50K requests so a runaway loop in dev can't cost you money. Paid plans use a soft limit with authorized overage (Pro: +$8 / 100K, Team: +$5 / 100K) up to a hard cap you control, so a traffic spike charges you fairly instead of dropping requests.

Seats: Free 1 · Pro 3 · Team 10 · Enterprise unlimited. Unlimited projects on every paid tier.

---

⚡ Quick start in 30 seconds

TypeScript / JavaScript (Next.js)

npx @spanlens/cli init

The wizard:

1. Installs @spanlens/sdk with your package manager (npm / pnpm / yarn / bun)
2. Writes SPANLENS_API_KEY to .env.local
3. Rewrites every new OpenAI({ apiKey, baseURL }) into createOpenAI()

Paste your Spanlens API key once, confirm two prompts, done. Your LLM calls are now flowing through the Spanlens proxy and visible in www.spanlens.io/requests.

Manual TypeScript setup

import { createOpenAI } from '@spanlens/sdk/openai'
const openai = createOpenAI()  // reads SPANLENS_API_KEY, uses Spanlens proxy baseURL

Python

pip install "spanlens[openai]"

from spanlens.integrations.openai import create_openai

client = create_openai()  # reads SPANLENS_API_KEY from env
res = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)

For agent tracing in Python (multi-step, async, tool calls) see the Python SDK README.

Framework integrations

Already using an orchestration framework? Plug Spanlens in as a callback. No code rewrites.

Vercel AI SDK (Next.js / edge friendly)

import { SpanlensClient } from '@spanlens/sdk'
import { createSpanlensTracker } from '@spanlens/sdk/vercel-ai'

const tracker = createSpanlensTracker({
  client: new SpanlensClient({ apiKey: process.env.SPANLENS_API_KEY! }),
  modelName: 'gpt-4o',
})

await generateText({
  model: openai('gpt-4o'),
  messages,
  onStepFinish: tracker.onStepFinish,
  onFinish: tracker.onFinish,
})

LangChain JS / LangGraph

import { createSpanlensCallbackHandler } from '@spanlens/sdk/langchain'

const handler = createSpanlensCallbackHandler({ client })
await chain.invoke({ input }, { callbacks: [handler] })   // LangChain
await graph.invoke({ input }, { callbacks: [handler] })   // LangGraph

LlamaIndex TS

import { Settings } from 'llamaindex'
import { registerSpanlensCallbacks } from '@spanlens/sdk/llamaindex'

const unregister = registerSpanlensCallbacks(Settings, { client })
// ... run queries ... unregister() on shutdown

Python: LangChain — from spanlens.integrations.langchain import SpanlensCallbackHandler. Same BaseCallbackHandler contract, works with chains, LCEL, and LangGraph.

Ollama (local LLMs) — Use the OpenAI-compatible client pointed at your local Ollama, then wrap with observeOllama() so the dashboard tags the call as Ollama instead of OpenAI.

import OpenAI from 'openai'
import { observeOllama } from '@spanlens/sdk'

const ollama = new OpenAI({ baseURL: 'http://localhost:11434/v1', apiKey: 'ollama' })
await observeOllama('chat', () => ollama.chat.completions.create({
  model: 'llama3.1', messages: [...]
}))

---

What you see

Every request logged with model, provider, latency, tokens, cost, and full prompt + response body. Filter, search, export. Streaming responses reconstructed automatically.

---

What you get

---

Team & workspaces

Spanlens is multi-user out of the box. Invite teammates, hand out roles, and spin up a separate workspace per client.

• Roles are admin (members + billing), editor (data + settings), and viewer (read-only). The last admin is protected against demotion / removal.
• Email invitations have a 7-day expiry with sha256-hashed tokens. Sent via Resend when RESEND_API_KEY is set; falls back to console-logging the accept URL for local dev.
• The pending-invitation banner surfaces unaccepted invites at the top of the dashboard, even if the recipient never opened the email. Accept joins and auto-switches the active workspace; Decline removes the row.
• Multi-workspace lets you switch between workspaces from the sidebar (sb-ws cookie + hard reload so middleware re-resolves scope). Useful for consultants juggling multiple clients or one team running prod / staging as separate workspaces.
• Two-step onboarding sends new signups to /onboarding: name your workspace, answer two optional survey questions, done. Invitees get a short-circuited variant where Accept skips workspace creation entirely.
• The audit log (Settings → Audit log) records every membership / role / invitation event with actor + timestamp.

---

Monorepo structure

Spanlens/
├── apps/
│   ├── web/             — Next.js 14 dashboard (www.spanlens.io)
│   └── server/          — Hono LLM proxy + REST API (spanlens-server.vercel.app)
├── packages/
│   ├── sdk/             — @spanlens/sdk:  TypeScript / JavaScript SDK
│   ├── sdk-python/      — spanlens (PyPI): Python SDK
│   └── cli/             — @spanlens/cli:  npx wizard for 1-command setup
├── clickhouse/
│   ├── migrations/      — ClickHouse schema for the `requests` log table
│   └── apply.ts         — `pnpm ch:migrate` runner (idempotent)
└── supabase/
    ├── migrations/      — Postgres schema (orgs, projects, keys, prompts, … — RLS-gated)
    └── seeds/           — model_prices.sql etc.

Storage split

Spanlens uses two databases, each for what it's good at.

Supabase (Postgres) handles transactional, relational, RLS-gated data: organizations, projects, members, API + provider keys, prompts, datasets, alerts, billing, audit log.

ClickHouse handles the high-volume append-only requests table (every LLM call). All reads go through apps/server/src/lib/requests-query.ts, which auto-injects the organization_id filter and the per-plan retention window (free=14d / pro=90d / team=365d). If ClickHouse is briefly unreachable, the proxy falls back to a Supabase queue (requests_fallback) that a cron replays every 5 minutes with no log loss.

Projects, unified keys, and headers

• A workspace can hold multiple projects (e.g. dev / staging / prod, or one per app). Each project gets its own quota slice, provider keys, and prompt namespace.
• Unified API keys give you one sl_live_* key per project that is provider-agnostic. Spanlens infers the provider from the request path (/proxy/openai/*, /proxy/anthropic/*, /proxy/gemini/*, /proxy/azure/*), so you only need one Spanlens key even if you call multiple model vendors.
• X-Spanlens-* headers (set automatically by the SDK helpers withUser(), withSession(), withPromptVersion(), withLogBody()): tag a request with end-user / session IDs, link it to a prompt-version experiment, or limit how much body Spanlens stores. Full list in /docs/proxy.
• Streaming safety ensures proxy responses are gracefully closed at 290s with a truncated=true flag in the log, so long streams never silently disappear.

---

Local development

Prerequisites: Node 20+, pnpm 10.33.0+, Docker (for local Supabase), Vercel CLI optional.

# 1. Clone + install
git clone https://github.com/spanlens/Spanlens.git
cd Spanlens
pnpm install

# 2. Start local Supabase + ClickHouse (both require Docker)
supabase start
supabase db push        # apply Postgres migrations
supabase gen types --lang typescript --local > supabase/types.ts

docker compose up -d clickhouse   # start ClickHouse only (web/server run from pnpm dev)
pnpm ch:migrate                   # apply ClickHouse migrations

# 3. Env vars (see apps/server/.env.example)
cp apps/server/.env.example apps/server/.env

# 4. Run everything (web on :3000, server on :3001)
pnpm dev

Running tests + lint

pnpm typecheck          # TS across all packages
pnpm lint               # ESLint
pnpm test               # Vitest — server + sdk + cli suites
pnpm build              # production build smoke test

See CLAUDE.md for architecture rules and Known Gotchas (streaming, RLS, Paddle billing, Vercel Edge runtime, npm publish).

---

Self-hosting

The easiest way to self-host is with the included docker-compose.yml. It runs the dashboard (web), the proxy/API server, and a local ClickHouse instance together using pre-built images from GHCR.

1. Apply the Supabase schema (one-time)

Open your Supabase project → SQL Editor → New query, paste the contents of supabase/init.sql, and click Run. That's it. No CLI needed.

Alternative (psql):

psql "postgresql://postgres:<password>@db.<ref>.supabase.co:5432/postgres" \
  -f supabase/init.sql

2. Create a .env file

# Supabase (cloud or self-hosted)
NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_URL=https://xxxx.supabase.co
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...

# Encryption key (generate with: openssl rand -base64 32)
ENCRYPTION_KEY=<32-byte base64>

# Random secret for cron endpoint
CRON_SECRET=<random string>

# ClickHouse (request logs, required)
CLICKHOUSE_URL=http://clickhouse:8123        # the in-network service from docker-compose
CLICKHOUSE_USER=spanlens
CLICKHOUSE_PASSWORD=<choose a strong password>
CLICKHOUSE_DB=spanlens

# Optional (for invite emails)
# WEB_URL=https://your-domain.com
# RESEND_API_KEY=re_...
# RESEND_FROM=Spanlens <no-reply@your-domain.com>

# Optional (Paddle billing, only if you sell paid plans on your instance)
# PADDLE_API_KEY=...
# PADDLE_NOTIFICATION_SECRET=...
# PADDLE_ENVIRONMENT=sandbox  # or production

3. Start

docker compose up -d
pnpm ch:migrate                # one-time: apply ClickHouse schema (requests table)

• Dashboard: http://localhost:3000
• API / proxy: http://localhost:3001
• ClickHouse HTTP: http://localhost:8123
• Health: GET /health (liveness) and GET /health/deep (ClickHouse + fallback queue depth)

The web container passes NEXT_PUBLIC_* vars as build arguments (Next.js bakes them into the client bundle), so they must be present before docker compose build.

Server-only (no dashboard)

If you only need the proxy/API and run the dashboard separately:

docker pull ghcr.io/spanlens/spanlens-server:latest
docker run -p 3001:3001 \
  -e SUPABASE_URL=... \
  -e SUPABASE_ANON_KEY=... \
  -e SUPABASE_SERVICE_ROLE_KEY=... \
  -e ENCRYPTION_KEY=... \
  ghcr.io/spanlens/spanlens-server:latest

Point your SDK at your self-hosted URL

const openai = createOpenAI({
  baseURL: 'https://your-spanlens.example.com/proxy/openai/v1',
})

Your Spanlens instance talks to your Supabase + ClickHouse. We never see your data.

Background jobs (Vercel Cron / your scheduler)

The hosted instance ships with the following cron tasks (see apps/server/vercel.json). On self-host, point any scheduler at the same paths with the CRON_SECRET bearer:

---

Contributing

PRs and issues welcome. See CONTRIBUTING.md for the project layout, local-dev setup, coding conventions, and what we look for in a PR. Commit messages follow Conventional Commits and the PR template walks through the safety checklist.

Security issues: please email support@spanlens.io instead of opening a public issue. See SECURITY.md.

License

MIT. Use, fork, self-host, or build on top freely. The hosted service at spanlens.io is the recommended way to run Spanlens, but you can always pull the Docker image and run it yourself (see docs/self-host).