MCP
Connect MCP (Model Context Protocol) servers to Cola — edit servers.json, complete OAuth, and how tools get discovered and called.
Cola supports MCP (Model Context Protocol) natively. Once a server is connected, its tools join Cola's tool catalog: Cola discovers and calls them when a task needs them, through the same path as built-in tools.
Add an MCP server
The config file is ~/.cola/mcp/servers.json. There is no management UI yet: edit it directly, or ask Cola to do it ("add an MCP server for me").
{
"servers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/"
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me"]
}
}
}- An entry with
urlis a remote server; one withcommandis a local process. Both are supported; each entry takes exactly one of the two. - Cola picks up changes automatically — they take effect from the next turn, no restart needed.
- Once a
commandis saved, Cola starts that process immediately with no further confirmation — only add commands you trust.
Authorization
For servers that need OAuth, ask Cola to start the flow before first use ("authorize the github MCP server"); it posts an authorization link in the conversation, and you open it in a browser and sign in (the link is valid for 5 minutes — just ask again if it expires). Tokens are stored in ~/.cola/mcp/tokens.json, readable only by your local user. Servers without OAuth can carry static headers directly in servers.json.
How tools get discovered and called
- A server's tool list is cached; Cola searches and calls tools only when a task actually needs them, instead of loading every MCP tool into every turn.
- Connections are kept on demand: a new server is connected once when its tool list is first discovered (local servers are started at that point), idle connections close after about 10 minutes, and the next call reconnects transparently.
- MCP tools are flagged as third-party: before calling one, Cola sees a guideline to confirm with you when the impact is unclear or destructive — but that is model behavior, not a hard gate, so check a server's own permission scope before connecting it.
- A server that fails to connect or crashes only fails its own calls with a descriptive error; other servers and the conversation are unaffected.
- To see what's connected, with connection and auth state, just ask Cola ("list my MCP servers").
Troubleshooting
| Symptom | Usual cause | What to do |
|---|---|---|
| Added a server but tools aren't available | Still inside the same turn, or the server hasn't been discovered successfully yet | Start a new turn; if still nothing, ask Cola to "list my MCP servers" and check connection state and errors |
| An entry seems to be ignored | Both command and url set, or the server name has invalid characters | Keep exactly one of the two; name servers with letters, digits, -, _ |
| An OAuth server exposes no tools at all | Not authorized yet | Ask Cola to start the authorization flow |
| A local server won't start | command not on PATH, or wrong arguments | Run it once manually in a terminal |
| A server never appears at all | Its name contains a double underscore __ | Rename it. __ separates the segments in mcp__<server>__<tool>, so entries containing it are skipped |
Related
- Tasks and permissions — the boundaries for Cola's own tools. Note that MCP tools run outside authorized directories and path guards; their permissions are whatever the server itself allows — connect only servers you trust
- Channels and plugins — the opposite direction: embedding Cola into external software