An MCP client that puts your servers to work

How it works

1. 1

   Give the MCP client a stdio and an HTTP server

   Each [[mcp.servers]] entry is one server. auto_bind attaches it to a role, and {{ENV:KEY}} reads a token from your environment so it never sits in the file. Leave out the Authorization header and Octomind runs the OAuth sign-in instead.

   ~/.local/share/octomind/config/config.toml

   [[mcp.servers]]
   name = "time"
   type = "stdio"
   command = "uvx"
   args = ["mcp-server-time"]
   timeout_seconds = 30
   tools = []
   auto_bind = ["assistant"]
   
   [[mcp.servers]]
   name = "github"
   type = "http"
   url = "https://api.githubcopilot.com/mcp/"
   headers = { Authorization = "Bearer {{ENV:GITHUB_TOKEN}}" }
   timeout_seconds = 30
   tools = []
   auto_bind = ["assistant"]

2. 2

   Start the MCP host and check what loaded

   octomind run launches the role’s stdio servers before the first prompt. /mcp shows each server, its health and its tools, and /mcp health forces a check. Neither one calls a model.

   octomind run assistant
   
   # inside the session
   /mcp           # servers, health, tools
   /mcp health    # check every external server now
   /mcp full      # full parameter schemas

3. 3

   Let the MCP agent add a server mid-session

   Ask in plain words. The agent calls the built-in mcp tool to register the server, connect it and use it. persist writes mcp-<name>.toml, so the server loads again next session.

   {"action": "add", "name": "calc", "server_type": "http", "url": "http://127.0.0.1:3917/mcp"}
   {"action": "enable", "name": "calc"}
   {"action": "persist", "name": "calc"}

What you get

• stdio and Streamable HTTP, old servers included

  Local servers start as child processes in their own process group, so Ctrl+C in your terminal does not kill them. Remote servers use Streamable HTTP. Octomind speaks MCP 2026-07-28 and falls back to the legacy initialize handshake for servers that predate it.

  src/mcp/client.rs:17↗

• OAuth sign-in for remote MCP servers

  With no Authorization header, Octomind finds the server’s auth server through RFC 9728 discovery and runs an OAuth 2.1 sign-in with PKCE in your browser. The token is saved per server; near expiry Octomind renews it with the stored refresh token, and opens the browser again only when there is none or the server rejects it. Set a static header and OAuth is skipped.

  src/mcp/client.rs:651↗

• Servers added and removed while the agent works

  The built-in mcp tool takes seven actions: list, add, enable, disable, remove, persist and unpersist. enable can take a tools filter such as ["github_*"], so you expose only the tools the task needs.

  src/mcp/runtime/dynamic.rs:581↗

• Crashed stdio servers restart themselves

  A health monitor checks every stdio and HTTP server in your config every 120 seconds and restarts a dead stdio process. Restart attempts are at least 30 seconds apart. After 3 failed starts in a row the server is marked failed and left alone, so a broken server cannot loop.

  src/mcp/health_monitor.rs:36↗

• Servers that ship with their own installer

  A tap capability can bundle an [[mcp.servers]] entry with [deps] require = ["org/tool"]. Before MCP starts, Octomind runs the tap’s deps/org/tool.sh, which installs the server if it is missing. If the script exits non-zero, you get its error and the server is not started.

  src/agent/deps.rs:17↗

One prompt adds a server for good, and a killed server comes back

The first run is one small model turn on deepseek-v4-flash. The agent registered a Streamable HTTP server it had never seen, connected it, called a tool on it and persisted it. The turn cost $0.00096. The second run is a fresh session with no model call: the persisted calc server loads from its file, and the script in .agents/tools/todo-count shows up as a tool with no registration. In the third, the stdio time server got kill -9 10 seconds into a session, and nothing was typed for 130 seconds. /mcp then showed it running again: the health monitor restarted it on its own (the counter includes the first start, so restarts: 2 is one restart).

