MCP (Model Context Protocol)

Maki connects to external tool servers over MCP. Both stdio and HTTP transports are supported.

Configuration

Add servers under [mcp.*] in your MCP config:

Global: ~/.config/maki/mcp.toml
Project: .maki/mcp.toml (project config wins when both set a value)

Stdio

[mcp.filesystem]
command = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

[mcp.github]
command = ["gh", "mcp-server"]
environment = { GITHUB_TOKEN = "ghp_xxxx" }
timeout = 10000
enabled = false

HTTP

[mcp.analytics]
url = "https://mcp.example.com/mcp"
headers = { Authorization = "Bearer tok123" }

All options

Field	Type	Default	Notes
`command`	array		Stdio: program + args
`url`	string		HTTP: server URL
`environment`	map		Stdio only
`headers`	map		HTTP only
`timeout`	u64	30000	Milliseconds (1-300000)
`enabled`	bool	true
`always_load`	bool	false	Skip tool search, load all tools upfront

Set command for stdio, url for HTTP. Pick one.

One option lives at the top level of mcp.toml, outside any server:

Field	Type	Default	Notes
`defer_tools`	usize	10	Defer tools only when more than this many exist

Tool search

Every tool definition a server exposes costs context window space, on every request. Take Datadog's MCP server: with all toolsets on it ships over 100 tools, when a task often needs three.

So Maki, like Claude Code, defers MCP tools by default. The model sees one small tool_search tool that lists the deferred names, searches when it actually needs something, and the matches stay loaded for the rest of the session. Resume a session and the tools it was using come back. Subagents keep their own loads, so their searches don't bloat your main conversation.

You don't configure anything for this. Add the server as usual:

[mcp.datadog]
url = "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=all"

Ask about an incident, and the model searches for something like datadog logs, gets back the few matching tools, and the other hundred definitions never enter the conversation.

With 10 or fewer tools across all your servers there is no search step: at that size, searching costs more than it saves, so everything loads upfront. The top-level defer_tools key moves that line:

defer_tools = 30

[mcp.github]
url = "https://api.githubcopilot.com/mcp/"

Set it to 0 to always defer, or above your tool count to never defer.

If one server should skip the search step entirely, opt it out:

[mcp.linear]
command = ["linear-mcp-server"]
always_load = true

Good for small servers you rely on every turn. On a big server it defeats the point: every definition is back in your context on every request.

Naming and namespacing

Server names are ASCII alphanumeric, hyphens ok. Tools get prefixed with their server name: a read tool on the filesystem server becomes filesystem__read. Because of this, __ is reserved and names can't collide with built-in tools.

Runtime toggling

Turn servers on/off from the MCP picker in the UI. Changes save back to your config.

Status

Status	Meaning
Connecting	Waiting for the server to come up
Running	Tools available
Disabled	Off in config or toggled off in UI
Failed	Error shown in UI
NeedsAuth	Waiting for OAuth (see below)

If one server fails, the rest still work.

OAuth

Some HTTP servers need auth. When that happens, Maki opens your browser to log in. Other servers keep working while you authenticate. Tokens refresh on their own. If you change the server URL, you log in again.

maki mcp auth <server-name>     # manually trigger auth
maki mcp logout <server-name>   # remove stored tokens

Headless machines

On a machine without a browser (say, a dev server over SSH), run maki mcp auth <server-name>. Maki prints the login URL. Open it on your laptop and log in. The browser lands on a http://127.0.0.1:19876/... page that fails to load. Copy that full URL from the address bar and paste it into the terminal to finish the login.

Prompts

MCP servers can expose prompts (reusable message templates). Maki shows them as slash commands in the command palette: /server:prompt-name. Type / to filter.

/github:create-pr           # no arguments
/analytics:report monthly   # one argument
/review:code src tests      # multiple, positional

Skip a required argument and Maki shows a usage hint. Prompts are fetched at startup and on reconnect, so new ones need a restart. Only text content is supported.