AgentGrid

Verbinde entfernte KI-Assistenten mit AgentGrid: Lies Nachrichten von Coding-Agent-Teams und sende ihnen welche, und delegiere Aufgaben an einen Coordinator. Erstelle deine persönliche MCP-URL und dein Token in der App.

Dokumentation

Core Concepts

Remote MCP access

Let an app on another machine, such as Claude Code or Hermes, list, read and message your panes and direct a Coordinator through one AgentGrid URL.

Remote access gives an app that isn't on your computer one MCP URL, https://mcp.agentgrid.sh/mcp. The app signs in with your AgentGrid account, then it can see your panes, message them and direct a Coordinator. The sign-in flow below reaches AgentGrid on your Mac. It goes through the AgentGrid relay, the same way the phone app does.

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

Connect an app

On a Mac, open Settings → MCP Server. Connect from anywhere shows the URL with Copy URL; copy it from there. Add to an app lists each app:

  • Add sets up the server in that app on this computer. Once AgentGrid detects its URL in the config, the button shows ✓ Added. Apps added with the earlier https://agentgrid-relay.agentgrid.workers.dev/v1/mcp address keep working and also show ✓ Added.
  • Switch appears for an app still set up with the old local server when automatic setup is supported (except Claude Desktop). It replaces that entry with the URL and revokes the old local token.
  • Claude Desktop: Add copies the URL and opens Claude. Paste it under Customize → Connectors → + Add → Add custom connector. This manual step does not change the button to ✓ Added.
  • Manual shows where the entry goes and the exact config or command, with a copy button. Use it for an app on another machine, or one Add can't write (Muse).

Copy agent prompt copies instructions you can paste to an agent so it adds the server to itself.

Apps still on the old local server are also listed under Local server (deprecated), with Remove to take the entry out of the app's config. Switch them above when you can.

Sign in

The first time the app connects, it asks you to sign in with your AgentGrid account:

  • In a browser: the app opens a sign-in page, or gives you a link. Approve it and you're done.
  • On a machine with no browser (a VPS, an SSH session): use the device-code flow if the app has one. The app prints a short code and a link to agentgrid.sh/device. Open it on any device, sign in, and type the code shown if it isn't filled in. The page shows the code with "Check this matches the code on your device"; if it matches, select Allow. The code expires in 10 minutes. Approve only a code you started yourself. For example, hermes mcp login agentgrid --flow device.

Some apps need a command to start the sign-in. Manual shows it under the snippet:

AppSign-in
Claude CodeRun /mcp in Claude Code
Codexcodex mcp login agentgrid
Gemini CLIRun /mcp auth agentgrid in Gemini CLI
Hermeshermes mcp login agentgrid --flow device
Musemuse mcp login agentgrid
OpenClawopenclaw mcp login agentgrid
OpenCodeopencode mcp auth agentgrid

Claude Desktop and Cursor start the sign-in themselves when they first connect. Grok (the CLI) is not Grok Bot: its sign-in isn't verified yet and may need a token header instead.

Claude Code on another machine (use the URL from Settings → MCP Server):

claude mcp add --transport http --scope user agentgrid https://mcp.agentgrid.sh/mcp

Then run /mcp in Claude Code to sign in.

Any MCP client that speaks Streamable HTTP and supports OAuth sign-in works the same way. Grok Bot, a different app from the Grok CLI, can't sign in this way yet; it works only with an existing agr_ token (see Old tokens).

What a remote app can do

With a Mac online, remote apps get eleven tools: list_devices, 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. When no Mac is online, only list_devices is listed.

Pick a Mac. list_devices lists the Macs on your account, with name, online state and last seen. Every other tool takes an optional device: a device ID or exact name from that list. You can leave it out while only one Mac is online; with several online, the call asks you to pick one.

On the free plan an app reaches one Mac, the oldest one registered on your account. AgentGrid Pro reaches all of them.

Any app you sign in can 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. Sign in only apps 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 app is named by what it says it is plus an ID AgentGrid checks: oauth_ and the start of its sign-in client ID for an app you signed in, like Claude Code (oauth_3f9a1c2e), or the token ID for an old token, like Grok (agr_536d5ac7). Only the 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?" }

Claude Code, on another machine, 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 Mac. The relay can read them: they are not end-to-end encrypted, unlike the phone app. End-to-end encryption is planned.
  • A sign-in gives the app an access token that lasts 10 minutes and a refresh token that lasts 14 days. No token is written into the app's config.
  • Connected apps (in the account menu) lists each app you signed in, with its ID, connection date and latest token issuance ("Token issued 2 h ago" or "No token issued"). This records sign-in or refresh, not the app's last tool call. To cut an app off, select Revoke there. The website cuts it off at once; the relay and your Macs refuse it within 10 minutes, once its last access token expires. Removing the entry from the app's config alone doesn't revoke its sign-in.

See Security and privacy for when your Mac connects to the relay.

Old tokens

Tokens you created before (they start with agr_) keep working. Settings → MCP Server lists them under Old tokens with their ID and when each was last used, like "Used 2 d ago" or "Never used". On a Mac, new tokens can't be created.

Select Revoke next to a token's ID to cut it off. The next request with that token is refused. The relay doesn't check or store these tokens; your Mac does, on every request.

On Windows and Linux

The URL sign-in above is for a Mac. On Windows and Linux, Settings → MCP Server keeps the local cards, and Remote access (beta) creates tokens.

  1. Find Remote access (beta) and select Create token.
  2. 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.
  3. In Grok Bot, add a custom MCP server with the URL and the header Authorization: Bearer <token>. In Claude Code on another machine:
claude mcp add --transport http agentgrid <url> --header "Authorization: Bearer <token>"

Each token belongs to this computer, so create one per agent. Settings lists each by ID (like agr_536d5ac7). Select Revoke next to an ID to cut it off. claude.ai connectors aren't supported, because they need OAuth.

[

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)