{"type":"tool_use","tool":"mcp","server":"runtime","params":{"action":"add","name":"calc","server_type":"http","url":"http://127.0.0.1:3917/mcp"}}
{"type":"tool_result","tool":"mcp","server":"runtime","content":"Server 'calc' registered. Use 'enable' to activate it.","success":true}
{"type":"tool_use","tool":"mcp","server":"runtime","params":{"action":"enable","name":"calc"}}
{"type":"tool_result","tool":"mcp","server":"runtime","content":"Server 'calc' enabled with 15 tools:\necho, get-annotated-message, get-env, get-resource-links, get-resource-reference, get-structured-content, get-sum, get-tiny-image, gzip-file-as-resource, toggle-simulated-logging, toggle-subscriber-updates, trigger-long-running-operation, trigger-elicitation-request, trigger-url-elicitation, simulate-research-query","success":true}
{"type":"tool_use","tool":"get-sum","server":"calc","params":{"a":19,"b":23}}
{"type":"tool_result","tool":"get-sum","server":"calc","content":"The sum of 19 and 23 is 42.","success":true}
{"type":"tool_use","tool":"mcp","server":"runtime","params":{"action":"persist","name":"calc"}}
{"type":"tool_result","tool":"mcp","server":"runtime","content":"Server 'calc' persisted to /private/tmp/claude-usecases/mcp-client/work/data/config/mcp-calc.toml. Auto-bind set to role 'assistant'.","success":true}
{"type":"assistant","content":"42"}
{"type":"cost","session_tokens":39395,"session_cost":0.0009555599999999999,"input_tokens":1370,"output_tokens":265,"cache_read_tokens":37760,"cache_write_tokens":0,"reasoning_tokens":0,"aux_input_tokens":0,"aux_output_tokens":0,"aux_cost":0}
{"type":"cost","session_tokens":39395,"session_cost":0.0009555599999999999,"input_tokens":1370,"output_tokens":265,"cache_read_tokens":37760,"cache_write_tokens":0,"reasoning_tokens":0,"aux_input_tokens":0,"aux_output_tokens":0,"aux_cost":0}

…
▍ 〉/mcp list
╭ /mcp list
│ orchestration
│   tap
│   schedule
│   monitor
│ core
│   recall
│ local
│   todo-count
│ runtime
│   mcp
│   agent
│   skill
│   capability
│ agent
│   agent_context_gatherer
│ time
│   get_current_time
│   convert_time
│ calc
│   echo
│   get-annotated-message
…
│   simulate-research-query
│ Use '/mcp info' for descriptions or '/mcp full' for parameters.
╰ ✓ /mcp list · 7 server(s) · 27 tool(s)

…
▍ 〉/mcp
╭ /mcp info
│ servers
│   core  ✓ running  (builtin)
│   orchestration  ✓ running  (builtin)
│   runtime  ✓ running  (builtin)
│   agent  ✓ running  (builtin)
│   time  ✓ running  (stdin) · restarts: 2 · failures: 0
│   calc  ✓ running  (http)
│   local  ✓ running  (builtin)
│     configured: todo-count
…
╰ ✓ /mcp info · 7 server(s) · 27 tool(s)

What it doesn't do

• ✕

  Octomind is an MCP client, not an MCP server

  Other agents cannot call Octomind over MCP. To drive it from another program, use ACP for editors, the WebSocket server, or octomind run --format jsonl on stdin and stdout. Docs →

• ✕

  No legacy HTTP+SSE transport

  Remote servers must speak Streamable HTTP. For a server that only offers the old SSE endpoint, run its stdio build, or put a stdio bridge in front of it and add that as a stdio server. Docs →

• ✕

  Remote taps come from GitHub only

  octomind tap user/repo clones github.com/user/octomind-repo. For GitLab or a private host, clone the repo yourself and add it as a local tap with octomind tap user/repo ./path. Docs →

• ✕

  The runtime mcp tool cannot set headers, env or cwd

  A server that needs a token header or environment variables goes in TOML, where {{ENV:KEY}} reads the value from your environment at connect time. Docs →

• ✕

  Only stdio servers from your config auto-restart

  Remote HTTP servers are checked but never restarted, since Octomind has no command to relaunch them. A server added mid-session is not watched until you persist it and start a new session. Docs →

Questions

Go deeper

Other ways to run octomind

• Self-hosted agent An agent on your own box that takes work from webhooks, timers and your shell.
• Agentic workflows Multi-step agent pipelines in one TOML file: parallel, loop until it passes, fan-out.
• Agent orchestration A lead agent hands work to specialists at runtime. You get one bill and one verdict.
• Self-improving agent Correct the agent once. It saves the fix as a file and recalls it next session.
• Agent backend Your app talks to one WebSocket. octomind runs the agent, its tools and the bill per user.