← All guides

Query your traces from Claude Code, Codex, and other agents

simpletel mcp is a stdio Model Context Protocol server built into the CLI. Register it once and your coding agent can list traces, open one, run the onboarding check, and read account usage through its own tool channel — without shelling out.

What you get: five read-only tools

The server advertises five tools. Every tool returns text — the JSON document the matching CLI command produces — and tool-side failures come back as a normal result with isError: true, so a bad call never breaks the session.

get_traces, get_trace, get_signals, and verify are team-scoped; usage is account-scoped and needs a logged-in user token.

Install and register

The subcommand is simpletel mcp. Install the CLI, sign in, create a team, then register the server with your client:

curl -fsSL https://simpletel.dev/install | sh
simpletel login                 # GitHub device flow
simpletel team create --name my-app
claude mcp add simpletel -- simpletel mcp

It takes the connection flags --endpoint, --team, --admin-token, and --config, with the same precedence as every other read command (flag > environment variable > config file > default). Logged in locally, it reads ~/.simpletel/config.toml; to pin it to a 20-hex team id instead: claude mcp add simpletel -- simpletel mcp --team <20-hex-team-id>. Any JSON-configured client (Claude Desktop, Cursor, Cline, Windsurf) works the same way:

{"mcpServers":{"simpletel":{
  "command":"/Users/you/.simpletel/bin/simpletel",
  "args":["mcp"],
  "env":{"SIMPLETEL_ENDPOINT":"https://simpletel.dev","SIMPLETEL_TEAM":"<20-hex-team-id>"}
}}}

Or run the container

The published image bundles the CLI and runs simpletel mcp for linux/amd64 and linux/arm64:

docker run -i --rm ghcr.io/willnewby/simpletel-mcp

The transport is stdio, so -i is required and -t must not be added. The image runs as the distroless nonroot user (uid/gid 65532) with HOME=/home/nonroot. Pass credentials through the environment (recommended — nothing is written to the image), or mount a config file read-only and run the container as the file's owner so a mode-0600 file stays readable: --user "$(id -u):$(id -g)".

What the handshake advertises

The server speaks newline-delimited JSON-RPC 2.0 on stdin/stdout. initialize reports protocol revision 2025-06-18, capabilities.tools, and serverInfo named simpletel; tools/list returns the five tools above. stdout carries protocol messages only — every diagnostic goes to stderr — so a client that pipes the two streams can never mistake a log line for a response.

Why stdio, not a URL

A stdio MCP server is launched by the client as a subprocess and speaks over pipes. There is no port to expose, no public endpoint to secure, and no bearer token to pass around: the connection — endpoint, team, and the stk_… user token — stays in your local ~/.simpletel/config.toml (mode 0600, written by simpletel login). That is also the tradeoff, stated plainly: a stdio server only serves the process that spawned it, which is why the registry lists it as an OCI package with a stdio transport rather than a remote endpoint.

A worked example

Ask your agent "what just happened?" and it calls get_traces over the default 1-hour window, picks out the failing or slow request, then passes that trace_id to get_trace for the full span tree. verify is the same exit-code gate the CLI uses: it polls until service has a fresh, library-instrumented trace and returns the pipe/identity/richness rung report with an exit status — a deadline miss is a completed check (status 1), not a tool error. usage answers with the account's plan and month-to-date records, so the agent can name the ceiling before hitting it. Because each tool returns the document the CLI's --format json prints, what an agent reads over MCP is the same text you would see running simpletel get traces --format json in a terminal — one read path, not a second implementation to keep in sync.

Finding it without the CLI

As of October 2026 the server is published in three places. The official MCP registry entry is io.github.willnewby/simpletel — an OCI package with a stdio transport (the registry hosts metadata and points at the image, it does not host the server). The public MIT repository is github.com/willnewby/simpletel-mcp, and the public multi-arch image is ghcr.io/willnewby/simpletel-mcp. The CLI path remains the shortest: the same server is built into the binary, so there is nothing else to install.

Honest limits

stdio only. simpletel mcp is launched as a subprocess by the client; it is not an HTTP or SSE endpoint.

Read-only. The tools query traces, usage, and onboarding state. They never ingest data or change account settings.

A team is required for trace tools. With no resolvable team, every team-scoped call returns isError: true with "team is required (--team, SIMPLETEL_TEAM, or `simpletel login` + `team create`)". That is not a crash: initialize and tools/list still answer, so the agent always sees the tool catalog and can report the real problem.

usage needs a user token. It is account-scoped, so it needs a logged-in stk_… token (from simpletel login or SIMPLETEL_TOKEN) — the team-scoped tools do not.

Troubleshooting