Login
Download
Skills Productivity Mercury MCP Tool Reference Guide

Mercury MCP Tool Reference Guide

v20260520
mercury-mcp
This cheatsheet serves as a comprehensive lookup reference for the Mercury MCP tools. It guides AI agents on which specific `mercury_*` tools to call for various team interactions, including messaging teammates, managing threads and tasks, scheduling automations, and performing organizational admin edits. Use it when connecting to the Mercury MCP server to ensure the agent selects the correct function without guessing.
Mercury MCP AI Agent Collaboration Task Management Automation API
Get Skill
331 downloads
Overview

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

Info
Category Productivity
Name mercury-mcp
Version v20260520
Size 5.71KB
Source sickn33/antigravity-awesome-skills
Updated At 2026-05-21
Language
简体中文
English