jaeger-mcp

Read-only MCP server for querying Jaeger environments from Codex.

The server talks to Jaeger Query API over HTTP and returns compact, sanitized summaries instead of raw traces. This is important because production spans can contain sensitive values such as rpc.request.params, user text, emails, SQL text, headers, and provider payloads.

Environments

This repository does not ship real Jaeger URLs. Configure them locally through environment variables.

Logical environments:

• dev
• test
• preview
• prod

When two logical environments share the same Jaeger Query endpoint, use grouped URL variables:

export JAEGER_DEV_TEST_URL="<dev-test-jaeger-query-url>"
export JAEGER_PREVIEW_PROD_URL="<preview-prod-jaeger-query-url>"
export JAEGER_DEFAULT_ENV="dev"
export JAEGER_TIMEOUT_SECONDS="20"

JAEGER_DEV_TEST_URL configures both dev and test. JAEGER_PREVIEW_PROD_URL configures both preview and prod.

Explicit per-environment variables override grouped variables:

export JAEGER_DEV_URL="<dev-jaeger-query-url>"
export JAEGER_TEST_URL="<test-jaeger-query-url>"
export JAEGER_PREVIEW_URL="<preview-jaeger-query-url>"
export JAEGER_PROD_URL="<prod-jaeger-query-url>"

For custom environments:

export JAEGER_ENVIRONMENTS='{"dev":"<dev-jaeger-query-url>","prod":"<prod-jaeger-query-url>"}'

For headers:

export JAEGER_HEADERS='{"X-Debug":"1"}'
export JAEGER_PROD_HEADERS='{"Authorization":"Bearer ..."}'

Run

From this repository:

python3 -m jaeger_mcp.server

For Codex MCP configuration, point the command at the source tree without installing:

{
  "mcpServers": {
    "jaeger": {
      "command": "python3",
      "args": ["-m", "jaeger_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/jaeger-mcp/src"
      }
    }
  }
}

Replace /path/to/jaeger-mcp with the local checkout path on the machine running Codex.

Tools

• jaeger_list_services(env?)
• jaeger_list_operations(env?, service, span_kind?)
• jaeger_search_traces(env?, service, operation?, lookback?, start_us?, end_us?, min_duration?, max_duration?, limit?, tags?)
• jaeger_search_error_traces(env?, service, operation?, lookback?, limit?)
• jaeger_get_trace_summary(env?, trace_id, max_error_spans?, max_slow_spans?)
• jaeger_find_error_spans(env?, trace_id, max_spans?, include_logs?)
• jaeger_get_span_detail(env?, trace_id, span_id, include_logs?)

Design boundaries

• Read-only only.
• Default output is JSON text suitable for Codex reasoning.
• Raw tags are not returned wholesale.
• Sensitive keys are redacted or omitted.
• Long strings are truncated.
• Trace search is capped by JAEGER_MAX_LIMIT with a default cap of 50.

Code layout

• server.py: stdio entrypoint.
• rpc.py: JSON-RPC request handling.
• tools.py: MCP tool schemas and dispatch.
• client.py: Jaeger Query API client and tool implementations.
• trace_analysis.py: span classification, summaries, and trace URLs.
• redaction.py: sensitive-key detection and output sanitization.
• config.py: local environment-variable configuration.

Local tests

python3 -B -m unittest discover -s tests