coco-mcp

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.svg"> <img src="docs/logo-light.svg" width="96" alt="The Coco mark: a cat's face with teal eyes"> </picture> </p> <h1 align="center">Coco MCP</h1> <p align="center">Inspect and debug MCP servers in depth, from the command line or a native window.</p>

Coco MCP is a tool for inspecting and debugging Model Context Protocol servers: connect to one, see what it offers, call it with any payload, read every message on the wire, and keep what you learned. It is one binary, written in Rust and drawn by GPUI: coco-mcp --cli runs a command, coco-mcp --desktop opens a native window, and both work from the same core.

Why

I wrote Coco because the way I was inspecting MCP servers kept getting in my way. I needed to send a raw JSON payload, not only what a form would let me type. I needed several servers connected at the same time, each with its own log. I needed the tool to stay fast with a long log and a large result on screen, and I needed it to remember the servers and the calls from yesterday. So Coco does those things first:

• Any payload. The Raw tab next to the generated form takes whatever JSON you paste, checks it against the tool's schema before it is sent, and copies the request as JSON-RPC or curl exactly as it goes out.
• Many servers at once. Every server in the sidebar has its own session, wire log and history, all connected together; switching is a click or ⌘K.
• Fast, and still fast an hour later. A native binary drawn on the GPU, where every list, tree and text builds only the lines in view, so a result of a hundred thousand rows costs a frame what ten rows do.
• Memory. Servers, calls and snapshots persist, a call can be replayed or opened back in the form, and each connect is diffed against the last snapshot so a breaking change in a server is noticed, not discovered.

The command line exists so the same things can be scripted, and so a breaking change can fail a CI job.

Built in Rust, drawn by GPUI

Coco is a native program from the wire to the pixels, and that shows in use:

• It starts in a blink and stays light. The window is a single native binary: nothing to boot before the first frame, no runtime to install, no browser process beside it. Memory stays flat through a long session, since every table, log and tree is drawn from the model, not kept as markup.
• The UI is drawn on the GPU. The window is built with GPUI, the engine the Zed editor is written in: a retained scene rendered through Metal, Vulkan or DirectX. A log drawer with thousands of messages, a schema tree with hundreds of nodes and a result of many megabytes scroll at the frame rate, and every list builds only the rows in view.
• One core, two faces. The protocol client, the storage, the schema forms, the diff and the export formats are plain Rust crates with no UI in them. The command line and the window are two thin layers over the same code, so what one shows, the other can script, and neither can drift from the other.
• The whole UI runs headless. Because GPUI can render without a display, every screen in this README is produced by a test that drives the real window against a mock server, and the animated tour above is assembled from those frames. What you see is what the tests saw.
• Rust end to end. No unsafe code, no unwrap outside tests, every dependency under a permissive licence, audited in CI. Secrets go to the OS keyring through native bindings; the database is SQLite, compiled in.

What it does

• Connect to stdio servers (any command) and streamable HTTP servers, with custom headers, bearer tokens or OAuth 2.1 (PKCE, dynamic registration). Secrets live in the OS keyring, never in the database.
• Speak either era of the protocol: the initialize handshake (2024-11-05 to 2025-11-25) or the sessionless 2026-07-28 revision, chosen per server. Every feature follows the version the server agreed to and what it declared; one it cannot use stays on screen, disabled, and says why.
• Browse tools, resources, resource templates and prompts with an inline filter and keyboard navigation.
• Call tools through a form generated from the tool's JSON Schema (nested objects, arrays, enums, oneOf), or edit the raw JSON. Arguments are validated against the schema before they are sent.
• See responses as collapsible JSON, text, Markdown or images, with round-trip times, in a panel of their own under the form, split by a separator you drag, and every wire message in a filterable log drawer (⌘J, zoomed over the columns with ⌘⇧J), where rows unfold, each on its own, into the same tree as a response, and a toggled row moves to the top of the drawer. A reconnect keeps the previous connection's messages above a separator, so the reason a server stopped is still there.
• Answer server-initiated requests: elicitation forms, sampling and roots are shown as dialogs instead of being auto-rejected.
• Remember every call. The History view replays a call or loads its arguments back into the form; its filter matches a call's name, arguments, result and error, so one word finds a call in a long history. The bin above the list empties it after a confirmation; the bin on a call deletes that call alone.
• Notice changes. Each connect is compared with the last stored snapshot and a banner classifies every difference as breaking, compatible or cosmetic, direction-aware for input and output schemas.
• Take it away. Right-click any node of any tree to copy its value, its path or its key; copy a whole response, a tool's schema, a request as JSON-RPC or as curl; export the snapshot, the wire log, the call history and the client config to files. Bearer tokens are redacted everywhere except the one action named for them.
• Bring it in. Import an mcpServers file from another MCP client and every server it names is added at once, with any token it carried moved into the keyring.
• Watch an agent. Turn the gateway on in Settings and an agent connects to http://127.0.0.1:<port>/<server> instead of the server itself. Its messages go through unchanged, and each shows in that server's log under the agent's name, and each tool call, resource read or prompt it makes becomes a row of History under its name, which can be replayed from there (the newest 500 per server are kept). The root, http://127.0.0.1:<port>/, is every included server as one for an agent that connects once: tools and prompts are named <server>__<name>, resources keep their URIs. The gateway answers only on this machine, only with the access token Settings holds.
• Script it with coco-mcp --cli: snapshot, call, read, prompt, diff (exit 1 on a breaking change) and export the saved servers as an mcpServers block.

