mcp-creator

Configure an MCP server

octo connects to MCP servers declared in ~/.octo/mcp.json, using the Claude Code-compatible mcpServers shape. This is the file you write to.

Your job is to turn "I want my assistant to talk to X" into a working entry in that file. Not every user knows what MCP is — briefly explain terms if in doubt.

Config schema

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {"KEY": "value"}
    },
    "remote-api": {
      "url": "https://example.com/mcp",
      "headers": {"Authorization": "Bearer …"},
      "auth": "oauth"
    }
  }
}

Each entry is exactly one of two transports — setting both command and url is invalid:

Field	Transport	Meaning
command	stdio	Executable to launch (e.g. npx, uvx, a binary path)
args	stdio	Argument list, one element per arg
env	stdio	Extra environment variables for the child process
url	http	Streamable-HTTP endpoint URL
headers	http	Static headers, e.g. an API-key Authorization
auth	http	"oauth" to run OAuth (Authorization Code + PKCE) on connect; omit otherwise
disabled	both	true keeps the entry but skips connecting

Server names must have no whitespace and must not contain __ (reserved as the tool-name separator). Prefer short kebab-case names — they prefix every tool the server exposes.

Editing an existing server

The web UI's per-row "Edit with Agent" button routes here too. This skips most of the Workflow below; there's no new package to find or transport to choose:

1. Locate the entry in ~/.octo/mcp.json.
2. Show the user the current entry before changing anything.
3. Ask what they want changed. Apply the smallest edit that satisfies the request — preserve every other field and every other server entry verbatim.
4. Write the file back, then do step 6 of the Workflow below (verify, tell them to Reload).