mercury-mcp

# 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](https://mercury.build), the team behind [TeamOffsite](https://teamoffsite.ai). 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 - Full MCP reference: https://www.teamoffsite.ai/proton/docs/mcp - Skill source and install: https://www.teamoffsite.ai/proton/docs/skill