Langfuse MCP Server

Model Context Protocol server for Langfuse observability. Query traces, analyze accuracy, detect failures, track costs, debug latency, manage prompts and datasets.

56 tools across data access and analytics. Multi-project support so one instance can serve several Langfuse projects. Works with Claude Code, Codex CLI, Cursor, and any MCP-compatible client.

Why this MCP server?

Comparison with official Langfuse MCP (as of March 2026):

The official MCP focuses on prompt management. This server provides a full observability and analytics toolkit — traces, observations, sessions, scores, exceptions, prompts, datasets, annotation queues, plus 9 built-in analytics tools that compute insights server-side and return LLM-sized summaries. Multi-project routing lets a single instance serve several Langfuse projects behind one connector URL.

Quick Start

1. Get your API keys

• Langfuse Cloud: cloud.langfuse.com → Settings → API Keys

• Self-hosted: Your Langfuse instance → Settings → API Keys. Set LANGFUSE_HOST to your instance URL (e.g., https://langfuse.yourcompany.com)

2. Add the MCP server

Claude Code

claude mcp add \
  -e LANGFUSE_PUBLIC_KEY=pk-lf-... \
  -e LANGFUSE_SECRET_KEY=sk-lf-... \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  --scope project \
  langfuse-mcp -- uvx langfuse-mcp-server

Codex CLI

codex mcp add langfuse-mcp \
  --env LANGFUSE_PUBLIC_KEY=pk-lf-... \
  --env LANGFUSE_SECRET_KEY=sk-lf-... \
  --env LANGFUSE_HOST=https://cloud.langfuse.com \
  -- uvx langfuse-mcp-server

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "langfuse-mcp": {
      "command": "uvx",
      "args": ["langfuse-mcp-server"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-...",
        "LANGFUSE_HOST": "https://cloud.langfuse.com"
      }
    }
  }
}

3. Verify

Restart your CLI, then test with /mcp (Claude Code) or codex mcp list (Codex).

Manual install (alternative to uvx)

pip install langfuse-mcp-server
langfuse-mcp-server

Hosting as a remote service

Run as a long-lived HTTP service so multiple users connect to a single instance — required for Claude.ai custom Connectors, and useful for team-wide access without distributing Langfuse API keys per user.

Enabled via env vars; no code changes.

Minimum setup

MCP_TRANSPORT=streamable-http
MCP_BASE_URL=https://mcp.yourcompany.com
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://your-langfuse-instance.example

Without OAuth env vars, the endpoint is unauthenticated — suitable only for local testing. See Google OAuth setup below for production.

Docker

A production-ready Dockerfile is checked into the repo (non-root user, pinned base, .dockerignore to prevent secret leakage). Each tagged release auto-publishes a multi-arch image to GitHub Container Registry via .github/workflows/docker-publish.yml.

Pull the published image:

docker pull ghcr.io/drishtantkaushal/langfusemcp:latest

Or build from source:

docker build -t langfuse-mcp .

Run (all secrets injected via -e, never baked into the image):

docker run -d \
  --name langfuse-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_BASE_URL=https://mcp.yourcompany.com \
  -e LANGFUSE_PUBLIC_KEY=pk-lf-... \
  -e LANGFUSE_SECRET_KEY=sk-lf-... \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  -e GOOGLE_CLIENT_ID=... \
  -e GOOGLE_CLIENT_SECRET=... \
  -e ALLOWED_EMAIL_DOMAINS=yourcompany.com \
  ghcr.io/drishtantkaushal/langfusemcp:latest

Reverse proxy

Terminate TLS in front (nginx, Caddy, Cloudflare). MCP endpoint is at /mcp/ (trailing slash). Because responses stream, the proxy must:

• Disable response buffering — nginx: proxy_buffering off;

• Allow read timeout ≥ 5 minutes — some analytics queries legitimately run several minutes

• Speak HTTP/1.1 with keepalive upstream

Google OAuth

In your Google Cloud project:

1. APIs & Services → OAuth consent screen

   • User type: Internal (restricts sign-in to your Google Workspace domain)

   • Scopes: openid, https://www.googleapis.com/auth/userinfo.email

2. Credentials → Create OAuth client ID → Web application

   • Authorized redirect URI: https://{your-base-url}/auth/callback

   • Copy the Client ID and Client Secret

Set:

GOOGLE_CLIENT_ID=....apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...

OAuth activates when GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and MCP_BASE_URL are all set. With an Internal consent screen, Google rejects non-Workspace sign-ins at the identity layer — the server never sees those attempts.

Optional email allowlist

For narrower control than "anyone in the Workspace":

# either, or both
ALLOWED_EMAIL_DOMAINS=yourcompany.com
ALLOWED_EMAILS=alice@yourcompany.com,bob@yourcompany.com

When set, every tool call verifies the caller's email_verified claim and checks membership before proceeding. When unset, the server trusts whatever the OAuth provider returns.

