How to Add Custom Tools to Crush With MCP Servers
Crush supports MCP — the Model Context Protocol — so you can give it tools beyond reading and editing files. Register an MCP server in its config, and Crush can call that server’s functions during a session: query a database, hit an internal API, search docs. It is the standard way to extend a terminal agent without modifying its source.
MCP servers speak a common protocol, so the same server you configured elsewhere often drops straight into Crush’s config with a path change.
What is MCP and why does it matter here?
MCP is an open protocol that lets an AI client discover and call tools exposed by a server process. The client asks “what can you do,” the server replies with a list of functions and their schemas.
For a coding agent, that means tooling like a structured issue-tracker client, a schema-aware database query tool, or a doc search — anything with a maintained MCP server.
How do you register an MCP server?
- Locate Crush’s configuration file, typically a JSON file in its config directory.
- Add an mcp entry with a command that starts the server — an npx package or a binary path.
- Provide any required environment variables, such as an API token for the service.
- Restart Crush so it loads the new server.
- In a session, ask a question that needs the tool and confirm it appears.
Most servers are launched as a subprocess over stdio, so a typo in the command means Crush silently has no tools from it. Check the startup output when troubleshooting.
What makes a good MCP tool to add?
| Tool | Use case | Risk |
|---|---|---|
| Database query | Inspect schema, run reads | Writes if granted |
| Issue tracker | Read and file tickets | Mass edits |
| Doc search | Pull internal docs | Low |
How do you scope permissions?
Give each server the least access it needs. A database tool should connect with a read-only role unless you specifically need writes. An API token should be scoped to the one service, not a full account key.
Crush still asks for confirmation before running tools, which is a real safety layer. Keep it on for any tool that mutates state — the model can misread a request and call a write tool when you meant a read.
What goes wrong with MCP setups?
Version drift is common: a server package updates and changes its function signatures, so the model calls a tool with stale arguments. Pin versions. Startup failures are quiet, so verify the server responds before relying on it in a workflow.
Too many tools also degrade performance. Each tool’s schema consumes context, and dozens of options make the model pick the wrong one. Add servers deliberately, not in bulk.
Who should wire this up?
Developers who already run internal services and want the terminal agent to reach them. If your whole workflow is local files and git, the built-in file and shell tools cover it and MCP adds complexity for little gain. Add it when a real external system needs to be in reach.
Quick Summary
- Crush can call MCP servers, adding tools like database queries and doc search to a session.
- Register servers in Crush’s config with a start command and any env vars, then restart.
- Scope each server to least privilege and keep write tools behind confirmation.
- Pin server versions and avoid adding many tools — extra schemas consume context.
