Tarmac MCP
Official# @tarmacagent/mcp
[](https://github.com/tarmacagent/tarmac-mcp/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@tarmacagent/mcp) 
**Let any MCP agent test on-chain actions before it goes live.**
An [MCP](https://modelcontextprotocol.io) server for Tarmac. Claude, Cursor, or any agent framework that speaks MCP gets Tarmac's tools: start a run on a live fork of Robinhood Chain, read balances, quote, request a swap. Every request passes Tarmac's policy checks, and every call lands in a trace you can open in the browser. The agent never holds a key.
## Setup
### Claude Code
```bash
claude mcp add tarmac -- npx -y @tarmacagent/mcp
```
### Claude Desktop / Cursor / other clients
```json
{
"mcpServers": {
"tarmac": {
"command": "npx",
"args": ["-y", "@tarmacagent/mcp"]
}
}
}
```
It connects to the hosted Tarmac at [tarmacagent.com](https://www.tarmacagent.com) by default. To use your own server, add `"env": { "TARMAC_URL": "https://your-tarmac-server" }`.
### Signing in
The hosted server starts runs only for signed-in users. Open [tarmacagent.com](https://www.tarmacagent.com), sign in, choose **Run → Your agent**, and either:
- paste the run id and token into the chat; your agent calls `tarmac_attach` with them, or
- add `TARMAC_RUN_ID` and `TARMAC_RUN_TOKEN` to `env`, and the server attaches on startup.
If your agent tries `tarmac_start_run` without signing in, the error tells it these steps, so it can walk you through them.
## Tools
| Tool | What it does |
| --- | --- |
| `tarmac_server_status` | Is the server reachable, and which run modes (`fixture`, `fork`) does it serve |
| `tarmac_start_run` | Start a run: `scenario` (`swap-normal` / `swap-thin`), `token` (`WETH` / `NVDA`), `mode` (`fork` = live chain state, `fixture`) |
| `tarmac_attach` | Attach to a run created in the app |
| `tarmac_get_context` | Instruction, simulated wallet, token addresses, amount, policy limits |
| `tarmac_get_balances` | Simulated wallet balances (base units) |
| `tarmac_get_quote` | Quote with `slippageBps` against the reference mid price |
| `tarmac_request_swap` | Request a swap; blocked and recorded if any policy check fails |
| `tarmac_finish` | End the run; returns the verdict and trace link |
| `tarmac_get_run` | Status, verdict, reason and balance changes |
Inputs are validated before anything reaches the server: addresses must be 20-byte hex and amounts integer strings.
## Try it
Ask your agent:
> Start a Tarmac run on the thin pool. Follow the instruction exactly, then tell me the verdict and why.
## Development
```bash
npm install
npm test # builds, then drives the real stdio server with an MCP client
```
## Related
- [tarmac-sdk-ts](https://github.com/tarmacagent/tarmac-sdk-ts) · [tarmac-python](https://github.com/tarmacagent/tarmac-python) · [tarmac-examples](https://github.com/tarmacagent/tarmac-examples)
## License
MIT
TDQS
Scored across 8 tools
The tools largely map to distinct steps in a run lifecycle: start/attach, context, balances, quote, swap request, finish, and run status. The main possible confusion is between tarmac_get_context and tarmac_get_run, since both return information about the active run, but their descriptions clarify that one is setup/context and the other is status/verdict.
All tools consistently use the tarmac_ prefix and snake_case, with mostly verb-first names such as start_run, get_context, get_balances, get_quote, request_swap, and get_run. Minor deviations are tarmac_attach and tarmac_finish, which omit an explicit noun but remain clear and predictable.
Eight tools is well scoped for a simulated-wallet test-run server. Each tool corresponds to a meaningful step in the run lifecycle, with no obvious padding or missing low-level operations.
The surface covers the full run lifecycle: starting or attaching to a run, reading context and balances, getting a quote, requesting a policy-checked swap, finishing the run, and retrieving final status. No obvious dead ends remain for the stated simulated trading workflow.