Use the MCP server

Metergraph ships a stdio MCP server so a coding agent can ask what your routes are and what your recent traffic looked like, without you pasting numbers into a prompt. It is read-only, and it returns no prompt or model-output content at all.

Read this before you plan around it

You cannot mint the key this server needs from the dashboard today. Keys created in the dashboard always get the ingest scope, and the MCP server requires the agent:read scope, which only the operator command line can issue. The command runs with database access inside the deployment, so on the hosted service it is a request to Metergraph rather than something you can do yourself.

The metergraph-mcp command itself ships with the server package, which is not published to a public package index. If you run Metergraph yourself, locally or in your own AWS account, you already have both halves. If you are on the hosted service, you have neither yet.

What it is

A zero-dependency bridge that speaks newline-delimited JSON-RPC over stdio and forwards to two read-only HTTP endpoints. It targets MCP protocol revision 2025-11-25 and also accepts 2025-03-26 and 2025-06-18. It refuses redirects, so the bearer token cannot be walked to another origin, and it caps protocol messages at 1 MiB and API responses at 5 MiB.

The token is read from the process environment, never from a protocol message, and is never written to stdout or stderr.

The tools

metergraph_list_routes

No arguments. Returns every route in the workspace with its description, constraints, evaluation contract, last update, total call count, and how many of those calls are eligible for replay.

metergraph_query_traces

Recent traces, grouped by trace id, newest first.

Argument	Type	Range
route	string	1 to 512 characters
status	string	1 to 128 characters
days	integer	1 to 90, default 7
limit	integer	1 to 200, default 50

Anything else is rejected as an unknown argument. Each trace comes back with its name, first and last span times, span count, input, output and cache token totals, cost, a success or error status, and the distinct routes, providers and models it touched.

Content-free by construction

The response payload carries content_included: false, and that is not a promise, it is a description of the query: the endpoints behind these tools never select prompt text, response text, tool arguments or tool results. The one endpoint that does return content requires an authenticated dashboard session and rejects agent keys outright.

So an agent using this server can reason about cost, latency, failure and coverage, and cannot read your users’ data. That is the trade the scope exists to make.

Configure it

1. Get an agent:read key

   Issued by an operator, against your workspace slug:

   Operator command, not a customer command

   python -m metergraph_app.cli issue-key TENANT_SLUG \
     --label coding-agent --scope agent:read

   The token is printed once. It is an mg_ key like any other, but its scope lets it call only /v1/agent/routes and /v1/agent/traces. Ingest, the reporting API and every dashboard mutation reject it.

2. Point your MCP host at the command

   The token goes in the child process environment.

   .mcp.json

   {
     "mcpServers": {
       "metergraph": {
         "command": "metergraph-mcp",
         "env": {
           "METERGRAPH_URL": "https://metergraph.example.com",
           "METERGRAPH_AGENT_TOKEN": "replace-with-agent-token"
         }
       }
     }
   }

   METERGRAPH_URL must be an absolute HTTP or HTTPS URL with only a scheme, host and path. A query string, a fragment or embedded credentials are rejected at startup with exit code 2.

3. Check it responds

   The server answers initialize, ping and tools/list before any credential is used against the API, so a tools/list that comes back with two tools proves the wiring without proving the token.

Availability by deployment

The agent API is part of the managed and local capability sets. It is not available on the BYOC core profile, where the endpoints are gated off. See Choosing a deployment.

For coding agents What an agent should do with a Metergraph workspace it has been pointed at.

See also

• Manage your workspace for what the dashboard can and cannot mint
• Ingest API