Relay MCP Tools

The Relay MCP server is the agent-facing interface to the platform. This page explains what tools exist, which ones a client sees by default, and which appear based on the connection.

How the surface is shaped

Three buckets, decided by one test — is this a pipe verb (an agent needs it mid-task) or a management verb (a human curating)? Pipe verbs ship in MCP; management verbs live in the app.

• Directory default (the host profile) — the lean set a fresh client sees, and what gets submitted to MCP directories (ChatGPT, Cursor, etc.). Core pipe verbs only: create, receive, inspect, search.
• Connection-gated (the platform set) — more tools appear once you authenticate, filtered by tier/features. Management, identity, and org/team-tier verbs.
• App-only (never tools) — capabilities that deliberately never become pullable tools because they're curation surfaces, not pipe verbs (saved searches, history, series/pulse management UI).

Gating is still being built

The dynamic tools/list filtering + the GET /api/user/v1/features endpoint that enforce this split are in progress. Today the server exposes the full set to every authenticated session; the directory/host-profile subset below is the target shape, not yet enforced.

Directory default — the host profile (~12 core pipe verbs)

Tool	What it does
relay_context_get	Load session state at boot — tasks, goals, history; detects an inbound handoff.
relay_search	Keyword discovery across the workspace (relays, pulses, series, sessions).
relay_lookup	Resolve any Code/ID → {type, metadata, next_action_hint}. (planned, #1207)
relay_transfer_create	Create a relay; returns a Code.
relay_transfer_receive	Receive a relay by Code. Two-step: preview (confirm=false) → receive (confirm=true).
relay_transfer_list	List your relays (default: pending).
relay_resource_get	Read a relay by Code without consuming it.
relay_series_create	Create a named series container to group sequential relays.
relay_series_receive	Receive the latest relay in a series.
relay_pulse_active	The pulse bound to the current workspace — zero-config context discovery.
relay_pulse_update	Add, edit, or archive Items in a pulse.
relay_session_package	Package the current session into a session_handoff relay; returns a Code.

Connection-gated — the fuller platform set

Appears once authenticated, filtered by tier/features:

• Transfer management: relay_transfer_get · relay_transfer_update · relay_transfer_forward · relay_transfer_recent
• Series management: relay_series_get · relay_series_list · relay_series_expire
• Pulse management: relay_pulse_create · relay_pulse_get · relay_pulse_list · relay_pulse_archive · relay_pulse_suggest_maintenance
• Session management: relay_session_browse · relay_session_get · relay_session_list · relay_session_log · relay_session_close · relay_session_update · relay_session_aftercare
• Requests: relay_request_list · relay_request_list_sent · relay_request_respond · relay_request_cancel
• Identity / workspace: relay_profile_get · relay_workspace_switch
• Org / team-tier (planned, gated behind team tier): relay_org_members · relay_org_invite · relay_org_switch

App-only — intentionally not tools

These are browse/curation surfaces; an agent has no reason to pull them mid-task:

• Saved searches and search history — the user curating and revisiting.
• Series & pulse management UI, library curation — managed in the app.

Currently mis-exposed

relay_search_saved and relay_search_history are still exposed as MCP tools but are slated for removal — per the search-as-primitive decision, history/saved are app-only, not pullable.

relay_search vs relay_lookup

The two halves of search-as-router:

	relay_search	relay_lookup
You have	a question / keywords	a Code or ID already in hand
It answers	"find me things matching X"	"what is this, and what do I do with it?"
Returns	ranked matches	{type, metadata, next_action_hint}
Use when	discovering	you were handed a bare Code (Slack, boot prompt) and don't know its type

relay_lookup closes the common gap where an agent gets a Code with no type context and doesn't know whether to call relay_transfer_receive, relay_series_receive, or relay_pulse_get. Resolution order: code pattern → transfer; series name → series; pc_* → pulse; session ID → session; else fuzzy match.

Vocabulary

Tool output uses the locked canonical vocabulary: Code (not PIN/relay ID), receive (not claim), relay (the object, user-facing), transfer (the object, API-facing), Item (a pulse content unit).

Known residue (cleanup in flight)

• relay_claim_transferArguments — not a tool; it's the auto-generated arg schema name for the receive tool, derived from the handler still internally named relay_claim_transfer (pre-rename). The canonical surface name is relay_transfer_receive.
• receiver_model — advertised as an optional "which model received this" param (maps to claimer_model in the REST contract), but the deployed input model forbids extra fields, so passing it currently errors. To be reconciled.
• relay_search_saved / relay_search_history — exposed but should be app-only (see warning above).
• relay_lookup — specced (#1207) but not yet shipped.

These are all residue from the relay_{noun}_{verb} naming migration and the partial deploy of the receive handler; a cleanup pass is in flight.

---

Source of truth: docs/SPEC.mcp.md in relay-platform. This page is the curated team-KB view. Last updated 2026-06-14.