Unified Logfire

Unified Logfire is an MCP server that provides structured access to OpenTelemetry traces and metrics collected through the Logfire observability platform. This MCP bridge enables AI assistants to query, analyze, and interpret distributed tracing data and application performance metrics without requiring direct dashboard access. It transforms complex observability data into actionable insights through natural language interaction.

When to Use This MCP Server

Connect this server when...

• You need to investigate production incidents by querying distributed traces and spans across microservices
• Your team wants AI-assisted root cause analysis of latency spikes, error cascades, or performance degradation
• You are building automated monitoring workflows that correlate OpenTelemetry metrics with application behavior
• You want to query historical trace data to identify patterns in service communication and dependency chains
• Your observability stack uses OpenTelemetry and you want conversational access to Logfire-collected telemetry

Consider alternatives when...

• Your observability data lives exclusively in Prometheus, Grafana, or Datadog without Logfire integration
• You only need basic uptime monitoring without deep trace-level analysis
• Your application does not emit OpenTelemetry-compatible traces or metrics

Quick Start

Copy
# .mcp.json configuration
{
  "mcpServers": {
    "logfire": {
      "command": "uvx",
      "args": ["logfire-mcp@latest", "--read-token=YOUR-READ-TOKEN"]
    }
  }
}

Connection setup:

1. Sign up at logfire.pydantic.dev and create a project
2. Generate a read-only API token from your Logfire project settings
3. Add the configuration above to your .mcp.json file, replacing YOUR-READ-TOKEN
4. Restart your MCP client to establish the connection

Example tool usage:

# Query recent traces with errors
> Show me all traces from the last hour that contain error spans

# Analyze latency distribution
> What is the p95 latency for the /api/checkout endpoint over the past 24 hours?

# Investigate a specific trace
> Find the trace for request ID abc-123 and show me the full span tree

Core Concepts

Concept	Purpose	Details
Traces	End-to-end request tracking	A trace represents a complete request journey across services, composed of individual spans with timing and metadata
Spans	Individual operation records	Each span captures a single operation within a trace, including duration, status, attributes, and parent-child relationships
Metrics	Aggregated measurements	Counters, histograms, and gauges that summarize application behavior over time windows
Read Token	Secure authentication	A scoped API token that grants read-only access to your Logfire project telemetry data
Queries	Data retrieval interface	Structured queries against trace and metric data with filtering by service, time range, and attributes

Architecture:

+------------------+       +----------------+       +------------------+
|  Your Services   |------>|   Logfire       |------>|  Logfire MCP     |
| (OTel SDK)       | traces| Platform        | API  |  Server (uvx)    |
+------------------+       +----------------+       +------------------+
                                                            |
                                                     stdio  |
                                                            v
                                                    +------------------+
                                                    |  AI Assistant    |
                                                    |  (Claude, etc.)  |
                                                    +------------------+

Configuration

Parameter	Type	Default	Description
read-token	string	(required)	Read-only API token generated from your Logfire project settings
base-url	string	https://logfire.pydantic.dev	Base URL for the Logfire API endpoint
project	string	(auto-detect)	Specific Logfire project to query when multiple projects exist
timeout	integer	30	Request timeout in seconds for API calls to the Logfire platform
log-level	string	info	Logging verbosity for the MCP server process (debug, info, warn, error)

Best Practices

1. Use read-only tokens exclusively. Never configure write-capable tokens for the MCP server. Read-only tokens ensure that AI assistants can query observability data without any risk of modifying trace data, deleting projects, or altering alert configurations. Generate dedicated tokens for MCP usage separate from your CI/CD tokens.

2. Scope queries with time ranges. Always include explicit time boundaries when querying traces and metrics. Unbounded queries against large telemetry datasets can be slow and return overwhelming amounts of data. Start with narrow windows like the last hour and expand only when needed for trend analysis.

3. Leverage structured attributes for filtering. OpenTelemetry spans carry rich attribute metadata such as service name, HTTP method, status code, and custom business attributes. Use these attributes in your queries to narrow results precisely rather than scanning through all spans manually.

4. Rotate tokens on a regular schedule. Treat your Logfire read tokens like any other credential. Rotate them quarterly, and immediately revoke any token that may have been exposed in logs, configuration files, or version control systems.

5. Combine trace and metric queries for full context. When investigating an incident, start with high-level metrics to identify the time window and affected services, then drill into specific traces for detailed span-level analysis. This top-down approach is more efficient than starting with individual traces.

Common Issues

"Authentication failed" when connecting. This typically occurs when the read token has expired or was copied incorrectly. Verify the token in your Logfire dashboard under project settings. Ensure there are no trailing whitespace characters in the token string. If you recently regenerated the token, update your MCP configuration and restart the client.

Queries return empty results despite active services. Confirm that your application services are correctly instrumented with the OpenTelemetry SDK and are sending data to your Logfire project. Check the Logfire web dashboard directly to verify data ingestion. If data appears in the dashboard but not through MCP, the issue may be a project scope mismatch in your configuration.

Slow response times on large trace queries. Logfire stores substantial volumes of telemetry data, and broad queries without filters can be resource-intensive. Add service name filters, time range constraints, and status filters to your queries. If you consistently need wide-ranging historical analysis, consider using Logfire's built-in analytics features alongside the MCP server.