Skip to content
tcpsystems
Version: Current

MCP setup

This guide explains how to configure an MCP client to use the tcpsystems MCP endpoint.

Current status

Section titled “Current status”

The MCP endpoint is currently dead until restored (verified 2026-11-05). The server at https://mcp.tcp.systems/mcp exists but is not accepting connections. This guide documents the intended setup for when the service is restored.

What MCP is

Section titled “What MCP is”

The Model Context Protocol (MCP) endpoint exposes tcpsystems operations to AI agents and MCP-compatible clients. It uses the same internal/actions surface as the CLI, so commands and MCP tools cannot drift.

Endpoint: POST https://mcp.tcp.systems/mcp

Authentication

Section titled “Authentication”

The MCP endpoint requires OIDC bearer tokens:

Authorization: Bearer <access_token>

Tokens are verified against the issuer’s JWKS with both iss (issuer) and aud (audience) checked. Missing or invalid tokens receive HTTP 401 with WWW-Authenticate.

Getting a token

Section titled “Getting a token”

Use the CLI to obtain a token:

Terminal window
tcp login

The token is stored in ~/.local/state/tcp/token.json (mode 0600). For MCP clients, you may need to extract it:

Terminal window
cat ~/.local/state/tcp/token.json | jq -r '.access_token'

Authorization scopes

Section titled “Authorization scopes”

Every tool declares a scope. A principal lacking the required scope gets a tool-level error (isError: true) naming the missing scope.

scope grants
studio:read read projects, runs, deployments, templates, connections, usage, harness versions/status
studio:write create a project
studio:run cancel/steer a run, read the run feed
studio:deploy deploy, roll back, start a preview
admin:keys list, mint, revoke API keys
acumen:models list models
acumen:operator model capacity and gateway usage
acumen:search web search
status:read suite status

* grants everything; studio:* grants the studio: subtree. Scopes are read from scope or scp in the token.

Rate limits

Section titled “Rate limits”
  • Per account: 120 calls/minute, burst 30
  • Limited calls receive HTTP 429 with Retry-After

Example: tools/list request

Section titled “Example: tools/list request”
Terminal window
TOKEN=$(cat ~/.local/state/tcp/token.json | jq -r '.access_token')


curl -sS https://mcp.tcp.systems/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Response shape:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "studio_projects_list",
        "description": "...",
        "inputSchema": {...}
      }
    ]
  }
}

Available tools

Section titled “Available tools”

Tools are grouped by domain:

  • projects: studio_projects_list, studio_projects_get, studio_projects_create
  • runs: studio_runs_list, studio_runs_get, studio_runs_cancel, studio_runs_steer, studio_runs_events
  • deploys: studio_deployments_list, studio_deployments_get, studio_deploy_start, studio_deploy_rollback, studio_deploy_targets
  • previews: studio_preview_start, studio_preview_get
  • catalogue: studio_templates_list, studio_connections_list, studio_connections_kinds, studio_usage, studio_harness_versions, studio_harness_status, studio_harness_pins
  • keys: studio_keys_list, studio_keys_create, studio_keys_revoke
  • models: acumen_models, acumen_models_capacity, acumen_models_usage, acumen_search
  • suite: suite_status

Resources

Section titled “Resources”

The MCP server also exposes resources:

URI content
tcp://catalog/tools every tool, its scope and whether it is read-only (JSON)
tcp://docs/cli command surface and global flags
tcp://docs/exit-codes the exit-code contract
tcp://docs/mcp protocol documentation

Example:

Terminal window
curl -sS https://mcp.tcp.systems/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"tcp://catalog/tools"}}'

Protocol details

Section titled “Protocol details”
  • Versions: 2025-06-18, 2025-03-26, 2024-11-05
  • Methods: initialize, notifications/initialized, ping, tools/list, tools/call, resources/list, resources/read, prompts/list
  • Batching: JSON arrays are answered in request order; notifications (no id) produce no reply
  • Transport: JSON responses (no SSE response stream)
  • Stateless: DELETE /mcp answers 204; GET /mcp answers 405 with Allow: POST, DELETE

Troubleshooting

Section titled “Troubleshooting”

401 Unauthorized

Section titled “401 Unauthorized”

Your token is missing, expired, or invalid. Re-authenticate:

Terminal window
tcp login

403 Forbidden (missing scope)

Section titled “403 Forbidden (missing scope)”

Your token lacks the required scope. Request additional scopes during login or contact the owner to adjust your permissions.

429 Too Many Requests

Section titled “429 Too Many Requests”

You’ve hit the rate limit. Wait for the duration in Retry-After header.

Connection refused

Section titled “Connection refused”

The MCP endpoint is currently not accepting connections. Check the MCP product status page for updates.

Audit

Section titled “Audit”

Every tools/call and resources/read writes one JSONL row under TCP_MCP_AUDIT_DIR (0600, day-partitioned). The audit record includes: account, subject, tool, scope, outcome, code, duration, and a 12-hex digest of the arguments. Argument values and credentials are never stored.

Next steps

Section titled “Next steps”