Adding to Claude.ai

Once hosted at https://mcp.yourcompany.com:

1. Claude.ai → Settings → Connectors → Add custom connector

2. Remote MCP server URL: https://mcp.yourcompany.com/mcp/

3. Leave the OAuth Client ID / Secret fields empty — the server uses Dynamic Client Registration; those fields are for a different deployment pattern.

4. Click Add → Google sign-in popup → done.

Verifying the deploy

Auth enabled, expect 401:

curl -i -X POST https://mcp.yourcompany.com/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

OAuth metadata endpoint returns JSON (used by Claude.ai to auto-register):

curl https://mcp.yourcompany.com/.well-known/oauth-authorization-server

Liveness/readiness probe — unauthenticated GET /health returns HTTP 200 with {"status": "ok"}, suitable for Kubernetes probes:

curl -i https://mcp.yourcompany.com/health

Multi-project support

A single server instance can route to multiple Langfuse projects. Every tool accepts an optional project argument; when omitted, the server-configured default is used. Call list_projects to discover what's available.

Configuring projects

Declare each project via indexed env vars. Project names are data, not part of variable names — use whatever scheme you like.

LANGFUSE_PROJECT_1_NAME=production
LANGFUSE_PROJECT_1_PUBLIC_KEY=pk-lf-...
LANGFUSE_PROJECT_1_SECRET_KEY=sk-lf-...
LANGFUSE_PROJECT_1_HOST=https://cloud.langfuse.com

LANGFUSE_PROJECT_2_NAME=staging
LANGFUSE_PROJECT_2_PUBLIC_KEY=pk-lf-...
LANGFUSE_PROJECT_2_SECRET_KEY=sk-lf-...
LANGFUSE_PROJECT_2_HOST=https://cloud.langfuse.com

LANGFUSE_DEFAULT_PROJECT=production

Usage from the client

Claude: "Show me failing traces in production today."
→ fetch_traces(project="production", ...) routed to project 1's credentials.

Claude: "Compare that with staging."
→ fetch_traces(project="staging", ...) routed to project 2's credentials.

Each project has its own cache, rate limiter, and connection pool. Claude.ai sees one connector; users authenticate once via OAuth and can query any configured project within the session.

Single-project (legacy) mode

If LANGFUSE_PROJECT_1_NAME is not set, the server falls back to the legacy LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_HOST vars and registers them as a project called default. Existing deployments keep working without changes.

Configuration

Tools

Analytics (9 tools)

Tools that compute insights server-side and return compact summaries. These go beyond raw data access — they aggregate, detect patterns, and compute statistics so the LLM can reason over results without hitting context window limits.

Data Access (25 tools)

Full Langfuse API coverage for querying and managing your observability data.

Traces

Observations

Sessions

Errors

Scores

Prompts

Datasets

Annotation Queues

Metrics

Users

Comments

Models

Projects

Schema

Sample Questions

Once connected, ask your AI assistant questions like these:

Agent & Pipeline Health

• "Which agents failed the most this week?"

• "What's the failure rate by agent name?"

• "Which agent has the worst accuracy?"

• "Show me the top 5 agents by trace volume"

• "Are any agents consistently slower than others?"

• "Compare all agents by accuracy, latency, and cost"

Accuracy & Quality

• "What's our overall accuracy this week?"

• "What's the accuracy trend by week for the last 30 days?"

• "Compare accuracy across different agents"

• "What's the daily accuracy breakdown?"

• "Which users are getting the worst accuracy?"

• "What percentage of traces have feedback scores?"

Failures & Debugging

• "Show me failure examples from today"

• "What are the most common failure patterns?"

• "Which users are seeing the most failures?"

• "What's the failure rate by agent?"

• "Are failures increasing or decreasing this week vs last?"

• "Show me traces where the LLM said 'unable to' or 'I can't'"

Token Usage

• "What are the P90 and P99 token usage stats?"

• "Which agents consume the most tokens?"

• "Compare token usage across user groups"

• "Are any users hitting unusually high token counts?"

Context Window Breaches

• "Are any generations exceeding the 128K context window?"

• "Show me traces with token usage above 200K per generation"

• "What's the breach severity distribution?"

• "Which users trigger the most context window breaches?"

Sessions & Engagement

• "What's our multi-turn rate?"

• "How deep are sessions on average?"

• "Which users have the deepest sessions?"

• "How many single-turn vs multi-turn sessions this week?"

• "What's the average session cost?"

Cost

• "How much are we spending per day this week?"

• "What's the weekly cost trend for the last 30 days?"

• "Which agent is the most expensive?"

• "Which users are costing the most?"

• "What's the average cost per trace?"

Latency

• "What's the P95 latency?"

• "Is latency getting worse over time?"

• "Which model is the slowest?"

• "Compare latency across agents"

• "Show me per-generation latency breakdown by model"

• "Which users are experiencing the highest latency?"

