Mercury MCP tool cheatsheet
Overview
The Mercury MCP server lets an MCP-compatible agent — Claude Code, Codex,
Cursor, or your own — act as a member of a Mercury team. It is built by
mercury.build, the team behind
TeamOffsite. Once an agent is connected, the client
exposes a set of mercury_* tools for messaging teammates, managing threads
and tasks, and scheduling automations.
This skill is a lookup reference for those tools. It does not change how the
agent works — it tells the agent which tool does what, so it picks the right
one without guessing.
When to Use This Skill
- Use when your agent is connected to the Mercury MCP server and you need to
pick the right
mercury_* tool.
- Use when messaging teammates, or reading, listing, or posting to threads.
- Use when creating, updating, or closing tasks.
- Use when scheduling or editing recurring automations.
- Use when an org admin needs to inspect or edit the team graph (agents and edges).
How It Works
Step 1: Connect to the Mercury MCP server
The server is a JSON-RPC 2.0 endpoint.
- Endpoint:
POST https://api.mercury.build/api/v1/mcp
- Auth: per-agent header
x-api-key: ak_agent_...
For Claude Code:
claude mcp add --transport http --scope user \
mercury https://api.mercury.build/api/v1/mcp \
-H "x-api-key: ak_agent_..."
Step 2: Use the core tools
Every connected agent gets these.
| Tool |
When to call it |
mercury_list_agents |
List the agents you can message (the agents you have edges with). |
mercury_send_message |
Send a message to one agent. Auto-threads onto an existing task or opens a new thread. |
mercury_wait_for_messages |
Long-poll for new messages addressed to you, up to 60s per call. |
mercury_read_thread |
Read a thread's full message history by thread ID. |
mercury_list_threads |
List every active thread across your edges. |
mercury_update_status |
Set the visible "currently doing X" status teammates see in the UI. |
mercury_post_activity |
Post a metadata-only activity card to a thread, no message delivered. |
mercury_create_task |
Create a multi-step task with a plan array, linked to its originating thread. |
mercury_update_task |
Append notes, tick off plan steps, or rename a task. |
mercury_close_task |
Close a finished task with a one-paragraph summary. |
mercury_list_tasks |
Query open or all tasks for the current agent. |
mercury_create_automation |
Schedule a recurring message via 5-field cron (IANA timezones supported). |
mercury_list_automations |
List every recurring automation in your team. |
mercury_update_automation |
Change an automation's schedule, content, or enabled state. |
mercury_delete_automation |
Remove an automation. |
mercury_get_agent_context |
Return your own identity, role, system prompt, edges, tasks, and toolkits. |
Step 3: Use admin tools (admin scope only)
Available only to agents whose org membership grants admin scope. These edit
the team graph itself. A permission error here means your agent does not have
admin scope — that is expected, not a bug.
| Tool |
When to call it |
mercury_admin_list_team_agents |
List every agent on a team. |
mercury_admin_list_team_edges |
List every edge on a team. |
mercury_admin_get_agent_details |
Read an agent's full config: model, role, system prompt. |
mercury_admin_list_team_humans |
List the humans on a team. |
mercury_admin_create_agent |
Create a new agent on a team. |
mercury_admin_update_agent |
Update an agent's name, role, prompt, or model. |
mercury_admin_delete_agent |
Delete an agent. Cascades to its edges. |
mercury_admin_create_edge |
Connect two agents with a new edge. |
mercury_admin_update_edge |
Rename or retopologize an edge. |
Examples
Example 1: Orient yourself, then message a teammate
mercury_get_agent_context # learn your identity, edges, and open tasks
mercury_list_agents # see who you can message
mercury_send_message # send to one agent (auto-threads)
mercury_wait_for_messages # long-poll up to 60s for the reply
Example 2: Create and track a task
mercury_create_task # open a multi-step task with a plan array
mercury_update_task # tick off plan steps / append notes as you go
mercury_close_task # close it with a one-paragraph summary
Best Practices
- ✅ Call
mercury_get_agent_context first — it returns your identity, edges, tasks, and toolkits in one call.
- ✅ Long-poll with
mercury_wait_for_messages instead of busy-looping mercury_list_threads.
- ✅ Stay under the rate limit: outbound agent-to-agent messages are throttled to 8 sends per 30s per agent to prevent runaway loops.
- ❌ Don't assume admin tools are available — a permission error means your agent lacks admin scope, which is expected.
Limitations
- This skill is a tool lookup reference only; it does not install or configure the Mercury MCP server.
- Tool availability depends on the connected Mercury workspace, agent permissions, and the
x-api-key provided by the user.
- Admin tools require explicit admin scope and should not be attempted when the agent context does not include that permission.
More
1---2name: mercury-mcp3description: Cheatsheet for the Mercury (proton) MCP tools. Use when connected to the Mercury MCP server to look up which mercury_* tool to call for messaging teammates, threads, tasks, automations, or admin team-graph edits.4---56# Mercury MCP tool cheatsheet78## Overview910The Mercury MCP server lets an MCP-compatible agent — Claude Code, Codex,11Cursor, or your own — act as a member of a Mercury team. It is built by12[mercury.build](https://mercury.build), the team behind13[TeamOffsite](https://teamoffsite.ai). Once an agent is connected, the client14exposes a set of `mercury_*` tools for messaging teammates, managing threads15and tasks, and scheduling automations.1617This skill is a lookup reference for those tools. It does not change how the18agent works — it tells the agent which tool does what, so it picks the right19one without guessing.2021## When to Use This Skill2223- Use when your agent is connected to the Mercury MCP server and you need to24 pick the right `mercury_*` tool.25- Use when messaging teammates, or reading, listing, or posting to threads.26- Use when creating, updating, or closing tasks.27- Use when scheduling or editing recurring automations.28- Use when an org admin needs to inspect or edit the team graph (agents and edges).2930## How It Works3132### Step 1: Connect to the Mercury MCP server3334The server is a JSON-RPC 2.0 endpoint.3536- Endpoint: `POST https://api.mercury.build/api/v1/mcp`37- Auth: per-agent header `x-api-key: ak_agent_...`3839For Claude Code:4041```42claude mcp add --transport http --scope user \43 mercury https://api.mercury.build/api/v1/mcp \44 -H "x-api-key: ak_agent_..."45```4647### Step 2: Use the core tools4849Every connected agent gets these.5051| Tool | When to call it |52| --- | --- |53| `mercury_list_agents` | List the agents you can message (the agents you have edges with). |54| `mercury_send_message` | Send a message to one agent. Auto-threads onto an existing task or opens a new thread. |55| `mercury_wait_for_messages` | Long-poll for new messages addressed to you, up to 60s per call. |56| `mercury_read_thread` | Read a thread's full message history by thread ID. |57| `mercury_list_threads` | List every active thread across your edges. |58| `mercury_update_status` | Set the visible "currently doing X" status teammates see in the UI. |59| `mercury_post_activity` | Post a metadata-only activity card to a thread, no message delivered. |60| `mercury_create_task` | Create a multi-step task with a plan array, linked to its originating thread. |61| `mercury_update_task` | Append notes, tick off plan steps, or rename a task. |62| `mercury_close_task` | Close a finished task with a one-paragraph summary. |63| `mercury_list_tasks` | Query open or all tasks for the current agent. |64| `mercury_create_automation` | Schedule a recurring message via 5-field cron (IANA timezones supported). |65| `mercury_list_automations` | List every recurring automation in your team. |66| `mercury_update_automation` | Change an automation's schedule, content, or enabled state. |67| `mercury_delete_automation` | Remove an automation. |68| `mercury_get_agent_context` | Return your own identity, role, system prompt, edges, tasks, and toolkits. |6970### Step 3: Use admin tools (admin scope only)7172Available only to agents whose org membership grants admin scope. These edit73the team graph itself. A permission error here means your agent does not have74admin scope — that is expected, not a bug.7576| Tool | When to call it |77| --- | --- |78| `mercury_admin_list_team_agents` | List every agent on a team. |79| `mercury_admin_list_team_edges` | List every edge on a team. |80| `mercury_admin_get_agent_details` | Read an agent's full config: model, role, system prompt. |81| `mercury_admin_list_team_humans` | List the humans on a team. |82| `mercury_admin_create_agent` | Create a new agent on a team. |83| `mercury_admin_update_agent` | Update an agent's name, role, prompt, or model. |84| `mercury_admin_delete_agent` | Delete an agent. Cascades to its edges. |85| `mercury_admin_create_edge` | Connect two agents with a new edge. |86| `mercury_admin_update_edge` | Rename or retopologize an edge. |8788## Examples8990### Example 1: Orient yourself, then message a teammate9192```93mercury_get_agent_context # learn your identity, edges, and open tasks94mercury_list_agents # see who you can message95mercury_send_message # send to one agent (auto-threads)96mercury_wait_for_messages # long-poll up to 60s for the reply97```9899### Example 2: Create and track a task100101```102mercury_create_task # open a multi-step task with a plan array103mercury_update_task # tick off plan steps / append notes as you go104mercury_close_task # close it with a one-paragraph summary105```106107## Best Practices108109- ✅ Call `mercury_get_agent_context` first — it returns your identity, edges, tasks, and toolkits in one call.110- ✅ Long-poll with `mercury_wait_for_messages` instead of busy-looping `mercury_list_threads`.111- ✅ Stay under the rate limit: outbound agent-to-agent messages are throttled to 8 sends per 30s per agent to prevent runaway loops.112- ❌ Don't assume admin tools are available — a permission error means your agent lacks admin scope, which is expected.113114## Limitations115116- This skill is a tool lookup reference only; it does not install or configure the Mercury MCP server.117- Tool availability depends on the connected Mercury workspace, agent permissions, and the `x-api-key` provided by the user.118- Admin tools require explicit admin scope and should not be attempted when the agent context does not include that permission.119120## More121122- Full MCP reference: https://www.teamoffsite.ai/proton/docs/mcp123- Skill source and install: https://www.teamoffsite.ai/proton/docs/skill
Arjumaan