Langfuse Trace Fetcher

Version 0.1.0 · Fetch Langfuse observability traces directly into your coding agent's context.

What It Does

This is a Model Context Protocol (MCP) server that connects your VS Code coding agent (Gemini Code Assist) to a Langfuse instance. It exposes three tools:

Installation

From PyPI (Recommended)

pip install langfuse-traces-mcp

From Source

# Clone the repository
git clone https://github.com/yourusername/langfuse-traces-mcp.git
cd langfuse-traces-mcp

# Install in development mode (includes test dependencies)
pip install -e ".[dev]"

Prerequisites

• Python 3.10+
• VS Code with Gemini Code Assist extension (Agent Mode enabled)
• Langfuse instance — cloud (cloud.langfuse.com) or self-hosted

VS Code Setup

1. Install the package: pip install langfuse-traces-mcp

2. Add the MCP server configuration to your VS Code settings. Open VS Code settings (Ctrl/Cmd + ,) and search for "Gemini Code Assist". In the settings JSON, add:

{
  "mcpServers": {
    "langfuse-traces": {
      "command": "langfuse-traces-mcp"
    }
  }
}

3. Reload VS Code after configuration.
4. Open Gemini Code Assist chat and toggle Agent Mode ON.
5. The langfuse-traces tools should now be available.

Usage

Once configured, you can ask your coding agent questions like:

• "Show me traces from production in the last hour"
• "Get details for trace ID abc-123-xyz"
• "List traces with errors tagged as 'critical'"
• "Show me traces from user 'john.doe' in the staging environment"

The agent will fetch and display formatted trace data directly in the conversation.

Available Filters

Example Chat Usage

In VS Code Gemini Code Assist chat (with Agent Mode on):

Fetch the last 5 production traces from my Langfuse instance:
- Public key: pk-lf-abc123
- Secret key: sk-lf-xyz789
- Host: https://cloud.langfuse.com
- Environment: production
- Limit: 5

The agent will call fetch_langfuse_traces with those parameters and return formatted trace data.

Running Tests

# Install dev dependencies (if not already)
pip install -e ".[dev]"

# Run all tests
pytest tests/ -v

# Run a specific test file
pytest tests/test_models.py -v
pytest tests/test_client.py -v
pytest tests/test_server.py -v

Project Structure

├── pyproject.toml                  # Project metadata & dependencies (v0.1.0)
├── README.md                       # This file
├── .gemini/
│   └── settings.json               # MCP server registration for VS Code
├── src/
│   └── langfuse_traces_mcp/
│       ├── __init__.py              # Version export
│       ├── server.py                # FastMCP server + 3 tool definitions
│       ├── client.py                # Async HTTP client for Langfuse API
│       └── models.py                # Pydantic models (filters, credentials)
└── tests/
    ├── conftest.py                  # Shared test fixtures & mock data
    ├── test_models.py               # Filter & credential validation tests
    ├── test_client.py               # REST client tests (mocked HTTP)
    └── test_server.py               # MCP tool integration tests

Versioning

This project follows Semantic Versioning 2.0:

• PATCH (0.1.x) — Bug fixes
• MINOR (0.x.0) — New filters, tools, or features
• MAJOR (x.0.0) — Breaking changes

License

MIT