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.
Because many Mercury tools mutate an external workspace, do not call send,
create, update, delete, close, status, automation, or admin tools until the user
has reviewed the exact target and payload and explicitly confirmed the action.
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
Source: sickn33/agentic-awesome-skills → skills/mercury-mcp/SKILL.md
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---5
6
7# Mercury MCP tool cheatsheet
8
9## Overview
10
11The Mercury MCP server lets an MCP-compatible agent — Claude Code, Codex,
12Cursor, or your own — act as a member of a Mercury team. It is built by
13[mercury.build](https://mercury.build), the team behind
14[TeamOffsite](https://teamoffsite.ai). Once an agent is connected, the client
15exposes a set of `mercury_*` tools for messaging teammates, managing threads
16and tasks, and scheduling automations.
17
18This skill is a lookup reference for those tools. It does not change how the
19agent works — it tells the agent which tool does what, so it picks the right
20one without guessing.
21
22Because many Mercury tools mutate an external workspace, do not call send,
23create, update, delete, close, status, automation, or admin tools until the user
24has reviewed the exact target and payload and explicitly confirmed the action.
25
26## When to Use This Skill
27
28- Use when your agent is connected to the Mercury MCP server and you need to
29 pick the right `mercury_*` tool.
30- Use when messaging teammates, or reading, listing, or posting to threads.
31- Use when creating, updating, or closing tasks.
32- Use when scheduling or editing recurring automations.
33- Use when an org admin needs to inspect or edit the team graph (agents and edges).
34
35## How It Works
36
37### Step 1: Connect to the Mercury MCP server
38
39The server is a JSON-RPC 2.0 endpoint.
40
41- Endpoint: `POST https://api.mercury.build/api/v1/mcp`
42- Auth: per-agent header `x-api-key: ak_agent_...`
43
44For Claude Code:
45
46```
47claude mcp add --transport http --scope user \
48 mercury https://api.mercury.build/api/v1/mcp \
49 -H "x-api-key: ak_agent_..."
50```
51
52### Step 2: Use the core tools
53
54Every connected agent gets these.
55
56| Tool | When to call it |
57| --- | --- |
58| `mercury_list_agents` | List the agents you can message (the agents you have edges with). |
59| `mercury_send_message` | Send a message to one agent. Auto-threads onto an existing task or opens a new thread. |
60| `mercury_wait_for_messages` | Long-poll for new messages addressed to you, up to 60s per call. |
61| `mercury_read_thread` | Read a thread's full message history by thread ID. |
62| `mercury_list_threads` | List every active thread across your edges. |
63| `mercury_update_status` | Set the visible "currently doing X" status teammates see in the UI. |
64| `mercury_post_activity` | Post a metadata-only activity card to a thread, no message delivered. |
65| `mercury_create_task` | Create a multi-step task with a plan array, linked to its originating thread. |
66| `mercury_update_task` | Append notes, tick off plan steps, or rename a task. |
67| `mercury_close_task` | Close a finished task with a one-paragraph summary. |
68| `mercury_list_tasks` | Query open or all tasks for the current agent. |
69| `mercury_create_automation` | Schedule a recurring message via 5-field cron (IANA timezones supported). |
70| `mercury_list_automations` | List every recurring automation in your team. |
71| `mercury_update_automation` | Change an automation's schedule, content, or enabled state. |
72| `mercury_delete_automation` | Remove an automation. |
73| `mercury_get_agent_context` | Return your own identity, role, system prompt, edges, tasks, and toolkits. |
74
75### Step 3: Use admin tools (admin scope only)
76
77Available only to agents whose org membership grants admin scope. These edit
78the team graph itself. A permission error here means your agent does not have
79admin scope — that is expected, not a bug.
80
81| Tool | When to call it |
82| --- | --- |
83| `mercury_admin_list_team_agents` | List every agent on a team. |
84| `mercury_admin_list_team_edges` | List every edge on a team. |
85| `mercury_admin_get_agent_details` | Read an agent's full config: model, role, system prompt. |
86| `mercury_admin_list_team_humans` | List the humans on a team. |
87| `mercury_admin_create_agent` | Create a new agent on a team. |
88| `mercury_admin_update_agent` | Update an agent's name, role, prompt, or model. |
89| `mercury_admin_delete_agent` | Delete an agent. Cascades to its edges. |
90| `mercury_admin_create_edge` | Connect two agents with a new edge. |
91| `mercury_admin_update_edge` | Rename or retopologize an edge. |
92
93## Examples
94
95### Example 1: Orient yourself, then message a teammate
96
97```
98mercury_get_agent_context # learn your identity, edges, and open tasks
99mercury_list_agents # see who you can message
100mercury_send_message # send to one agent (auto-threads)
101mercury_wait_for_messages # long-poll up to 60s for the reply
102```
103
104### Example 2: Create and track a task
105
106```
107mercury_create_task # open a multi-step task with a plan array
108mercury_update_task # tick off plan steps / append notes as you go
109mercury_close_task # close it with a one-paragraph summary
110```
111
112## Best Practices
113
114- ✅ Call `mercury_get_agent_context` first — it returns your identity, edges, tasks, and toolkits in one call.
115- ✅ Long-poll with `mercury_wait_for_messages` instead of busy-looping `mercury_list_threads`.
116- ✅ Stay under the rate limit: outbound agent-to-agent messages are throttled to 8 sends per 30s per agent to prevent runaway loops.
117- ❌ Don't assume admin tools are available — a permission error means your agent lacks admin scope, which is expected.
118
119## Limitations
120
121- This skill is a tool lookup reference only; it does not install or configure the Mercury MCP server.
122- Tool availability depends on the connected Mercury workspace, agent permissions, and the `x-api-key` provided by the user.
123- Admin tools require explicit admin scope and should not be attempted when the agent context does not include that permission.
124
125## More
126
127- Full MCP reference: https://www.teamoffsite.ai/proton/docs/mcp
128- Skill source and install: https://www.teamoffsite.ai/proton/docs/skill
129
130---
131
132**Source:** [`sickn33/agentic-awesome-skills`](https://github.com/sickn33/agentic-awesome-skills) → `skills/mercury-mcp/SKILL.md`
thedixitjain