Langfuse MCP Server

Version 1.4.2 - A secure MCP server for Langfuse analytics with comprehensive security features and dual readonly/readwrite modes for safe operation.

🔒 Security-First Design (New in v1.4.0)

• Dual Operation Modes - Safe readonly mode by default, explicit opt-in for write operations

• Triple-Layer Security - Environment, tool list, and runtime validation

• Write Tool Prefixing - Clear write_* prefixes for all data modification operations

• Confirmation Prompts - Required confirmation for destructive operations

• Comprehensive Audit Logging - All write operations logged for compliance and security

Features

• 32+ Comprehensive Tools - Complete analytics, dataset management, and comment collaboration

• Secure Mode System - Readonly (default) and readwrite modes with explicit opt-in

• Cost & Usage Analytics - Detailed breakdowns by model, service, environment, and time periods

• Dataset Management - Create, organize, and manage test datasets with validation examples

• Comment Collaboration - Add comments to traces, observations, sessions, and prompts

• Trace Analysis & Debugging - Advanced filtering, search, and detailed trace inspection

• System Management - Health monitoring, model management, and prompt template operations

• Real-time Testing - Comprehensive test suite with mode validation

What's New in v1.4.0

🔒 Security & Mode System:

• Readonly mode by default - only read operations allowed

• Readwrite mode with explicit opt-in for data modification

• Write tool prefixing (write_create_dataset, write_delete_dataset_item, etc.)

• Confirmation prompts for destructive operations

• Comprehensive audit logging for all write operations

🛠️ Enhanced Functionality:

• 32+ tools across analytics, dataset management, and collaboration

• Single CLI binary with intuitive mode flags: langfuse-mcp

• Legacy tool support during transition period

• Mode-aware tool filtering and descriptions

✅ Production Ready:

• Triple-layer security validation

• Extensive test coverage including mode validation

• Clean error messages and user guidance

• Structured audit logs for compliance

Installation

Option 1: Using npx (Recommended)

Read-Only Mode (Safe Default):

# Only analytics and read operations - safe for most users
npx @therealsachin/langfuse-mcp
# OR explicitly use readonly binary
langfuse-mcp-ro

Read-Write Mode (Explicit Opt-in):

# ⚠️ Enables write operations - can modify your Langfuse data
LANGFUSE_MCP_MODE=readwrite npx @therealsachin/langfuse-mcp
# OR use CLI flag
langfuse-mcp --readwrite

Option 2: Local Development

git clone https://github.com/therealsachin/langfuse-mcp.git
cd langfuse-mcp
npm install
npm run build

# Test readonly mode
LANGFUSE_MCP_MODE=readonly node build/index.js

# Test readwrite mode
LANGFUSE_MCP_MODE=readwrite node build/index.js

Configuration

Basic Configuration

Set environment variables for each Langfuse project:

LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx
LANGFUSE_BASEURL=https://us.cloud.langfuse.com

Mode Configuration (New in v1.4.1)

Control server operation mode using CLI flags or environment variables:

CLI Flags (Recommended for npx usage):

# Read-only mode (default, safe)
npx @therealsachin/langfuse-mcp

# Read-write mode (explicit opt-in)
npx @therealsachin/langfuse-mcp --readwrite

# Alternative explicit flag syntax
npx @therealsachin/langfuse-mcp --mode=readonly
npx @therealsachin/langfuse-mcp --mode=readwrite

Environment Variables (Legacy support):

# Readonly mode (default, safe)
LANGFUSE_MCP_MODE=readonly

# Readwrite mode (explicit opt-in)
LANGFUSE_MCP_MODE=readwrite

Claude Desktop Configuration

Read-Only Mode (Recommended for most users):

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-your-key",
        "LANGFUSE_SECRET_KEY": "sk-lf-your-secret",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

Read-Write Mode (Advanced users only):

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp", "--readwrite"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-your-key",
        "LANGFUSE_SECRET_KEY": "sk-lf-your-secret",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

🔒 Security Best Practices

⚠️ IMPORTANT: Never commit real API credentials to version control!

Built-in Security Features (New in v1.4.2)

This MCP server includes multiple layers of security protection:

🛡️ HTTPS Enforcement

• Automatic validation ensures all connections use HTTPS protocol

• Prevents plaintext transmission of credentials and sensitive data

