MCP¶
anthrogo implements the Model Context Protocol (MCP) client with four transport types. Add servers to ~/.anthrogo/settings.yaml under mcpServers:.
Quick start¶
mcpServers:
filesystem:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
type defaults to stdio. Tools surface as mcp__<server>__<tool> (names exceeding 64 chars get a sha-8 suffix).
Four transports¶
| Type | Use case | Key field |
|---|---|---|
stdio (default) |
Local subprocess | command, args |
sse |
2024-11-05 SSE remote | endpoint |
streamable |
Streamable HTTP remote | endpoint |
websocket |
Custom WS (ws:// or wss://) | endpoint, subprotocols |
Full config examples:
mcpServers:
# stdio (default)
filesystem:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
# streamable HTTP
remote-fetch:
type: streamable
endpoint: https://example.com/mcp
max_retries: 3
headers:
X-Api-Key: env:MY_API_KEY
# legacy SSE
legacy-sse:
type: sse
endpoint: https://legacy.example.com/mcp
headers:
Authorization: "Bearer static-token"
# WebSocket
ws-server:
type: websocket
endpoint: wss://example.com/mcp
subprotocols: ["mcp"]
headers:
X-Tenant-Id: "acme"
Headers¶
headers injects arbitrary HTTP headers on every outgoing request for sse, streamable, and websocket transports.
- Values support
env:VARNAMEexpansion (resolved once at startup):X-Api-Key: "env:MY_API_KEY"reads$MY_API_KEY /mcp status <name>redacts sensitive values — any key containingauthorization,auth,token,key,secret,password, orbearer(case-insensitive) shows as<redacted>
When oauth: is also set, headers are applied first and the OAuth Authorization: Bearer is layered on top.
OAuth 2.1 PKCE¶
For HTTP/WebSocket servers requiring authentication:
mcpServers:
api-with-oauth:
type: streamable
endpoint: https://example.com/mcp
oauth:
authorization_url: https://example.com/oauth/authorize
token_url: https://example.com/oauth/token
client_id: my-anthrogo-app
scopes: [mcp.read, mcp.write]
redirect_port: 8765 # local loopback for the OAuth callback (default 8765)
# client_secret: optional for confidential clients
Flow when oauth: is set:
1. Checks ~/.anthrogo/oauth/<server-name>.json for a cached token
2. If valid (not expired within a 30s margin), reuses it
3. If expired with a refresh_token, attempts a refresh-token grant
4. Otherwise: opens the browser to authorization_url, starts a local HTTP listener on redirect_port, exchanges the code + PKCE verifier for tokens, caches the result
5. Access token injected as Authorization: Bearer <token> on every request
WebSocket subprotocols¶
subprotocols (websocket only) advertises listed subprotocols during the WebSocket handshake (Sec-WebSocket-Protocol). The server's chosen subprotocol is echoed back.
MCP resources¶
anthrogo lists resources advertised by Ready servers in the system prompt at startup. The model uses the built-in MCPResource tool to access them:
// List resources on a server
{"server": "filesystem"}
→ [{uri, name, description, mime_type, size}, ...]
// Read a resource
{"server": "filesystem", "uri": "file:///tmp/notes.md"}
→ resource text
MCPResource has a default alwaysAllow rule (read-only; deny rules and PreToolUse hooks still take precedence).
Elicitations¶
When an MCP server sends an elicitation/create request, TUI users get a form modal:
- Multi-field mode: schema is a flat
objectwith all primitive properties (string,number,integer,boolean) orenumstring arrays. Each property renders as its own input row. Tab/Shift-Tab moves focus; Enter submits; Esc cancels. Schemadefaultvalues pre-fill buffers. - Single-textarea fallback: schemas with nested objects, arrays, or multi-select enums fall back to a JSON-blob textarea. Type a JSON object matching the schema, press Enter.
Headless mode (-p) always declines. Disable elicitation capability per-server:
mcpServers:
filesystem:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
elicitation_mode: "disabled"
Slash commands¶
/mcp # list all servers and their status
/mcp status <name> # show one server's last error and headers (redacted)
/mcp reload # remove and re-register all mcp__* tools
Note: /mcp reload re-registers tools but the model's system prompt is built at startup — restart anthrogo to refresh model awareness of newly-added servers.
Plan mode¶
Plan mode blocks all MCP tool calls (mcp__* tools are treated as write tools). Use /mode default to invoke MCP tools.
list-changed notifications¶
anthrogo registers notifications/tools/list_changed handlers. When a server pushes the notification, anthrogo refreshes its per-server tool cache and logs the event. The model-facing tool registry is NOT auto-rebuilt (would race with in-flight turns); run /mcp reload to surface new tools.