# simpletel [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/willnewby/simpletel-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/simpletel

## Description
Query your simpletel OpenTelemetry traces and account usage from a coding agent.

## Tools
Capabilities this server exposes over MCP:

- **get_traces** — Lists this team's traces newest-first. The JSON document `simpletel get traces --format json` produces. Use it to find a failing or slow request.
- **get_trace** — Fetches one trace in full — spans, span events, and correlated log records. The JSON document `simpletel get trace <id> --format json` produces.
- **verify** — Runs the `simpletel verify` onboarding check: polls until `service` has a fresh trace carrying spans from a library instrumentation. Returns the rung report and the exit status (`0` verified, `1` deadline miss). A deadline miss is a completed check, not a tool error.
- **usage** — Shows the account's plan, month-to-date records, allowance, and spend cap. The JSON document `simpletel usage --format json` produces. Account-scoped (needs a logged-in user token).

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/simpletel/readme_