How do I ask the Codex CLI to investigate 5xx errors on an API with Tares?

Tares lets the Codex CLI investigate 5xx errors on an API once you register the Tares MCP endpoint with codex mcp add and ask what happened to the service in the last 15 minutes. Codex calls the read tool and answers from one correlated, time-ordered timeline of logs, metrics, alerts and findings. You get the 5xx evidence for that service in a single read, with no per-system queries.

How it works

Tares ingests your metrics, logs and alerts into sources that share a service label. All sources carrying the same service value merge into one timeline per service, on one clock. For example, the 5xx rate from Prometheus, the request logs from the container and the alerts that fired all sit side by side for api-server.

Codex connects to Tares over MCP. When you ask about a service, it calls read with a selector such as {"service": "api-server"}. Tares returns the matching events from all sources as one timeline, and Codex answers from it. The timeline also includes findings that Tares agents or other agents recorded earlier, so Codex starts from the previous conclusion instead of from scratch.

This is the pull side: you ask when you want to investigate. The AI SRE guide also covers the push side, where a trigger wakes an agent for you.

Set it up

1. Have your API’s signals in Tares, keyed by service. Use a prometheus source for metrics such as the 5xx rate, a log source such as docker_logs or OTLP for request logs, and prometheus_alerts or alertmanager for alerts. Give each source a service label. The AI SRE guide walks through this end to end, including a demo system you can run on a laptop.

2. Start Tares and its MCP endpoint. A local tares up does not serve /mcp by itself, so run the MCP server in a second shell:

tares up
tares mcp

The endpoint is http://localhost:8788/mcp. On your own server it is your domain followed by /mcp. On Tares Cloud the console shows it under Connect, and the MCP server is already running.

3. Register Tares with Codex. Keep --url before the URL, because a bare URL registers a stdio server:

codex mcp add tares --url http://localhost:8788/mcp

4. On a secured instance, pass a key. Codex reads the credential from an environment variable. Use an API key with the read scope rather than the root token:

export TARES_API_KEY=<api-key>
codex mcp add tares --url https://<your-host>/mcp \
  --bearer-token-env-var TARES_API_KEY

On an open local instance you need no credential.

5. Verify the connection. Ask Codex: Use tares: what are you ingesting right now? It calls catalog_list and answers with your sources, triggers and projects. In the console, Reads lists each read as it happens, tagged client = mcp.

6. Ask about the 5xx errors. Name your service:

   Use tares: what happened to api-server in the last 15 minutes?

   Codex calls read with your service label and answers from the correlated timeline. To dig further, ask it to look at just the metrics and alert sources, which it does by passing sources to read. Replace api-server with the value of your own service label.

What you get

• One answer built from metrics, logs, alerts and findings together, so a 5xx spike appears next to the error logs and the alert that fired for it.
• A read scoped to one service, so Codex does not wander through unrelated systems.
• Continuity between investigations. If an agent recorded a finding on the service, Codex reads it along with the evidence.
• Visibility on your side. Each read shows up under Reads in the console, tagged client = mcp.
• A path to write back. Codex can use remember to store what it found, so the next investigation starts smarter.

When something else fits

• If you want to be woken when 5xx errors start rather than ask after the fact, add a trigger and a Tares agent or webhook, as the AI SRE guide describes.
• If you would rather not wire an external client, the console includes Ask, which runs the same read tools inside Tares.
• If you use Claude Code, Cursor or another MCP client, the agents page has the exact connect command for each.

Related