How do I connect the Codex CLI to Tares over MCP?

Tares connects to the Codex CLI with one command: codex mcp add tares —url followed by your Tares MCP endpoint. Codex then discovers the Tares tools and answers from the correlated timeline of logs, metrics, alerts and findings. On a secured instance, Codex reads the credential from an environment variable.

How it works

Tares serves its tools to any MCP client over streamable HTTP. Codex registers the Tares endpoint as a remote server, calls the tools when you ask a question, and reads one correlated, time-ordered timeline across your sources.

The endpoint depends on where Tares runs:

• Your machine (tares up): http://localhost:8788/mcp. The daemon alone does not serve /mcp, so you start the MCP server as a second process.
• Your own server: your domain with /mcp on the end, over HTTPS. The MCP server is already running.
• Tares Cloud: the endpoint is shown in your console under Connect. Each instance has its own hostname.

The console’s Connect page also generates the exact Codex command with the endpoint and token filled in.

On an open local instance (plain tares up), Codex needs no credential. On a secured instance, every server and Tares Cloud instance included, the MCP surface requires one. Use a scoped API key with the read scope rather than the root token. For an agent that should work inside one project only, use a project key, which reads that project and records findings in it and nothing else. The Connecting agents (MCP) page covers every client and the full tool list.

Set it up

1. Start the MCP server if you run Tares locally. Run this in a second terminal while tares up is running. On a server or Tares Cloud, skip this step.

   tares mcp --transport streamable-http --port 8788 --taresd http://localhost:8787

2. Add Tares to Codex. Run this in your terminal. Keep --url before the URL, because a bare URL registers a stdio server instead of an HTTP one.

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

3. For a remote, secured instance, pass the key through an environment variable. Replace the URL with your own endpoint. Codex reads the credential from the variable you name.

   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.

If you are running the demo, ask “what happened to api-server in the last 15 minutes?” and Codex answers from the correlated timeline.

What you get

• Codex can ask Tares about any entity on the fly. The read tool returns a timeline across all sources that match a label selector, and you can narrow it by project or by sources.
• Codex can browse what exists with catalog_list and catalog_describe, and check source health with list_sources.
• Codex can write back. With a key that has the matching scope, it can create a trigger so it is woken when something happens again, save an observation with remember, and record a finding with record_finding.
• Codex can set up sources conversationally. discover_source proposes a config, test_source dry-runs it, and create_source starts ingestion immediately.
• A read key gets the read surface only. Writing, such as ingest or source management, needs the matching scope, so you decide how much Codex can change.

For how Tares fits into incident work as a whole, see AI SRE.

When something else fits

• Using Claude Code? The Tares plugin is the default path. One install wires the MCP read-back and session capture, or you can run claude mcp add --transport http against the same endpoint.
• Using Cursor? Add a tares entry with a url to mcp.json and approve the server under Settings → MCP.
• Want an answer without wiring up an external client? Use Ask in the Tares console, which has the read tools built in.

Related