| | | |---|---| | | |

Install

Every release ships prebuilt binaries for macOS (arm64 and x86_64), Linux (x86_64) and Windows (x86_64), built by the release workflow from the tagged source, so installing takes seconds. Building it yourself is the other option.

Quick install

Homebrew, on macOS and Linux, installs the binary of the latest release and brew upgrade coco-mcp follows new ones:

brew install camiloazula/coco/coco-mcp

The tap lives at camiloazula/homebrew-coco.

npm, on macOS, Linux and Windows, runs the binary of the latest release without installing anything else; npm install -g coco-mcp keeps it:

npx coco-mcp

The package is a small shim over one binary package per platform, and nothing is compiled on install; it lives at camiloazula/coco-mcp-npm.

The release archive, on any platform including Windows: download the one for your system from the latest release, check it against SHA256SUMS, and put coco-mcp somewhere on your PATH. A file saved by a browser is quarantined on macOS and refused until you allow it under Privacy & Security in System Settings, or clear the mark:

xattr -d com.apple.quarantine coco-mcp

Fetching the archive with curl sets no such mark. Windows asks once in the same way; "More info", then "Run anyway".

From source

Cargo (Rust 1.90 or newer) builds the current main on your machine; add --tag vX.Y.Z for a release:

cargo install --locked --git https://github.com/camiloazula/coco-mcp coco-mcp

--locked builds with the exact dependency versions in the committed Cargo.lock, the set the tests and the licence audit ran against. To update a Cargo install, run the install command again; cargo install --list shows what is installed and from which commit, and cargo uninstall coco-mcp removes it. Building needs a C toolchain and the system libraries GPUI and the keyring link against; the CI workflow in .github/workflows/ci.yml lists the packages it installs.

Two modes

However it arrived, it is one binary, coco-mcp:

coco-mcp                   # the window (`--desktop` says the same)

coco-mcp --cli --help      # the command line; every command follows --cli

From a checkout, just run opens the window and just coco --help the command line.

Updates

When a newer release is out, the window shows it in the status bar, and the note opens the command that upgrades your install: brew upgrade coco-mcp for Homebrew, npm i -g coco-mcp@latest or npx coco-mcp@latest for npm (pnpm, Yarn and Bun get their own), the cargo install line for Cargo, and the release page for an archive. "Skip this version" keeps quiet until the one after; the About window says whether you are up to date. The command line prints the same as one line on stderr after its output, only when stderr is a terminal and CI is not set. Nothing is downloaded or replaced: the app only tells you.

To know, it asks GitHub for the latest release (api.github.com/repos/camiloazula/coco-mcp/releases/latest) at most once a day, in the background, sending a User-Agent with the version and nothing else. It is the only request the app makes to anything but the servers you configure. Turn it off with COCO_NO_UPDATE_CHECK=1 or DO_NOT_TRACK=1, or with "Turn off update checks" in the command palette, which holds for the command line too; "Check for updates" (also in the app menu) asks at once. What it found is kept in update.json beside the database.

The desktop mode

coco-mcp alone, or with --desktop, opens the window. Press ⌘N (or the + in the sidebar) to add a server. A stdio server is a command line, such as filesystem-server --root /tmp, an optional working directory and optional KEY=value environment lines. The line is split the way a shell splits it, so an argument with a space in it is quoted ("my notes"), but it never runs through a shell: nothing is expanded. An HTTP server is a URL plus optional headers and an auth mode. A server that is not connected shows that form as its pane, so it can be connected as it is or changed first; a connect that failed, or a session the server ended, leaves the reason under the fields, and a server that refused an OAuth login also offers Authorize; ⌘E moves the keyboard into it. For a connected server, the pencil next to the + (⌘E), or Settings at