Connect via MCP

Connecting through MCP

Once you generate a token, ADD UMTRI MCP appears right below it with commands ready for a range of AI agents. Each copied command already contains the token you just generated — click a button to copy it, then run it in your terminal to connect. Each service’s buttons come in two kinds: Global and Local (Project). (JSON config is a single button that copies the whole config.)

• Global: adds the MCP so it is available everywhere. You don’t have to add it per project, but every project on that computer can read your grounds with this token — and edit them too, if it is a Write token.
• Local: adds the MCP only to the project where you run the command. Safer, but you have to add the MCP again in every project that needs it. In Codex this option is labeled Project.

Umtri hosts a Model Context Protocol server at https://mcp.umtri.io. Point any MCP client at this address and pass your umtri_pat_… token as a Bearer header. Nothing to clone or install — just generate a token and add the MCP.

Claude Code

claude mcp add --transport http umtri https://mcp.umtri.io \
  --header "Authorization: Bearer umtri_pat_xxxxxxxxxxxxxxxx"

Use --scope user to apply it to every project (Global), or --scope local for the current project only (Local). Once connected, claude mcp list shows umtri: ✓ Connected, and inside a session /mcp shows the tool list and status.

Gemini CLI

gemini mcp add --transport http \
  --header "Authorization: Bearer umtri_pat_xxxxxxxxxxxxxxxx" \
  umtri https://mcp.umtri.io

Scope with --scope user (global) or --scope project.

Codex

Codex references the token through an environment variable. Set it, then add the server to ~/.codex/config.toml (global) or .codex/config.toml (project):

export UMTRI_API_TOKEN="umtri_pat_xxxxxxxxxxxxxxxx"

# ~/.codex/config.toml
[mcp_servers.umtri]
url = "https://mcp.umtri.io"
bearer_token_env_var = "UMTRI_API_TOKEN"

Any MCP client (JSON)

Clients that take a config object use the same shape:

{
  "mcpServers": {
    "umtri": {
      "type": "http",
      "url": "https://mcp.umtri.io",
      "headers": { "Authorization": "Bearer umtri_pat_xxxxxxxxxxxxxxxx" }
    }
  }
}

Run it locally (stdio)

If you’d rather run the server yourself — to pin a version or connect to a self-hosted API, for example — the umtri-mcp package runs over stdio. The client passes UMTRI_API_TOKEN as an environment variable.

claude mcp add umtri \
  -e UMTRI_API_TOKEN=umtri_pat_xxxxxxxxxxxxxxxx \
  --transport stdio \
  -- npx -y umtri-mcp

You can find the source here: github.com/bepuljang/umtri-mcp — Apache-2.0.

Other variables

• UMTRI_API_BASE — defaults to https://api.umtri.io. Change it only when you self-host the API.

Checking the connection

Whichever client you use, ask your agent “Show me my Umtri grounds”. If it comes back with your list of grounds, you’re connected.