Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Langfuse Trace Fetcher Show me the last 5 production traces"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Version 0.1.0 · Fetch Langfuse observability traces directly into your coding agent's context.
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:
Tool | Description |
| Fetch a filtered, paginated list of traces |
| Fetch full detail for a single trace (including observations, scores) |
| Show available filter fields and usage examples |
Related MCP server: Shepherd MCP
pip install langfuse-traces-mcp# 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]"Python 3.10+
VS Code with Gemini Code Assist extension (Agent Mode enabled)
Langfuse instance — cloud (cloud.langfuse.com) or self-hosted
Install the package: pip install langfuse-traces-mcp
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"
}
}
}Reload VS Code after configuration.
Open Gemini Code Assist chat and toggle Agent Mode ON.
The langfuse-traces tools should now be available.
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.
Parameter | Type | Default | Description |
| string | — | Filter by trace name |
| string | — | Filter by user ID |
| string | — | Filter by session ID |
| list | — | Filter by tags |
| string | — | Filter by app version |
| string | — | Filter by release |
| string | — | Filter by environment |
| string | — | ISO 8601 start time |
| string | — | ISO 8601 end time |
| int | 20 | Max traces (1–100) |
| int | 1 | Page number |
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: 5The agent will call fetch_langfuse_traces with those parameters and return formatted trace data.
# 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├── 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 testsThis 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
MIT
Fetch a filtered list of traces from a Langfuse instance.
Connects to the specified Langfuse host using the provided credentials and returns matching traces formatted as readable context.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter by trace name. | |
| page | No | Page number for pagination (default 1). | |
| tags | No | Filter by tags (traces must have ALL specified tags). | |
| limit | No | Max number of traces to return (1–100, default 20). | |
| release | No | Filter by release identifier. | |
| user_id | No | Filter by user ID. | |
| version | No | Filter by application version. | |
| host_url | Yes | Langfuse host URL (e.g. https://cloud.langfuse.com or http://localhost:3000). | |
| public_key | Yes | Langfuse public API key. | |
| secret_key | Yes | Langfuse secret API key. | |
| session_id | No | Filter by session ID. | |
| environment | No | Filter by environment (e.g. production, staging). | |
| to_timestamp | No | ISO 8601 end time — only return traces before this time. | |
| from_timestamp | No | ISO 8601 start time — only return traces at or after this time. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It states that the tool 'connects...using provided credentials' and 'returns...matching traces formatted as readable context', implying a read operation. However, it does not disclose details like rate limits, error behaviors, or any side effects, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, free of redundancy, and every sentence adds value. It is concise and front-loaded with the key purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 14 parameters with full schema descriptions and the presence of an output schema, the description is reasonably complete. It could mention pagination or filtering behavior, but the schema and output schema fill in many gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond 'filtered list', and all parameter details are already in the schema. The description does not enrich parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a filtered list of traces from a Langfuse instance', specifying the verb and resource. While it distinguishes from sibling tools by name, it does not explicitly contrast with 'get_langfuse_trace_detail' or 'list_langfuse_trace_filters'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'get_langfuse_trace_detail' (for a single trace) or 'list_langfuse_trace_filters' (to list available filters). There are no when-not-to-use or prerequisite instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full detail for a single Langfuse trace by its ID.
Returns the complete trace including input/output data, observations (spans, generations), scores, and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| host_url | Yes | Langfuse host URL (e.g. https://cloud.langfuse.com or http://localhost:3000). | |
| trace_id | Yes | The ID of the trace to fetch. | |
| public_key | Yes | Langfuse public API key. | |
| secret_key | Yes | Langfuse secret API key. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It describes the return payload but does not disclose behavioral traits like idempotency, rate limits, or error conditions. Adding notes on safety (read-only) and required auth would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences purpose-first, no filler. Efficiently communicates purpose and return content. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema, and 100% parameter coverage, the description is nearly complete. It lacks only minor usage context (e.g., idempotency note), but overall covers the essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no parameter meaning beyond the schema. The baseline of 3 applies; the description mentions 'by its ID' but trace_id is already well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', resource 'full detail for a single Langfuse trace', and the method 'by its ID'. It lists returned components (input/output, observations, scores, metadata), distinguishing it from siblings that list traces or filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing full detail of one trace, and the contrast with siblings (fetch_langfuse_traces, list_langfuse_trace_filters) is clear. However, it does not explicitly state when not to use or mention alternatives, which would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available filter fields for fetching Langfuse traces.
This is a help/reference tool — it does not make any API calls. Use these filter names as parameters when calling fetch_langfuse_traces.
Returns: A formatted reference table of available filters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description is transparent: it is a reference tool with no side effects, returning a formatted table. Could mention if results are static or computed, but sufficient for context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose, no redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and existence of output schema, description is nearly complete. Could briefly mention output format or that it's fast, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, schema coverage 100%. Description adds meaning by explaining the output serves as parameter names for fetch_langfuse_traces, going beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available filter fields for fetching traces. It specifies it is a help/reference tool that does not make API calls, distinguishing it from sibling tools like fetch_langfuse_traces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it does not make API calls and instructs to use the filter names as parameters for fetch_langfuse_traces, providing clear when-to-use and alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.3fetch_langfuse_tracesget_langfuse_trace_detaillist_langfuse_trace_filtersScored across 3 tools
Each tool serves a distinct purpose: fetching a filtered list of traces, retrieving full detail for a specific trace, and listing available filter fields. There is no functional overlap.
All tools follow a consistent verb_noun pattern (fetch_langfuse_traces, get_langfuse_trace_detail, list_langfuse_trace_filters) with snake_case, making the naming predictable and clear.
With 3 tools, the set is well-scoped for a trace fetching server: listing with filters, getting detail, and a reference tool for filters. No extraneous or missing tools.
For a 'Trace Fetcher', the tools cover the core workflow: querying traces with filters, retrieving individual details, and discovering available filters. No essential operations are missing.
AI agent observability for production traces, natural-language insights, and improvement loops.
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
Traced OpenAI LangChain Agent
LLM Orchestration Traced Agent
