Simpletel

What simpletel MCP server does

The simpletel MCP server connects an MCP-compatible coding client to a simpletel endpoint and exposes four read-only operations. It can list recent team traces, retrieve a complete trace, run an instrumentation verification check, and show account usage.

get_traces returns traces newest-first and supports filters for time range, service, errors, minimum duration, and result count. get_trace retrieves the spans, span events, and correlated log records for one trace. verify checks whether a service has produced a fresh trace containing spans from library instrumentation. usage reports the account plan, month-to-date records, allowance, and spend cap.

The three trace and verification operations are team-scoped. Usage is account-scoped and requires a logged-in user token.

How it works

The server is built into the simpletel CLI and starts with simpletel mcp. It communicates over stdio using newline-delimited JSON-RPC 2.0, so an MCP client launches it as a subprocess. Responses contain the JSON documents generated by the corresponding simpletel read commands. Tool-side failures are returned as MCP results marked with isError: true; they do not terminate the session.

Connection settings are resolved at startup in this order: command-line flag, environment variable, configuration file, then default. The endpoint defaults to http://localhost:4318. A team can be selected with a 20-character hexadecimal ID or a friendly name. Friendly-name resolution requires an admin token, while an ID can be used directly.

The verify tool returns both its rung report and exit status. Status 0 means verification succeeded; status 1 means the deadline was reached without verification, which is reported as a completed check rather than a tool failure.

Setup and configuration

Install the CLI with the provided shell installer, then run simpletel login and create or select a team. Register the executable and mcp subcommand in the client’s MCP configuration. Claude Code can add it with claude mcp add; JSON-configured clients can specify the executable as command and mcp as an argument.

The simpletel MCP server also has a container image at ghcr.io/willnewby/simpletel-mcp. Run Docker with interactive stdin (-i) and without a TTY. Credentials can be supplied through environment variables or a read-only mounted configuration file. The image supports linux/amd64 and linux/arm64.

Supported environment settings include SIMPLETEL_ENDPOINT, SIMPLETEL_TEAM, SIMPLETEL_ADMIN_TOKEN, SIMPLETEL_TOKEN, and SIMPLETEL_CONFIG. SIMPLETEL_TOKEN is specifically used by usage and accepts a user token beginning with stk_.

Tools and capabilities

• Find recent traces by service, error status, duration, time window, or limit.
• Inspect complete traces with spans, span events, and related logs.
• Check whether library instrumentation is producing trace spans for a service.
• Read account plan, record totals, allowance, and spend cap.
• Keep protocol output on stdout while sending diagnostics to stderr.

Limitations and notes

The simpletel MCP server is stdio-only; it does not provide an HTTP or SSE endpoint. It is read-only and does not ingest telemetry or change account settings. The host CLI is required unless the container image is used. The one-line installer is not a first-class Windows target, so Windows users should use Docker or WSL.

If the team setting is missing or invalid, the server still responds to initialization and tool-list requests, but team-scoped calls report the configuration problem individually. The server sends only the read requests made by its tools to the configured endpoint.