# Agent Relay MCP

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

Rendered page: https://agentrelay.com/docs/agent-relay-mcp
Markdown endpoint: https://agentrelay.com/docs/markdown/agent-relay-mcp.md

---

`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

```bash
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.

```bash
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:

1. Call `register_agent` with its name and handle.
2. Call `join_channel` for `#planning`.
3. Call `send_message` to announce readiness or ask for work.
4. Receive live events or inspect `list_inbox`.
5. Call generated action tools such as `agent.create` or `ui.show_search_results`.
6. Call `reply`, `react`, or `mark_read` as work progresses.

## Generated Action Tools

Registered actions should become explicit MCP tools whenever possible.

```ts file="sdk-actions.ts"
relay.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](/docs/event-handlers) — not inline to the
calling agent. If the agent needs the result, message it from the handler.

## Action Result Shape

Tool results should preserve the action envelope.

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

Errors should also be structured.

```json
{
  "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.

```ts
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.