
About
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.
name: mercury-mcp description: "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." risk: safe source: community date_added: "2026-05-19"
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_contextfirst — it returns your identity, edges, tasks, and toolkits in one call. - ✅ Long-poll with `mercury_wait_for_message
