AgentGrid

Core Concepts

Remote MCP access

Let an agent on another machine, such as Grok Bot or Claude Code, list, read and message your panes and direct a Coordinator through the AgentGrid relay.

Remote access gives an agent that isn't on your computer an MCP URL and a token, so it can see your panes, message them and direct a Coordinator. It reaches your computer through the AgentGrid relay, the same way the phone app does. It's in beta.

You need to be signed in to AgentGrid, and the background service must be running (see System tray and daemon).

Create a token

1. Open Settings → MCP Server and find Remote access (beta).
2. Select Create token.
3. Copy the URL (it starts with https://agentgrid-relay.agentgrid.workers.dev/v1/mcp/) and the token. The token is shown once; after you select I’ve saved it it can't be shown again. Create a new one if you lose it.

We may add a shorter branded address later; URLs you've already set up will keep working.

Each token belongs to this computer. Create one per agent, so you can cut one off without touching the others. Settings lists each token by its ID, the start of the token (like agr_536d5ac7), and when it was created, so you can match it to the agent you gave it to.

Connect an agent

Grok Bot: add a custom MCP server with the URL, and add the header Authorization: Bearer <token>.

Claude Code on another machine:

claude mcp add --transport http agentgrid <url> --header "Authorization: Bearer <token>"

Any MCP client that speaks Streamable HTTP and can send that header works the same way. claude.ai connectors aren't supported yet, because they need OAuth.

What a remote agent can do

Remote agents get ten tools: list_tabs, list_panes, search_panes, read_pane, send_message, wait_for_pane, wait_for_any, list_coordinators, ask_coordinator and get_coordinator_reply. They can't type into terminals, or open, close or move panes themselves.

A token can now direct a Coordinator. The Coordinator acts on the message with the full authority it has in the app, so it can do what those tools can't, such as creating team leads or closing panes. Give a token only to an agent you'd trust to ask for that.

Ask a Coordinator

An external assistant can ask a Coordinator about a project or hand it work. This works for any connected client, local or remote.

• list_coordinators lists Coordinator (all) first, then one per open project. If the Coordinator is off, you get an empty list and enabled: false.
• ask_coordinator sends a message. Leave out project (or use all) for the all-projects Coordinator, or pass a space ID, tab title or project folder. It waits for the reply for up to timeoutMs (30000 by default, 300000 at most), and wait: false returns as soon as the message is accepted.
• get_coordinator_reply checks on a message by its handle, without waiting. A handle keeps working after a restart, and only the client that asked can use it.

Each reply has a status: pending, done or failed, with reply and error when there's something to report. A turn that's still running keeps going after the wait ends, so call get_coordinator_reply later.

If the Coordinator is busy, your message queues as a follow-up and never interrupts the running turn. The reply then comes from that shared turn and carries sharedTurn: true.

Each message appears in the conversation with its sender, like From MCP client: Muse. A local client is named after its connection. A remote client is named by what it says it is plus its token ID, like Grok (agr_536d5ac7). Only the token ID is verified, so treat the name in front of it as a claim. Each client can ask 10 times a minute, and slash commands from the phone app don't run this way.

Muse, connected on this computer, asking about one project:

{ "project": "agent-grid", "message": "Are the release tests green?" }

Grok Bot, through the relay, handing off a longer job and checking back:

{ "message": "Summarize what every team finished today", "wait": false }

{ "handle": "<handle from ask_coordinator>" }

Some clients give up on a call after about a minute. If yours does, use wait: false and get_coordinator_reply.

Security

• Requests travel over TLS to the AgentGrid relay and on to your computer. The relay can read them: they are not end-to-end encrypted, unlike the phone app.
• The relay doesn't check or store your token; your computer does, on every request.
• OAuth and end-to-end encryption are planned.

Revoke a token

Select Revoke next to the token's ID in Remote access (beta). The next request with that token is refused. When the last token is revoked, your computer stops holding the relay connection open. After that, remote callers get a "desktop is offline" error rather than an authorization error.

[

Coordinator

One ongoing conversation that starts, follows and steers your team leads, from your desk or your phone.

](https://agentgrid.sh/docs/concepts/coordinator)[

Auto-switch

Keep a turn going on another account or model when usage runs out.

](https://agentgrid.sh/docs/concepts/auto-switch)