graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
name: mcp-config description: Inspect or change this workspace's MCP servers, or the user-level global ones - use when adding, removing, or authenticating an MCP server, when MCP tools are missing or a server did not connect, or when the user asks how MCP config works here.
MCP configuration
MCP servers are configured per workspace in .mcp.json at the project root, and
per user in ~/.codegraff/mcp.json for the servers you want in every project.
The two files use the same schema and are merged; a project entry wins over a
global one with the same name. Their tools reach the model as
mcp__<server>__<tool>.
The file
{
"mcpServers": {
"playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] },
"sentry": {
"command": "npx",
"args": ["-y", "@sentry/mcp-server"],
"env": { "SENTRY_AUTH_TOKEN": "..." }
},
"mobbin": { "url": "https://api.mobbin.com/mcp" },
"internal": {
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer ..." }
}
}
}
- Local (stdio) server:
commandplus optionalargsandenv.envvalues are literal strings - there is no${VAR}expansion. - Remote server:
url, Streamable HTTP. HTTPS is required except for localhost, andheadersis for static tokens. - Invalid JSON in one file means zero servers load from THAT file; the other one still loads. If tools vanished after an edit, check the file parses first.
~/.mcpconfig.jsonis not read - that path belongs to other MCP clients. Startup says so once if it exists.- Names under
"disabledMcpServers"(same object shape, in either file) stay out of the session, including servers graff would otherwise import from another tool's config. Moving an entry back intomcpServersturns it on. The global list never removes a server the project file defines. - A local server starts on first use once graff has seen its tools (they are
cached): the session lists its tools but spawns the process only when a tool
is called.
"startup": "eager"on an entry starts it with every session;GRAFF_MCP_EAGER=1does that for all of them. "shared": trueon a stateless local server (time, fetch, a docs search) runs one process per machine for every session, through a broker graff starts on demand and stops after a minute idle. Leave it off for servers that keep per-agent state: a browser, a working directory, credentials. POSIX only.
Prefer the CLI for writes
graff mcp # list configured servers (global ones tagged)
graff mcp list --json # the merged set as JSON, with each server's source
graff mcp add <name> -- <command> [args...] # local server
graff mcp add <name> --env KEY=VALUE -- <command> # with env
graff mcp add <name> --url https://host/mcp # remote server
graff mcp add <name> --url https://host/mcp --header KEY=VALUE
graff mcp login <name> # OAuth for a remote server
graff mcp status [--json] # each server's state and tools, starts nothing
graff mcp reconnect <name> | --all # fresh handshake; refreshes its cached tools
graff mcp enable|disable <name> # switch a server on or off everywhere
graff mcp add and /mcp add write the project .mcp.json; only
graff mcp add … --everywhere writes the global file - adding a server to one
repository must not edit every other one.
Editing either file with edit_file or write_file is equally valid, and it is
how you remove a server (drop its key) or rename one. Do not commit a secret
into it: prefer graff mcp login (OAuth credentials are stored outside the
repo) or a token the user supplies at runtime.
In-session, no restart
/mcp- connected servers, tool counts, and any workspace servers still pending consent/mcp add <name> <command> [args...]and/mcp add <name> --url <URL>- connect one live and persist it/mcp trust- connect the servers that were skipped at startup, project and global alike/mcp reconnect <name>- start one server again (a failed one joins for the first time) without a new session
When a server is not connected
Either config file launches arbitrary local commands, so graff never auto-spawns
untrusted entries: it asks at startup, and without consent (or --yolo) it
starts with an empty but live registry. A global entry gets no extra trust for
being global - it just follows you into every project. /mcp trust is the
in-session fix and /mcp shows what is pending. Remote servers pass the same
gate, because their arguments leave the machine.
/mcp says why each other server is not connected: failed (with the cause),
off (graff mcp disable, or "enabled": false in its own entry), optional
(graff mcp enable <name> opts in), or not started (consent). graff mcp reconnect <name> retries one and prints the server's own last error line.
After that, in likelihood order: the command is not on PATH, the package name
is wrong, the server needs a token that is not set, the URL is not HTTPS, or
the server needs an OAuth login (graff mcp login <name>).
After changing config
Tools appear as soon as a server actually connects, which live /mcp add and
/mcp trust both do. Editing .mcp.json alone changes nothing in the running
session - connect the server live or restart.
MCP tools are accelerators, never requirements. When a server is missing or a
call fails, fall back to the native tools (bash, read_file, webfetch) and
keep going.