Connect MCP servers

Stable

MCP servers give octo extra tools — databases, ticket trackers, internal APIs — without writing a built-in tool for each one. Tools are on by default, so every configured server connects at session start; its tools, resources, and prompts ride alongside octo’s built-in tools as mcp__<server>__<tool>.

Add a server

Servers are declared in ~/.octo/mcp.json (user-global, always loaded) or ./.octo/mcp.json (project-local, overrides user-global per name), one entry per server:

stdio

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Streamable HTTP

{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.linear.app/sse"
    }
  }
}

OAuth is automatic

Set "auth": "oauth" on a Streamable HTTP entry and octo discovers the server’s auth metadata on the first 401, then runs an Authorization Code + PKCE login — a browser tab opens to the server’s consent page and redirects back once you approve it. The token is cached at ~/.octo/mcp-tokens/<server>.json and refreshed automatically; an expired refresh token just triggers the prompt again.

Check what’s connected with /mcp in the TUI, or octo mcp --help for the full config reference. A server that fails to start or times out during the handshake (10s) is logged and skipped — the session continues with the others.

Tool Search

When MCP servers expose many tools, uploading every schema on every turn wastes context and hurts accuracy. Tool Search keeps built-in tools visible but defers MCP schemas behind a small bridge — every connected tool’s name and one-line description stay listed in the system prompt the whole time, so the model never has to guess whether a tool exists; only the full schema is loaded on demand:

Tool	Purpose
mcp_describe	load the full JSON Schema for one listed tool
mcp_call	invoke the tool with arguments matching that schema

Tuning when it activates

Set threshold_pct in ~/.octo/config.yml — Tool Search only turns on once deferred schemas would occupy that share of the context window.

~/.octo/config.yml

tools:
  tool_search:
    enabled: auto          # auto (default) | on | off
    threshold_pct: 10      # activate when deferred schemas ≥ N% of the context window

• auto (default) — only enable when the deferred MCP schemas would occupy at least threshold_pct of the model’s context window.
• on — always defer MCP schemas when any MCP tool is connected.
• off — upload all MCP schemas up front, as before.

Next: MCP tools compose naturally with skills and workflows.