Annotation & Write-back

• "Score all failing traces from today with 'needs-review'"

• "Tag these trace IDs as 'high-quality' for dataset creation"

• "Mark trace abc-123 with a score of 0 and comment 'hallucinated output'"

Lookups & Exploration

• "Fetch the last 20 traces"

• "Show me trace abc-123 with all its observations"

• "List sessions for user alice@example.com"

• "What errors happened in the last 24 hours?"

• "How many errors occurred this week?"

• "Show me all prompts in the project"

• "List all datasets"

• "What fields are available on traces and observations?"

Grouping Options

The group_by parameter controls how traces are segmented in analytics tools:

Selective Tool Loading

Load only the tool groups you need to reduce token overhead:

# Only load traces and analytics tools
LANGFUSE_TOOLS=traces,analytics langfuse-mcp-server

# Only load prompts and datasets
LANGFUSE_TOOLS=prompts,datasets langfuse-mcp-server

# In Claude Code
claude mcp add \
  -e LANGFUSE_PUBLIC_KEY=pk-lf-... \
  -e LANGFUSE_SECRET_KEY=sk-lf-... \
  -e LANGFUSE_TOOLS=traces,observations,analytics \
  langfuse-mcp -- uvx langfuse-mcp-server

Available groups:

If LANGFUSE_TOOLS is not set, all 56 tools are loaded.

Read-Only Mode

Disable write operations (score_traces, create_dataset, create_dataset_item, delete_dataset_item, create_text_prompt, create_chat_prompt):

LANGFUSE_MCP_READ_ONLY=true

How it Compares

vs Official Langfuse MCP

The official Langfuse MCP (5 tools) focuses on prompt management. This server provides full observability coverage plus 9 analytics tools.

vs Other Langfuse MCP Implementations

Other implementations provide data access (fetching raw traces, observations, sessions) using synchronous HTTP clients. This server adds a compute layer — analytics tools that aggregate, detect patterns, and compute statistics server-side — plus an async architecture that's fundamentally faster.

vs Platform-Embedded AI (Braintrust Loop, LangSmith Insights, Arize Alyx)

Architecture

Why async httpx instead of the Langfuse SDK?

The Langfuse Python SDK is excellent for writing traces (it batches and sends asynchronously in the background). But for reading traces at scale — which is what an analytics MCP server does — the SDK has a limitation: its read API is synchronous, built on the requests library.

This server uses httpx.AsyncClient instead, which enables:

• Concurrent observation fetching — fetch observations for 100 traces simultaneously via asyncio.gather, not one-by-one

• Non-blocking pagination — paginate through thousands of traces without blocking the event loop

• Rate-limited concurrency — asyncio.Semaphore + token bucket controls throughput without time.sleep() blocking

Measured impact: analyze_latency with per-generation breakdown dropped from 110s to 20s (5.4x faster) on a self-hosted instance with 2.4M daily observations.

Caching strategy

Two-tier in-memory TTL cache using cachetools.TTLCache:

The cache operates at the API page level. If you call aggregate_by_group then compute_accuracy for the same time range, the second call hits cache for all trace pages — only scores are fetched fresh.

Configure via LANGFUSE_CACHE_TTL and LANGFUSE_CACHE_TTL_HISTORICAL (seconds).

Rate limiting

A global token bucket rate limiter respects Langfuse API limits:

On HTTP 429 responses, the limiter automatically halves the RPM and reads the Retry-After header. This means the server adapts to any rate limit — cloud or self-hosted — without manual configuration.

Observation fetching: batch vs concurrent

Analytics tools that need per-generation data (token percentiles, context breaches, latency breakdown) face the N+1 problem: one API call per trace to fetch its observations.

This server uses a two-step strategy:

1. Try batch fetch — fetch ALL observations for the time range in one paginated call, group by traceId in memory

2. If volume is too high (>5000 pages / 500K+ observations) — fall back to concurrent per-trace fetch using asyncio.gather with semaphore-controlled concurrency

This means the server handles both small projects (batch is faster) and large-scale deployments (concurrent targeted fetching avoids downloading millions of irrelevant observations).

Context isolation via sub-agent

The server ships with a Claude Code custom agent at .claude/agents/langfuse-analyst.md. When a user asks a Langfuse-related question, Claude Code can delegate to this agent, which:

• Only loads Langfuse MCP tools (not other tools in the session)

• Has a specialized system prompt with tool taxonomy and workflow patterns

• Runs in an isolated context window, keeping the main conversation clean

• Returns a summary to the parent conversation

This prevents 33 tool schemas (~5000 tokens) from polluting every conversation.

Contributing

See CONTRIBUTING.md for development setup, code style guidelines, and areas for contribution.

Security

See SECURITY.md for the security policy, vulnerability reporting, and API key handling.

Code of Conduct

See CODE_OF_CONDUCT.md.

License

MIT — see LICENSE.