How do I ask the Codex CLI to investigate crash loops with Tares?

Tares lets the Codex CLI investigate crash loops over MCP: you register the Tares endpoint with codex mcp add, then ask what happened to the service in the last 15 minutes. Codex calls the read tool and answers from one correlated timeline of that service’s logs, metrics, alerts and findings. Nothing else needs installing in Codex, and the same question works for any service whose data Tares ingests.

How it works

This is the pull side of Tares: you ask, and the agent reads on demand.

• Tares exposes an MCP endpoint. On your machine it is http://localhost:8788/mcp. On your own server it is https://<your-domain>/mcp. On Tares Cloud it is shown under Connect in your console.
• Codex discovers the Tares tools once the server is registered.
• When you name a service, Codex calls read. The tool returns a time-ordered timeline across all sources that match a label selector, for example service set to api-server. Metrics, logs and alerts for that service arrive merged on one clock.
• Findings recorded earlier, by a Tares agent or an outside agent, appear in the same read. Codex starts from the previous conclusion instead of from scratch.

For a crash loop, this means Codex sees what your sources carry about the failing service in one answer, instead of querying each system separately. The timeline works when your logs, metrics and alerts for that service share the same service label, which is how the AI SRE guide wires them.

Set it up

1. Start Tares locally, then start the MCP server in a second terminal. The daemon alone does not serve /mcp.

tares up
tares mcp

2. Register the endpoint with Codex. Keep --url before the URL, because a bare URL registers a stdio server.

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

3. Connecting to a secured server or a Tares Cloud instance? Use your own endpoint. Codex reads the credential from an environment variable. Prefer a scoped API key with the read scope over 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

4. Verify the connection. Ask Codex:

Use tares: what are you ingesting right now?

Codex should call catalog_list and answer with your sources, triggers and projects. In the console, Reads lists each read as it happens, tagged client = mcp.

5. Ask about the crash loop. Name the service and the window:

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

Codex calls read for that service and answers from the correlated timeline. Replace api-server with the service that is restarting. If you want a narrower look, ask Codex to read only certain sources, since read accepts a sources argument.

6. Follow up in the same session. Ask what changed before the first failure, or whether an alert fired. Because deploys and config changes can be ingested through a webhook source with the same service label, a change that landed just before the restarts shows up on the same timeline.

What you get

• One question gives you one correlated answer for the service, with logs, metrics, alerts and findings in time order.
• Codex works from evidence in the timeline, so you can ask it to tie the failure to specific lines.
• Earlier findings are part of the read. If a Tares agent already wrote a first look, Codex builds on it.
• Codex can write back. With a key that allows it, it can use record_finding to leave its conclusion on the entity, or remember to save an observation, so the next investigation starts further along.
• Codex can use create_trigger to be woken the next time the same thing happens.
• You can check what it read. Every read is listed under Reads in the console.

When something else fits

• If you want the investigation to start without anyone asking, use a trigger that wakes a Tares agent or your own agent service. This is the push side, described in the AI SRE guide.
• If you work in Claude Code, Cursor or another MCP client, or want a key scoped to one project, see Connecting agents for each client’s setup and the authentication options.
• If you want to explore without an external client, use Ask in the console, which runs the same read tools inside Tares.

Related