MCP server

Sockudo ships a Model Context Protocol (MCP) server so agents such as Claude can inspect and operate a deployment through a typed, permissioned tool surface instead of raw HTTP calls. The protocol layer is the official rmcp SDK; Sockudo adds signed API access, scopes, tools, resources, and prompts.

Two deployment shapes share the same code:

Every tool call passes through the same validation, idempotency, rate limits, metrics, feature gates, and role restrictions as an external HTTP API caller. Tool results are the documented HTTP API response shapes, so anything learned from the HTTP API applies.

Enable the embedded server

Build with the feature and configure [mcp]:

cargo build -p sockudo --release --features "v2,mcp,redis,postgres"

[mcp]
enabled = true
path = "/mcp"
# port = 6100                 # optional dedicated listener (host defaults to the server host)
allowed_hosts = []            # empty = accept any Host (fine behind a trusted proxy)
allowed_origins = []          # browser origins; empty disables Origin checks
rate_limit_per_minute = 600   # per token; 0 disables
request_timeout_ms = 30000
session_ttl_seconds = 1800

[[mcp.tokens]]
name = "ops-agent"
token = "${SOCKUDO_MCP_OPS_TOKEN}"   # >= 16 chars; use env interpolation
scopes = ["read", "write"]
apps = ["*"]

[[mcp.tokens]]
name = "readonly-dashboard"
token = "${SOCKUDO_MCP_RO_TOKEN}"
scopes = ["read"]
apps = ["app-1"]

Validation refuses to start when enabled = true without tokens unless allow_anonymous = true (development only). MCP_TOKEN, MCP_TOKEN_NAME, MCP_TOKEN_SCOPES, and MCP_TOKEN_APPS add a token from the environment without touching the file; see Environment variables.

Clients connect with a bearer token:

curl -sS http://127.0.0.1:6001/mcp \
  -H "Authorization: Bearer $SOCKUDO_MCP_OPS_TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

Claude Code:

claude mcp add --transport http sockudo https://rt.example.com/mcp \
  --header "Authorization: Bearer $SOCKUDO_MCP_OPS_TOKEN"

Claude API (MCP connector):

{
  "mcp_servers": [{ "type": "url", "url": "https://rt.example.com/mcp", "name": "sockudo",
                    "authorization_token": "<token>" }],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "sockudo" }]
}

Standalone binary

cargo install --path crates/sockudo-mcp --features cli
# stdio for Claude Desktop / Claude Code
sockudo-mcp --url https://rt.example.com --app app-1:key:secret --scopes read,write
claude mcp add sockudo -- sockudo-mcp --url https://rt.example.com --app app-1:key:secret
# Streamable HTTP with tokens
sockudo-mcp --transport http --listen 127.0.0.1:6100 \
  --token 'ops/read+write=<32+ char token>' --url https://rt.example.com --app app-1:key:secret \
  --metrics-url http://rt.example.com:9601/metrics

Credentials may also come from SOCKUDO_URL, SOCKUDO_MCP_APPS (id:key:secret,...), or SOCKUDO_APP_ID / SOCKUDO_APP_KEY / SOCKUDO_APP_SECRET. Logs go to stderr; stdout is the protocol channel.

Scopes and safety

• tools/list only returns tools the token may call; calling a hidden tool returns JSON-RPC -32003.
• Destructive tools require confirm: true and a reason, which the server records.
• Tokens carry an app allow-list; requests for other apps fail with -32003.
• App secrets never leave the server. sockudo_list_apps and sockudo_get_app return keys and sanitized policy only; webhook headers are redacted.
• Every call emits an audit log line on target sockudo_mcp::audit with principal, tool, app, channel, outcome, and latency.
• Upstream API errors are returned as isError results carrying the server's JSON error body so the agent can read code and error and recover.

Tools

Hide tools with disabled_tools = ["sockudo_purge_history"]. Tools that hit a feature the server does not enable (for example push without the push feature) return the server's feature_disabled or 404 error rather than failing at startup.

Resources and prompts

Resources use the sockudo:// scheme: server/info, server/health, server/stats, apps, apps/{app_id}, apps/{app_id}/channels[/{channel}[/history|/presence|/messages/{serial}]], plus embedded references docs/http-api, docs/channels, and docs/operations. Prompts sockudo_debug_channel, sockudo_incident_triage, sockudo_design_realtime_feature, and sockudo_audit_app_security walk an agent through common workflows. Argument completion is available for app_id and channel.

Observability

Prometheus families (with the configured prefix):

Testing

• cargo test -p sockudo-mcp --all-features runs protocol, signing, catalog, and Streamable HTTP transport tests; cargo test -p sockudo --features mcp mcp:: drives the in-process transport through the real API middleware.
• make mcp-smoke builds both binaries, starts a scratch server from tests/mcp/config.toml, and runs tests/mcp/smoke_http.py (embedded endpoint, admin and read-only tokens) and tests/mcp/smoke_stdio.py (standalone binary over stdio).
• For interactive checks use npx @modelcontextprotocol/inspector against /mcp with the Authorization: Bearer header, or register the endpoint in Claude Code and call sockudo_server_info.

Performance notes

• The embedded transport never touches a socket: requests are signed and dispatched to the router with tower::Service::oneshot. Cost per call is one HMAC-SHA256, one MD5 for POST bodies, and the normal handler work.
• tools/list responses are prebuilt once per scope combination and served as an Arc clone.
• Responses are passed through as the server's JSON bytes; only object bodies are parsed once more to populate structuredContent.
• Sessions are managed by rmcp with idle expiry (session_ttl_seconds); the 2026-07-28 protocol revision is served statelessly.