Agent Relay MCP

Expose Relay messaging and registered actions to agents as MCP tools.

agent-relay mcp is how agents use Relay when they cannot or should not embed the SDK.

agent-relay mcp registers three groups of tools:

workspace and agent tools (register_agent, list_agents, add_agent, remove_agent, create_workspace, set_workspace_key, spawn, submit_result, query_nodes)
messaging and inbox tools (the table below)
action tools (list_actions, invoke_action, plus one generated tool per registered action)

Start The MCP Server

agent-relay mcp is a stdio MCP server with no subcommands. It reads its configuration from environment variables; set the workspace key before launching:

RELAY_WORKSPACE_KEY="$RELAY_WORKSPACE_KEY" agent-relay mcp

The workspace key connects the MCP server to the same workspace as your SDK app, runtime, and harness adapters. Create a workspace first if you do not have a key:

agent-relay workspace create support-triage

Messaging Tools

Tool	Purpose
`create_channel`	Create a channel.
`join_channel`	Join a named channel.
`leave_channel`	Leave a named channel.
`list_channels`	Show channels available in the workspace.
`invite_to_channel`	Invite an agent to a channel.
`set_channel_topic`	Set a channel topic.
`archive_channel`	Archive a channel.
`post_message`	Post a channel message.
`send_dm`	Send a direct message.
`send_group_dm`	Send a group DM.
`reply_to_thread`	Reply in a message thread.
`get_message_thread`	Read a message and its replies.
`list_messages`	List channel messages.
`list_dms`	List direct-message conversations.
`search_messages`	Search messages.
`add_reaction` / `remove_reaction`	Add or remove an emoji reaction.
`check_inbox`	Read inbox state for the current agent.
`mark_message_read`	Mark a message read.
`get_message_readers`	List who has read a message.

These tools are registered by registerMessagingTools (see packages/cli/src/cli/mcp/messaging-tools.ts).

Example Agent Tool Flow

An agent using MCP can coordinate without SDK imports:

Call register_agent with its name and handle.
Call join_channel for #planning.
Call post_message to announce readiness or ask for work.
Inspect check_inbox.
Call a generated action tool (each registered action is exposed by name), or invoke_action / list_actions.
Call reply_to_thread, add_reaction, or mark_message_read as work progresses.

Generated Action Tools

Each registered action becomes an explicit MCP tool.

sdk-actions.ts

// register on an agent client so the action is exposed as an MCP tool
coordinator.registerAction({
  name: 'review.submit_vote',
  description: 'Submit a review vote for the current proposal.',
  input: z.object({
    proposalId: z.string(),
    vote: z.enum(['approve', 'request_changes', 'abstain']),
    reason: z.string().optional(),
  }),
  handler: async ({ input, agent }) => {
    await reviewStore.recordVote(agent.name, input);
    return { recorded: true };
  },
});

The MCP server exposes a review.submit_vote tool with JSON Schema derived from the Zod schema. Agents see a clear tool name and input shape instead of a generic text instruction.

Actions are fire-and-forget: calling the tool returns an acknowledgement immediately, and the handler's return value is emitted as action.completed to your listeners — not inline to the calling agent. If the agent needs the result, message it from the handler.

Action Result Shape

Because invocation is fire-and-forget, a successful tool call returns the acknowledgement — an invocationId, not the handler's output:

{
  "ok": true,
  "status": "invoked",
  "invocation": {
    "invocationId": "act_123",
    "actionName": "review.submit_vote"
  }
}

A failed invocation returns an error string:

{
  "ok": false,
  "error": "Planner cannot vote on this proposal."
}

Caller Identity

The MCP server must identify the caller for policy and audit.

type McpCaller = {
  type: 'agent';
  id: string;
  name?: string;
  handle?: string;
  sessionId?: string;
};

For local hosts, identity may start from the MCP server config. For managed sessions, the runtime can install MCP config with the session id and workspace key already bound.

Delivery Through MCP

MCP is also a delivery path.

If the host supports streaming, the MCP server can push message.created, delivery.*, action.*, and session.event notifications to the agent.

If the host does not support live subscriptions, the MCP tools still provide durable fallbacks:

check_inbox
mark_message_read
list_actions
invoke_action

Relay should not rely on agents voluntarily checking an inbox as the only path. MCP should work alongside WebSockets, harness callbacks, and delivery adapters.

Tool Safety

MCP tools should:

validate inputs against the SDK schemas
use workspace key scoping
attach caller identity to messages and action invocations
return structured errors
emit audit events for action calls
avoid exposing raw terminal, transcript, or file data unless the session capability and workspace policy allow it

Runtime Integration

registerDriverActions (from @agent-relay/harness-driver) registers agent.create, agent.release, and agent.status as actions, plus agent.attach when the driver implements attach. They surface as MCP tools like any other registered action.