Jaeger MCP server: nine read-only tools, off by default

Jaeger's own connector, compiled into the query service. Every one of the nine tools reads, and none is served until a configuration block turns the endpoint on.

Last verified 1 September 2026 · from Jaeger's own source, its architecture decision record and its CHANGELOG

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector that lets the agent query the tool directly.

What is the Jaeger MCP server?

Jaeger is a distributed tracing backend, and this server hands that store to an agent. It uses the Model Context Protocol, so Claude Code or Cursor can walk a trace without a browser.

The tools are shaped for drilling down rather than for mirroring the query API. Jaeger's own instructions tell the model to start broad with get_services or search_traces, then take a structural view with get_trace_topology, and only then ask for verbose span data.

One tool is not telemetry at all. read_skill serves markdown playbooks compiled into the binary, starting at SKILL.md. Two ship as standard, one for spotting N+1 query patterns and one for walking a failed trace to its root cause.

Jaeger sits in production observability. It reaches nothing in code review, CI and release, agent observability or AI cost management.

For an agent, that means Jaeger answers where a request spent its time and which service called which. There are no metrics and no logs, because Jaeger stores neither, so a full investigation needs a second connector. The critical path is worked out by Jaeger itself, in Go, not by the client.

What can an AI agent do with Jaeger?

Start with search_traces and get_trace_topology. Both are cheap in context, and Jaeger's own system prompt tells the model to use them before asking for verbose span data.

Jaeger MCP server limits: where answers come back incomplete

The three limits below are about the size of an answer rather than about damage. Every tool reads, so nothing here can change what Jaeger holds.

How to configure Jaeger MCP for agents

1. 1

   Add the ai.mcp block, or nothing is served

   It is absent from a default jaeger-query, and an empty mcp: {} under ai: is enough to register the route.

2. 2

   Point clients at the query port, not 16687

   The standalone jaeger_mcp extension had its own listener and was retired in v2.20.0.

3. 3

   Expect the limits to be fixed

   jaeger-query builds the tool configuration from DefaultConfig(), so 100 search results, 20 spans per detail call and a 512 KiB skill file are not tunable.

4. 4

   Add your own playbooks with ai.mcp.skills_dir

   They are served under custom/ beside the built-in ones, and a missing SKILL.md there stops Jaeger from starting.

Paste this into your agent’s instructions

Every tool reads, so the risk is not damage. It is an agent reporting a truncated or shallow result as though it were the whole picture.

When you answer using Jaeger MCP tools, state:
- The service, the trace ID and the time window the answer
  covers.
- The search_depth you used. It defaults to 10 traces and
  stops at 100.
- For get_trace_errors, whether total_error_count matches the
  number of spans returned. Above 20 the list is cut.
- Whether a claim came from a trace or from a read_skill
  playbook. A playbook is procedure, not measurement.
Never state that data does not exist. State that no traces
matched the query above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Yes, on a Jaeger of v2.20.0 or later, if anyone on the team reads traces by hand. It installs nothing, it costs one configuration block, and the nine tools do the drilling down that the Jaeger interface makes you click through.

The HTTP query API is still the right route inside a script. A fixed query repeated on a schedule needs no model, and GET /api/traces is what the agent would be told to call anyway.

Grafana's connector fits better when the question crosses from traces into metrics and logs, because it reaches Tempo and other datasources through one connection.

What MCP adds is the critical path: get_critical_path runs an algorithm the HTTP API does not expose, ported into Go from the Jaeger interface specifically so this server could offer it.

Enable it on the Jaeger you already run. Keep the query API for calls that are scripted and repeated.

Jaeger MCP server setup

There is nothing to install. The server is compiled into jaeger-query, so a Jaeger of v2.20.0 or later already carries it.

Add the ai.mcp block to the jaeger_query extension and restart. The endpoint then answers at <base_path>/api/ai/mcp/ on the query port, which Jaeger's own configuration example writes as 16686.

extensions:
  jaeger_query:
    ai:
      mcp: {}

claude mcp add --transport http jaeger \
  http://jaeger-query:16686/api/ai/mcp/

{"mcpServers":{"jaeger":{
  "url":"http://jaeger-query:16686/api/ai/mcp/"}}}

[mcp_servers.jaeger]
url = "http://jaeger-query:16686/api/ai/mcp/"

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

extensions:
  jaeger_query:
    ai:
      mcp:
        skills_dir: /etc/jaeger/skills

--set extensions.jaeger_query.ai.mcp.skills_dir=/etc/jaeger/skills

Read-only access, permissions and security

• Every tool reads

  The nine cover discovery, trace structure, span detail, the critical path and skill files. None writes to Jaeger and none changes a setting.

• Traces carry whatever your services put in them

  get_span_details returns attributes, events, links and status for a span, and all of it reaches the model.

• The endpoint inherits the query port's protection, and nothing else

  Folding it into jaeger-query removed a listener along with its own TLS and authentication settings.

• Multi-tenancy is enforced at the transport

  Tenant extraction wraps the MCP handler, so a tenant header is required wherever Jaeger is configured for one.

• read_skill reaches the disk when skills_dir is set

  It is bounded to the directory you name and to 512 KiB per file.

Troubleshooting

404 on /api/ai/mcp/

The ai.mcp block is missing. It is absent from a default configuration, and its presence is what registers the route. An empty mcp: {} under ai: is enough.

Connection refused on port 16687

That port belonged to the standalone jaeger_mcp extension, retired in v2.20.0. The tools now serve on the query port under /api/ai/mcp/.

get_span_details returns an error instead of spans

More than 20 span IDs in one call is refused with span_ids exceeds maximum limit. The cap is fixed at 20, so split the call rather than looking for a setting.

A search finds nothing that should be there

search_traces uses a search depth of 10 traces when the caller leaves it unset, and the handler caps it at 100. Raise search_depth before reading an empty result as an absence.

Jaeger refuses to start after setting skills_dir

A skills_dir that cannot be opened, or whose SKILL.md cannot be read, is treated as broken configuration. Jaeger fails at startup rather than serving an incomplete skill set.

Jaeger MCP server: Reference

What engineers report

The finding here is that the connector is Jaeger's own, and has been since v2.15.0. The counts below describe the project repository, because the server has no repository of its own.

The tool list was read on 1 September 2026 from mcptools/server.go in jaegertracing/jaeger, which holds nine mcp.AddTool calls. Release history comes from the project's own CHANGELOG. The community package mshegolev/jaeger-mcp still exists, at 1 star, and is not the subject of this page.

Should you connect an agent to Jaeger?

Yes. Best for a Jaeger you already operate, with the agent required to state the search depth behind any absence.

Strongest fit

Teams already running Jaeger v2.20.0 or later who want an agent to walk a trace without a browser.

Main advantage

It is the project's own code, already inside the binary you deploy, and every tool reads.

Main weakness

Traces only. There are no metrics and no logs, and the response limits are fixed rather than tunable.

Operational risk

Low. Nothing writes. The real risk is a truncated or shallow answer read as a complete one.

Frequently asked questions