MCP server reference

Zumba includes a Model Context Protocol server with tools that let a coding agent look things up instead of reading whole files: a file's outline, where a symbol is defined, where a name is used, and the diagnostics your editor shows. Fewer files read means fewer tokens spent.

In Zumba

Agent tasks and inline edits get the server automatically, for the folder they work in (a task's worktree, or your project for inline edits). Claude Code, Codex and OpenCode all receive it next to the MCP servers from their own configuration, which still apply. Turn it off with editor_mcp = false in settings.toml, or Settings → Agents → Editor tools for agents: the tools' descriptions then cost no tokens.

Using it from any agent

The server is the Zumba app itself, started with mcp and a project folder. It speaks MCP over stdio, so any MCP client can use it, inside Zumba or not:

/Applications/Zumba.app/Contents/MacOS/Zumba mcp /path/to/project [--diagnostics <file>]

Claude Code:

claude mcp add zumba -- /Applications/Zumba.app/Contents/MacOS/Zumba mcp "$PWD"

Codex (~/.codex/config.toml):

[mcp_servers.zumba]
command = "/Applications/Zumba.app/Contents/MacOS/Zumba"
args = ["mcp", "/path/to/project"]

Other clients (mcpServers JSON):

{
  "mcpServers": {
    "zumba": {
      "command": "/Applications/Zumba.app/Contents/MacOS/Zumba",
      "args": ["mcp", "/path/to/project"]
    }
  }
}

Adjust the path if Zumba isn't in /Applications. It opens no window and needs nothing else running. Only diagnostics depends on the editor: it reads the file passed with --diagnostics, which Zumba keeps up to date while the project is open (~/Library/Application Support/Zumba/worktrees/<folder>-<id>.diagnostics.json). Without --diagnostics, the tool answers "No diagnostics."

Tools

Every tool returns plain text, one result per line, with 1-based line numbers. Paths are relative to the project folder. A tool that can't answer (no such file, a path outside the project) returns its message with isError: true.

`outline`

A file's functions, types, constants and headings, indented by nesting.

Argument	Type	Required	Meaning
`path`	string	yes	File path relative to the project.

14 enum Incoming
33 struct Rpc
42 impl Rpc
  43 method spawn
  150 method call

Use it to read only the lines you need. It recognizes declarations that start with a keyword (fn, struct, enum, trait, impl, function, class, interface, def, func, const, type…), which covers Rust, TypeScript, JavaScript, Python, Go and Swift, plus Markdown headings. C and C++ functions, which have no keyword, aren't listed.

`find_symbol`

Where a function, type, constant or heading is defined.

Argument	Type	Required	Meaning
`name`	string	yes	The name to find.

crates/app/src/agents.rs:309 function — pub fn handoff_prompt(t: &Task) -> String {

Exact (case-sensitive) matches first. If there are none, it lists names containing the text, ignoring case, starting with "No exact match; names containing it:". At most 40 results.

`find_references`

Lines that use a name, as a whole word, case-sensitive.

Argument	Type	Required	Meaning
`name`	string	yes	The name to find.
`path`	string	no	Only files matching these comma-separated globs, e.g. `src/*, .rs`.

crates/app/src/agents.rs:309: pub fn handoff_prompt(t: &Task) -> String {
crates/app/src/agents.rs:1063: let mut prompt = handoff_prompt(t);

It's a text search, so it also finds other things that share the name; it doesn't need a language server. At most 80 lines, then "… more; narrow it with path".

`diagnostics`

Errors and warnings from the language servers in the user's editor.

Argument	Type	Required	Meaning
`path`	string	no	Only this file.

src/client.rs:34:9: error: cannot find value `delay` in this scope
src/main.rs:3:5: warning: unused import: `std::fmt`

These are the user's files as the editor sees them, including unsaved edits. In a Zumba task they don't include the agent's own changes that haven't been applied yet.

What it searches

find_symbol and find_references cover every file in the project except what .gitignore excludes, the .git folder, and files over 512 KB (usually generated).

Protocol

MCP over stdio: one JSON-RPC 2.0 message per line. The server answers initialize (with the protocol version the client asks for), ping, tools/list and tools/call; other requests get error -32601, and notifications are ignored. Server name zumba, version = the app version.

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"outline","arguments":{"path":"src/main.rs"}}}' \
  | /Applications/Zumba.app/Contents/MacOS/Zumba mcp "$PWD"