MCP tools reference

You normally don't pick a server here — the agent-share CLI wires the right one for you (see Use it with Claude Code). This page is the lookup catalog for when you want to know exactly which tools an agent has and what each one takes.

Agent Share exposes two MCP servers with different tool sets, because they do different jobs:

The share.* tools (list/read/acknowledge/send) are the ones you'll care about most — they live on the hosted inbox server below.

Server A — hosted share-server /mcp

The hosted server is a remote MCP server at /mcp, scoped to a single inbox by its bearer token. These are the tools an agent uses to work an inbox.

Most tools accept an optional inboxSel object { inbox, key } to target a specific named inbox.

Inbox read tools

• share.list — list inbox items.

  • direction (default to_agent). direction=all also includes the agent's own to_phone replies.
  • status (default new; values new / received / all). new = unhandled (seenAt is zero), received = already acknowledged.
  • since (RFC3339) — time bound.

  The default query is direction=to_agent + status=new, so the agent sees only unhandled items unless it asks for more.

• share.get — id; returns metadata + text for one item.

• share.peek_text — id; returns the text only.

• share.get_frame — id; returns a PNG snapshot of a Kind==stream (live screen-mirror) share.

Inbox lifecycle tools

The lifecycle is three deliberately separate steps: read → acknowledge → optionally delete. Reading does not mark anything.

• share.mark_received — { id } or { ids: [...] }. Stamps seenAt so the item leaves the new view. Idempotent (first call wins) and does not delete.
• share.delete — { id }. Hard remove. Also calls RemoveResources, which notifies connected sessions. Prefer mark_received; only delete junk.

Send and agent management

• share.send — agent → phone. { title, body, kind?, text?, url? }. Writes a to_phone share and triggers Web Push (VAPID).
• agent.register — mints a separate inbox when bound to the owner-primary inbox.
• agent.heartbeat — keep the agent marked online.
• agent.unregister — remove the agent.

Webhook tools

Added 2026-06-18 for inbound webhook ingress. External systems (Coolify, CI) drop kind=event shares into the inbox.

• webhook.create — mint an inbound webhook URL.
• webhook.list — list webhook URLs (secrets masked).

Resource and notification

• Resource share://<id> — the canonical URI carrying the binary payload: a Blob for image/file kinds, URL text for url kind, and markdown for text kind.
• "new items" notification — when a share arrives, the server sends the standard MCP resources/list_changed signal so the agent's client refreshes, with no polling. It's a refresh signal, not a prompt: it does not inject the share into the conversation or interrupt the current turn. The agent only sees a new item when it next calls share.list. (For shares that push straight into a running session, see the research-preview channel server below and the channels page.) Using the standard signal keeps non-Claude clients like Cline and Cursor working too.

Server B — agent-side stdio CLI agent-share mcp

The CLI runs a local (stdio) MCP server. It's the entry agent-share install writes into ./.mcp.json.

agent-share mcp

On startup it registers this workspace as an agent and keeps it marked online for the life of the session. There's no token in the config — auth comes from your agent-share login.

Tools

• register — enroll/identify this agent.
• list — list items shared to this agent's inbox.
• get_agent_card — return this inbox's A2A connection card.
• task.list — list incoming A2A tasks.
• task.update — post progress on a task.
• task.complete — finish a task and return its result.

This server exposes no resources.

--personal mode

agent-share mcp --personal

Wired by agent-share init, this proxies through to your personal hosted inbox as the owner. In this mode the tools you actually get are the hosted share.* set (Server A), so you read and reply to your own phone shares.

Server C — channel server (research preview)

The agent-share channel command runs a separate stdio server — distinct from Server B — that implements Claude Code channels, a research-preview feature that does push content into a running session.

Research preview. Channels require Claude Code v2.1.80+ (permission relay v2.1.81+), Anthropic-only auth (not Bedrock/Vertex/Foundry), and the --dangerously-load-development-channels launch flag. The contract may change. See the channels concept page for the full model and the shipped-vs-aspirational distinction.

claude --dangerously-load-development-channels server:agent-share --dangerously-skip-permissions

Tools

• complete — complete a task.
• mark_received — acknowledge an item.
• get_agent_card — return the A2A card.
• register — enroll the inbox.
• list — list items.
• send_to_agent — relay a message to another agent.

How delivery differs

Unlike the hosted inbox's refresh signal, channel notifications inject content into the session mid-turn — an idle session wakes and the item lands in Claude's context as a <channel> tag. That's the whole point of channels, and also why it's gated behind the research-preview launch flag.

See also

• Use it with Claude Code — which command wires which server.
• CLI reference — every command and flag.
• Channels and the agent inbox — pull vs. push, in plain terms.