• Runtime checks reject any HTTP URLs with clear error messages

• Production safety guarantees secure communication with Langfuse APIs

🔍 URL Sanitization

• Automatic redaction of sensitive query parameters in error logs

• Information disclosure prevention protects against credential leakage in logs

• Smart filtering preserves debugging info while removing secrets

• Audit trail protection keeps logs clean and compliant

🚨 Pre-commit Security Hooks

• Automated credential detection prevents accidental commits of real API keys

• Langfuse-specific patterns scan for pk-lf- and sk-lf- format keys

• General secret detection catches common credential patterns

• Build validation ensures code compiles before commit

• Git integration uses Husky for seamless workflow integration

To enable pre-commit hooks in your development environment:

npm install husky --save-dev
npx husky install
# Hooks are automatically configured - no manual setup needed!

Secure Credential Management

1. Use Environment Variables: Store credentials in environment variables, never hardcode them in source files

2. Use .env Files Locally: Create a .env file for local development (already in .gitignore)

3. Use Placeholder Values: In committed files, use placeholders like pk-lf-your-public-key

4. Rotate Keys Regularly: Periodically generate new API keys in your Langfuse dashboard

5. Limit Key Permissions: Use project-specific keys with minimal required permissions

What NOT to do:

# ❌ NEVER commit real credentials like this:
LANGFUSE_PUBLIC_KEY=pk-lf-REAL-KEY-NEVER-COMMIT-THIS
LANGFUSE_SECRET_KEY=sk-lf-REAL-SECRET-NEVER-COMMIT-THIS

What TO do:

# ✅ Use placeholder values in committed files:
LANGFUSE_PUBLIC_KEY=pk-lf-your-actual-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-actual-secret-key

# ✅ Store real credentials in .env file (never committed):
# Create a .env file in your project root with your actual credentials

For Production Deployments:

• Use secure environment variable management (e.g., Kubernetes Secrets, Docker secrets, cloud provider secret managers)

• Never include credentials in Docker images or CI/CD logs

• Use least-privilege access principles

Available Tools (18 Total)

Core Analytics Tools (6)

1. list_projects - List all configured Langfuse projects

2. project_overview - Get cost, tokens, and trace summary for a project

3. usage_by_model - Break down usage and cost by AI model

4. usage_by_service - Analyze usage by service/feature tag

5. top_expensive_traces - Find the most expensive traces

6. get_trace_detail - Get detailed information about a specific trace

Extended Analytics Tools (6)

7. get_projects - Alias for list_projects (list available Langfuse projects)

8. get_metrics - Query aggregated metrics (costs, tokens, counts) with flexible filtering

9. get_traces - Fetch traces with comprehensive filtering options

10. get_observations - Get LLM generations/spans with details and filtering

11. get_cost_analysis - Specialized cost breakdowns by model/user/daily trends

12. get_daily_metrics - Daily usage trends and patterns with averages

System & Management Tools (6)

13. get_observation_detail - Get detailed information about a specific observation/generation

14. get_health_status - Monitor Langfuse system health and status

15. list_models - List all AI models available in the project

16. get_model_detail - Get detailed information about a specific AI model

17. list_prompts - List all prompt templates with filtering and pagination

18. get_prompt_detail - Get detailed information about a specific prompt template

Usage with Claude Desktop

Add to your claude_desktop_config.json:

Option 1: Using npx (Recommended)

