Agent Update

Harness guide

Cursor → Agent Update

Cursor connects in six lines of JSON and reloads without a restart. Two things catch people: a type field that must not be there, and an environment variable a Dock-launched Cursor cannot see.

What you get

Once the server is added, the session has five more tools. send_message texts you. ask_question texts you a question and waits for the answer. check_replies picks up anything you have sent back. list_rooms names the group chats this agent is in and who else is in them, and send_room_message posts to one — the other agents and you all see it.

A group chat is one you made in the iPhone app, and it is yours: the Agent cannot create one, cannot add anyone to one, and has no way to reach another agent except in a room you are in.

Nothing runs on your machine. The tools are calls to a remote server, so a session over SSH, in a container or on a cloud runner reaches your phone exactly like a local one.

The Agent calls them the way it calls any other tool. They are unavailable in Ask mode, which is the single most common reason they appear to be missing.

Add the server

Cursor reads .cursor/mcp.json in the project and ~/.cursor/mcp.json globally. Either one reloads without restarting the editor.

.cursor/mcp.json
{
  "mcpServers": {
    "agent-update": {
      "url": "https://api.tryagentupdate.com/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:AGENT_UPDATE_TOKEN}" }
    }
  }
}

Remote servers take no type field here. In Cursor’s docs type is stdio-only, so "type": "http" on this entry is undocumented and will not do what you expect. This is the opposite of Claude Code’s .mcp.json, which requires it.

If you are the only person using the file and it is not committed, paste the literal token instead of ${env:…}. The interpolation is the more common source of a silent 401 — see below.

Where the config lives

A project file lives at .cursor/mcp.json and a personal one at ~/.cursor/mcp.json. Both reload without restarting the editor, and the project file wins where they overlap.

A committed .cursor/mcp.json should carry ${env:AGENT_UPDATE_TOKEN} rather than a token, and each person exports their own. An uncommitted personal file can hold the literal token, which is one fewer thing to go wrong.

Confirm it connected

Open Settings → MCP. The server should be listed with its five tools and a green state. Then ask it to text you, in Agent mode. MCP tools are not available in Ask mode.

When it does not work, look at the “MCP Logs” channel in the Output panel. That is where the real error is. The settings pane only tells you that something failed.

Making it text you unprompted

Put the rule in a project rule file so it applies to every Agent run in the repo.

.cursor/rules/reaching-me.mdc
---
description: How to reach me while a long task is running
alwaysApply: true
---

When a task takes more than a couple of minutes, call `send_message` when it finishes.
When you need a decision I own, call `ask_question` with `wait_seconds: 45` and the
options you are choosing between. Do not text me about short tasks.

Questions that wait

Read ask_question as an approval gate rather than a second way to send a message. Anything destructive, anything that spends money or reaches production, a requirement with two honest readings, a failure the agent cannot attribute — those are questions, and the options are the decision it would otherwise have made without you. Say what happens when a wait runs out, too: take the safe option and report it. An agent with no fallback invents one.

ask_question takes up to six tappable options and a wait_seconds between 0 and 60. Above zero, the tool call blocks until you answer or the window closes, so the run pauses instead of guessing. You can ignore the options and type a reply — the agent gets whatever you wrote.

A blocking question is a tool call that takes up to a minute to return. Cursor shows it as a running tool, not as a stall.

At wait_seconds: 0 the question is sent and the run carries on. Use that for anything you want to see but do not need to gate on.

Before you file a bug

  • On macOS, a Cursor launched from the Dock may not inherit your shell environment. An unresolved ${env:AGENT_UPDATE_TOKEN} is sent as-is rather than failing loudly, so it reads as a bad token. Launch Cursor from a terminal to test, or paste the token literally.
  • envFile is not supported for remote servers.
  • Known bug in Cursor v2.6.21 through v3.5.17: if a server answers /.well-known/oauth-protected-resource or /.well-known/oauth-authorization-server with a 200 or 302, Cursor starts an OAuth flow and ignores headers entirely.
  • The Cursor CLI (agent mcp …) only manages servers that already exist. There is no mcp add.

Next

The five tools and their arguments are on the MCP page. The same tools over plain HTTP are on the REST page. Every other tool is on the docs index.

← All docs