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.

The MCP server should expose:

first-class messaging tools
workspace and identity tools
delivery and inbox tools
generated tools for registered actions
optional diagnostics for the current workspace

Start The MCP Server

agent-relay mcp start --workspace "$RELAY_WORKSPACE_KEY"

The workspace key connects the MCP server to the same workspace as your SDK app, runtime, and harness adapters.

For local development, a setup command can create a workspace and write the key to a project or user config.

agent-relay workspace create support-triage
agent-relay mcp install --workspace "$RELAY_WORKSPACE_KEY"

Core Messaging Tools

Messaging primitives should stay first class because agents use them constantly.

Tool	Purpose
`register_agent`	Register the current MCP client as a Relay participant.
`list_agents`	Show agents and session status in the workspace.
`join_channel`	Join a named channel.
`leave_channel`	Leave a named channel.
`list_channels`	Show channels available in the workspace.
`send_message`	Send a channel message, DM, group DM, or thread reply.
`reply`	Reply to an existing thread.
`react`	Add a reaction to a message.
`list_inbox`	Read inbox state for the current agent.
`mark_read`	Mark a message or thread read.
`subscribe_events`	Subscribe to workspace or session events when the host supports streaming.

The exact tool names can be host-friendly, but the concepts should map directly to the SDK messaging API.

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 send_message to announce readiness or ask for work.
Receive live events or inspect list_inbox.
Call generated action tools such as agent.create or ui.show_search_results.
Call reply, react, or mark_read as work progresses.

Generated Action Tools

Registered actions should become explicit MCP tools whenever possible.

sdk-actions.ts

relay.actions.register({
  name: 'review.submit_vote',
  description: 'Submit a review vote for the current proposal.',
  inputSchema: z.object({
    proposalId: z.string(),
    vote: z.enum(['approve', 'request_changes', 'abstain']),
    reason: z.string().optional(),
  }),
  handler: async (input, ctx) => {
    await reviewStore.recordVote(ctx.caller, input);
    return { recorded: true };
  },
});

The MCP server can expose 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.

Generic tools such as actions.list and actions.invoke can exist for dynamic hosts, but generated explicit tools should be the default.

Action Result Shape

Tool results should preserve the action envelope.

{
  "ok": true,
  "action": "review.submit_vote",
  "invocationId": "act_123",
  "output": {
    "recorded": true
  }
}

Errors should also be structured.

{
  "ok": false,
  "action": "review.submit_vote",
  "invocationId": "act_124",
  "error": {
    "code": "permission_denied",
    "message": "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:

list_inbox
mark_read
flush_deliveries
list_events
generated action result tools

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

Runtime-managed sessions can register action tools such as:

agent.create
agent.release
agent.status
agent.pause
agent.resume

Those tools are runtime-provided actions. Core MCP only needs the action protocol and generated tool surface.