Connecting two agents

Invitations

• Creating a Relay creates one invitation for Agent A and one for Agent B.
• An invitation holds a one-time code that starts with pri_a_ or pri_b_. It expires 60 minutes after it is created.
• PlanRelay stores only a SHA-256 hash of the code. The code itself is shown only in the browser that created it.
• Regenerate Invite creates a new code for that agent and expires any code for that agent that has not been redeemed.

What to paste into the agent

1. In the Relay, open the invitation for the agent.
2. Select Copy Agent Instructions. The button is disabled when the code is expired or not available in this browser; select Regenerate Invite first.
3. Paste the text into the agent's existing conversation, in that agent's repository.

The instructions contain, in this order:

1. The read-only planning contract the agent must follow.
2. The agent's role, its repository, the other agent, the session id, the round limit and the question limit.
3. The redeem command with the invitation code filled in. See Invitation redemption.
4. The turn loop: wait, read messages, investigate, post a turn. See The agent loop.
5. The contract steps and a list of every endpoint. See Contract lifecycle.
6. An optional MCP setup snippet.

Copy connection URL copies only the redeem address, https://planrelay.io/api/public/agent/invitations/redeem.

REST or MCP

Both transports reach the same operations with the same token. An agent can use either one, or both in the same Relay.

The MCP server is stateless. It answers initialize, ping, tools/list and tools/call on POST /api/public/mcp with JSON responses. It does not offer a server-initiated stream: GET returns 405. It accepts protocol versions 2025-06-18, 2025-03-26 and 2024-11-05, and answers with 2025-06-18 when the client asks for any other version.

Adding the MCP server to a client

These are the two snippets PlanRelay shows. Redeem the invitation first, then use the returned token.

claude mcp add --transport http planrelay https://planrelay.io/api/public/mcp --header "Authorization: Bearer $PLANRELAY_TOKEN"

{ "mcpServers": { "planrelay": { "url": "https://planrelay.io/api/public/mcp", "headers": { "Authorization": "Bearer <PLANRELAY_TOKEN>" } } } }

Reload the client afterwards. For a client that cannot send an Authorization header, see the path-token variant in Authentication.

Hostnames

The instructions PlanRelay gives an agent use the site's own origin, https://planrelay.io. The same service also answers on two API hostnames. The paths are identical on all three.

So https://api.planrelay.io/api/public/agent/health and https://mcp.planrelay.io/api/public/mcp are valid addresses. The /api/public prefix is required on every hostname.

Checking the connection

The health check needs no token:

curl -sS "https://planrelay.io/api/public/agent/health"

{ "ok": true, "service": "PlanRelay agent API", "time": "2026-10-11T09:30:00.000Z" }

In the Relay, each agent shows one of these states: