🎫 mcp-coatcheck

MCP Tasks for any MCP server. Hand over a slow tool call, get a ticket, pick up the result later.

Two real Claude Code runs with a 15s MCP tool timeout, replayed at 3× speed. MP4 · how it was made

The problem

Your agent calls a tool that takes a few minutes: a test suite, a build, a crawl, an eval. One of two things happens:

• The call times out. Most MCP clients cap how long a single tool call may run, and the work is lost.

• The chat freezes until the tool returns.

MCP Tasks fix this. The server hands back a task id right away and the client collects the result later. But almost no server implements Tasks yet, and most clients don't speak them either.

Related MCP server: Universal MCP Gateway

The fix

A tiny proxy for any stdio MCP server. No server changes needed.

Every call goes through. If it finishes within --after, the agent gets the normal result and nothing changes. If it doesn't, coatcheck hands the agent a ticket and keeps the call running:

No call ever blocks longer than --after, including coatcheck_result. Set it below your client's tool timeout and timeouts are gone.

Quick start

Put npx mcp-coatcheck -- in front of the command you already use.

Claude Code

claude mcp add my-server -- npx -y mcp-coatcheck -- npx -y some-slow-mcp-server

Codex (~/.codex/config.toml)

[mcp_servers.my-server]
command = "npx"
args = ["-y", "mcp-coatcheck", "--", "npx", "-y", "some-slow-mcp-server"]

Cursor, Gemini CLI, VS Code, anything with a JSON config

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "mcp-coatcheck", "--", "npx", "-y", "some-slow-mcp-server"]
    }
  }
}

Options

Durations look like 500ms, 20s, 2m, 1h.

What has been tested

npm test starts the real proxy around examples/slow-server.mjs and runs 14 end to end checks across all three modes, including cancellation races and late answers.

Good to know

• If the wrapped server already supports Tasks, coatcheck notices during the handshake and gets out of the way.

• Results live in memory. Restarting the proxy loses running jobs.

• tasks/list is not offered: the proxy cannot tell callers apart, so listing would show one caller another's tasks. Task ids are random UUIDs.

• stdio only for now. Streamable HTTP is next.

• If the wrapped server asks the user something (elicitation) while a call runs in the background, the request is forwarded but not tied to the task yet.

Try it locally

git clone https://github.com/emrehangorgec/mcp-coatcheck
cd mcp-coatcheck
npm install
npm test
node dist/cli.js --after 3s -- node examples/slow-server.mjs

examples/slow-server.mjs is a tiny MCP server with a quick echo tool and a run_tests tool that takes 20 seconds by default.

How the demo was made

The GIF replays two real claude -p runs with MCP_TOOL_TIMEOUT=15000 against examples/slow-server.mjs, one plain and one behind mcp-coatcheck --after 10s. Tool calls, results and agent messages are copied from the stream-json output. demo/demo.html draws them on a timeline. Open it in a browser to watch it live.

License

MIT