Simpletel README

simpletel-mcp

Model Context Protocol server for simpletel — ask your coding agent "what just happened?" and let it read the OpenTelemetry traces, logs, metrics, and account usage of your running services.

simpletel mcp is a stdio MCP server built into the simpletel CLI. It speaks newline-delimited JSON-RPC 2.0 on stdin/stdout (MCP protocol revision 2025-06-18) and exposes simpletel's read commands as native agent tools. It is a single static binary: no runtime, no dependencies, no background service.

• One-line install of the CLI: curl -fsSL https://simpletel.dev/install | sh
• Run it as simpletel mcp
• Or use the container: ghcr.io/willnewby/simpletel-mcp
• Registry name: io.github.willnewby/simpletel

Tools

The server advertises four 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 — a tool call never breaks the session.

get_traces, get_trace, and verify are team-scoped; usage is account-scoped.

Authentication and team resolution

The server resolves one connection at startup, using the same precedence as every other simpletel read command: **flag > environment variable > config file

default**.

• The config file is ~/.simpletel/config.toml, written by simpletel login and simpletel team (mode 0600). simpletel login signs you in with GitHub; simpletel team create / simpletel team use set the current team.
• --team accepts either a 20-hex team id — used verbatim, no token needed — or a friendly name. A name is resolved only, never created, and needs an admin token to look it up.
• usage additionally needs a user token: run simpletel login, or set SIMPLETEL_TOKEN (a stk_… token).

If the team is missing or wrong the server still answers initialize and tools/list, so the client sees the tool catalog; each team-scoped call then reports the problem as its own isError result.

Nothing is ever sent to simpletel by this server beyond the read requests the tools make to the endpoint you configure. Diagnostics go to stderr; stdout carries protocol messages only.

Install

1. Install the CLI

curl -fsSL https://simpletel.dev/install | sh

Installs simpletel into ~/.simpletel/bin/ (verify the sha256; no sudo, never prompts). Then sign in and create/select a team:

simpletel login            # GitHub device flow
simpletel team create --name my-team

2. Register the server with your client

The MCP subcommand is simpletel mcp. It takes the connection flags --endpoint, --team, --admin-token, and --config.

Claude Code

# by 20-hex team id (no extra credentials needed)
claude mcp add simpletel -- ~/.simpletel/bin/simpletel mcp --team <20-hex-team-id>

# or rely on the logged-in config file (~/.simpletel/config.toml)
claude mcp add simpletel -- ~/.simpletel/bin/simpletel mcp

Pass connection values as environment instead with --env:

claude mcp add simpletel \
  --env SIMPLETEL_ENDPOINT=https://simpletel.dev \
  --env SIMPLETEL_TEAM=<20-hex-team-id> \
  -- ~/.simpletel/bin/simpletel mcp

Claude Desktop / any JSON-configured client (claude_desktop_config.json, Cursor, Cline, Windsurf, …):

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

If you are logged in locally you can drop env and the command will read ~/.simpletel/config.toml. In a sandboxed client that cannot read your home directory, pass the values through env (or --env / --router equivalents) instead.

Docker

The image bundles the CLI and runs simpletel mcp. It is built for linux/amd64 and linux/arm64:

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

The container starts with no credentials. Provide them either by mounting the config file or through environment variables (recommended — nothing is written to the image).

Mount an existing config file (read-only). The image runs as the distroless nonroot user (uid/gid 65532) with HOME=/home/nonroot, so the CLI's default config path inside the container is /home/nonroot/.simpletel/config.toml. Because simpletel login writes that file mode 0600 for you, run the container as the file's owner so it stays readable:

docker run -i --rm \
  --user "$(id -u):$(id -g)" \
  -v "$HOME/.simpletel/config.toml:/home/nonroot/.simpletel/config.toml:ro" \
  ghcr.io/willnewby/simpletel-mcp:latest

(Passing the connection through -e below avoids the ownership question entirely and is the recommended path.)

Or pass everything through the environment:

docker run -i --rm \
  -e SIMPLETEL_ENDPOINT=https://simpletel.dev \
  -e SIMPLETEL_TEAM=<20-hex-team-id> \
  ghcr.io/willnewby/simpletel-mcp:latest

As a JSON client entry:

{
  "mcpServers": {
    "simpletel": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SIMPLETEL_ENDPOINT=https://simpletel.dev",
        "-e", "SIMPLETEL_TEAM=<20-hex-team-id>",
        "ghcr.io/willnewby/simpletel-mcp:latest"
      ]
    }
  }
}

The MCP transport is stdio, so -i (keep stdin open) is required and you must not add -t.

Configuration reference

simpletel mcp [--endpoint URL] [--team <id-or-name>] [--admin-token TOKEN] [--config PATH]

Limitations

• stdio only. simpletel mcp is launched as a subprocess by the client; it is not an HTTP/SSE endpoint.
• Read-only. The tools query traces, usage, and onboarding state. They do not ingest data or change account settings.
• The host CLI is required unless you use the container. The simpletel binary is fetched at build time by the Dockerfile; the repo ships no binary of its own — see Dockerfile for the build.
• Windows is not a first-class target of the one-line installer; use the Docker image or WSL.

Repository contents

License

MIT — see LICENSE.