{
  "mcpServers": {
    "langfuse-analytics": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxx",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

Option 2: Local Installation

{
  "mcpServers": {
    "langfuse-analytics": {
      "command": "node",
      "args": ["/path/to/langfuse-mcp/build/index.js"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxx",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

Example Queries

Once integrated with Claude Desktop, you can ask questions like:

Analytics Queries

• "Show me the cost overview for the last 7 days"

• "Which AI models are most expensive this month?"

• "Find the top 10 most expensive traces from yesterday"

• "Break down usage by service for the production environment"

• "Show me details for trace xyz-123"

System Management Queries

• "Check the health status of my Langfuse system"

• "List all available AI models in my project"

• "Show me details for the GPT-4 model"

• "What prompt templates do I have available?"

• "Get details for the 'customer-support' prompt"

Advanced Analysis

• "Show me detailed information for observation abc-123"

• "What's the daily cost trend for the last month?"

• "Find all traces that cost more than $0.10"

• "Which users are generating the highest costs?"

Development

# Watch mode for development
npm run watch

# Test with MCP Inspector
npm run inspector

# Test endpoints (requires .env file)
npm run test

Testing with Real Langfuse Data

For comprehensive testing against real Langfuse data, create a .env file in the project root:

# .env file (never commit this - it's in .gitignore)
LANGFUSE_PUBLIC_KEY=pk-lf-your-actual-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-actual-secret-key
LANGFUSE_BASEURL=https://us.cloud.langfuse.com

The test suite (npm run test) will automatically load these credentials using dotenv and run 13 comprehensive tests against your actual Langfuse project:

• ✅ Project overview with real cost/token data

• ✅ Trace retrieval with server-side sorting

• ✅ Top expensive traces analysis

• ✅ Daily metrics aggregation

• ✅ Cost analysis breakdowns

• ✅ Health status monitoring

• ✅ Model and prompt management

• ✅ Observation detail retrieval

Note: The .env file is automatically ignored by git to keep your credentials secure.

Publishing to NPM

✅ Package Published! The package is available via:

# Install and run directly with npx
npx @therealsachin/langfuse-mcp

# Or install globally
npm install -g @therealsachin/langfuse-mcp

Package Information:

• Name: @therealsachin/langfuse-mcp

• Version: 1.1.1

• NPM URL: https://www.npmjs.com/package/@therealsachin/langfuse-mcp

Project Structure

src/
├── index.ts              # Main server entry point
├── config.ts             # Project configuration loader
├── langfuse-client.ts    # Langfuse client wrapper with 18+ API methods
├── types.ts              # TypeScript type definitions
└── tools/                # All 18 MCP tools
    # Core Analytics Tools (6)
    ├── list-projects.ts
    ├── project-overview.ts
    ├── usage-by-model.ts
    ├── usage-by-service.ts
    ├── top-expensive-traces.ts
    ├── get-trace-detail.ts
    # Extended Analytics Tools (6)
    ├── get-projects.ts          # Alias for list-projects
    ├── get-metrics.ts           # Aggregated metrics
    ├── get-traces.ts            # Trace filtering
    ├── get-observations.ts      # LLM generations
    ├── get-cost-analysis.ts     # Cost breakdowns
    ├── get-daily-metrics.ts     # Daily trends
    # System & Management Tools (6)
    ├── get-observation-detail.ts    # Observation details
    ├── get-health-status.ts         # Health monitoring
    ├── list-models.ts               # AI models listing
    ├── get-model-detail.ts          # Model details
    ├── list-prompts.ts              # Prompt templates
    └── get-prompt-detail.ts         # Prompt details

docs/                     # Comprehensive documentation
├── ARCHITECTURE.md       # System design and patterns
├── DEVELOPER_GUIDE.md    # Development workflows
├── TECHNICAL_DIAGRAMS.md # Visual system flows
├── IMPLEMENTATION_NOTES.md # API implementation details
└── DOCUMENTATION_INDEX.md # Navigation guide

test-endpoints.js         # Comprehensive test suite (13 tests)

API Integration

This server integrates with multiple Langfuse public API endpoints:

Core Analytics APIs

• /api/public/metrics - Aggregated analytics using GET with JSON query parameter

• /api/public/metrics/daily - Daily usage metrics and cost breakdowns

• /api/public/traces - Trace listing, filtering, and individual trace retrieval

• /api/public/observations - Detailed observation analysis and LLM generation metrics

System Management APIs

• /api/public/observations/{id} - Individual observation details and metadata

• /api/public/health - System health status and monitoring

• /api/public/models - AI model listing and configuration

• /api/public/prompts - Prompt template management and versioning

API Implementation Notes:

• Metrics API: Uses GET method with URL-encoded JSON in the query parameter

• Traces API: Supports advanced filtering, pagination, and ordering

• Observations API: Provides detailed LLM generation and span data

• Daily Metrics API: Specialized endpoint for daily aggregated usage statistics

• Health API: Simple endpoint for system status monitoring

• Models/Prompts APIs: Support pagination, filtering, and detailed retrieval

All authentication is handled server-side using Basic Auth with your Langfuse API keys.

Documentation

For detailed architecture, development guides, and technical diagrams, see the comprehensive documentation:

• docs/ARCHITECTURE.md - System design, patterns, and implementation details

• docs/DEVELOPER_GUIDE.md - Development workflows and common tasks

• docs/TECHNICAL_DIAGRAMS.md - Visual system flows and component diagrams

• docs/DOCUMENTATION_INDEX.md - Complete navigation guide

Troubleshooting

✅ Fixed: 405 Method Not Allowed Errors

Previous Issue: Earlier versions encountered "405 Method Not Allowed" errors due to incorrect API usage.

Solution: This has been FIXED in the current version by using the correct Langfuse API implementation:

• Metrics API: Now uses GET method with URL-encoded JSON query parameter (correct approach)

• Traces API: Uses the actual /api/public/traces endpoint with proper filtering

• Observations API: Uses /api/public/observations endpoint with correct parameters

• Daily Metrics: Uses specialized /api/public/metrics/daily endpoint

✅ Fixed: Cost Values Returning as Zero

Previous Issue: Cost analysis tools were returning zero values even when actual cost data existed.

Solution: This has been FIXED by correcting field name mapping in API response parsing:

• Metrics API Response Structure: The API returns aggregated field names like totalCost_sum, count_count, totalTokens_sum

• Updated Field Access: All tools now use correct aggregated field names instead of direct field names

• Daily Metrics Integration: Cost analysis now uses getDailyMetrics API for cleaner daily cost breakdowns

• Affected Tools: get-cost-analysis, get-metrics, usage-by-model, usage-by-service, project-overview, get-daily-metrics

✅ Fixed: Response Size and API Parameter Issues

Previous Issues:

1. get_observations returning responses exceeding MCP token limits (200k+ tokens)

2. get_traces returning 400 Bad Request errors

Solutions Applied:

• get_observations Response Size Control:

  • Added includeInputOutput: false parameter (default) to exclude large prompt/response content

  • Added truncateContent: 500 parameter to limit content size when included

  • Reduced default limit from 25 to 10 observations

  • Content truncation for input/output fields when enabled

• get_traces API Parameter Fixes:

  • Added parameter validation for orderBy field

  • Enhanced error logging with full request details for debugging

  • Added proper error handling with detailed error responses

✅ Fixed: Cost Analysis Data Aggregation

Previous Issue: Cost analysis was showing zero values for total costs and model breakdowns while daily data worked correctly.

Root Cause: The Metrics API field mapping was still incorrect despite earlier fixes.

Solution: Switched to using the working Daily Metrics API data for all aggregations:

• Total Cost Calculation: Now sums from daily data instead of broken metrics API

• Model Breakdown: Extracts and aggregates model costs from daily usage data

• Daily Breakdown: Optimized to reuse already-fetched daily data

• User Breakdown: Still uses metrics API but with enhanced debugging

Result:

• ✅ totalCost now shows correct values (sum of daily costs)

• ✅ byModel now populated with real model cost breakdowns

• ✅ byDay continues to work perfectly

• 🔍 byUser includes debugging to identify any remaining field mapping issues

✅ Fixed: usage_by_model Showing Zero Costs/Tokens

Previous Issue: usage_by_model showed observation counts correctly but all costs and tokens as zero.

Root Cause: Same metrics API field mapping issue affecting cost calculations.

Solution: Applied the same daily metrics approach used in cost analysis:

• Primary Method: Uses getDailyMetrics API to aggregate model costs and tokens from daily usage breakdowns

• Fallback Method: Falls back to original metrics API with enhanced debugging if daily API fails

• Data Aggregation: Properly extracts totalCost, totalUsage, and countObservations from daily data

Result:

• ✅ Models now show real totalCost values instead of 0

• ✅ Models now show real totalTokens values instead of 0

• ✅ observationCount continues to work correctly

Performance Considerations

API Efficiency: The server now uses native Langfuse endpoints efficiently:

• Metrics queries are processed server-side by Langfuse for optimal performance

• Trace and observation filtering happens at the API level to reduce data transfer

• Daily metrics use the specialized endpoint for pre-aggregated data

Environment Variables

Make sure these environment variables are properly set:

LANGFUSE_PUBLIC_KEY=pk-lf-xxx     # Your Langfuse public key
LANGFUSE_SECRET_KEY=sk-lf-xxx     # Your Langfuse secret key
LANGFUSE_BASEURL=https://us.cloud.langfuse.com  # Your Langfuse instance URL