# Coding agents (MCP) (/agents/mcp)

Annoty's Model Context Protocol (MCP) server lets your coding agent work through a feedback session from your editor. It reads the open comments, finds the element each one is pinned to in your code, makes the fix, tells the reviewer what changed and resolves the thread. Claude Code, Cursor, Codex and any other agent that speaks MCP can use it. In Claude or ChatGPT, it can sum up a feedback session's comments, answer reviewers and open new feedback sessions.

## What the agent sees [#what-the-agent-sees]

Every comment comes with what the reviewer's browser showed when they pinned it:

| Field        | What the agent does with it                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| Element text | Searches your code for it. Usually the fastest way to the right file                |
| Element HTML | Matches its classes and attributes when the text is generated or appears many times |
| Page address | Finds the route, including the query string                                         |
| Window size  | Tells a phone layout bug from a desktop one                                         |
| Browser      | Tells a Safari bug from a Chrome one                                                |
| Screenshot   | Sees the page as the reviewer did, the element outlined: `get_comment` returns it   |

Older comments, made before the toolbar sent these fields, have only the page and the element's position. A comment has no [screenshot](/share/screenshots/) when the reviewer left it out or their browser couldn't take one.

## Connect your agent [#connect-your-agent]

Add the server to your agent. The first time it connects, it opens Annoty in your browser: sign in, check the organization, pick **Read** or **Read and write**, and click **Allow**.

<Tabs items={["Claude Code", "Claude", "ChatGPT", "Cursor", "Codex", "Other agents"]} groupId="agent" persist>
<Tab value="Claude Code">

```sh
claude mcp add --transport http --scope user annoty https://api.annoty.app/mcp
```

Then run `/mcp` in Claude Code, pick **annoty** and sign in.

</Tab>
<Tab value="Claude">

On claude.ai, or in the Claude desktop app:

<Steps>

1. Go to **Settings → Connectors** and click **Add custom connector**.

2. Name it "Annoty", enter `https://api.annoty.app/mcp` as the URL and click **Add**.

3. Click **Connect** beside Annoty and sign in.

</Steps>

On a Team or Enterprise plan, an owner adds the connector for the organization first, then each person connects their own account.

</Tab>
<Tab value="ChatGPT">

On chatgpt.com:

<Steps>

1. Open **Plugins**, click **+** and choose **Add custom MCP server**.

2. Name it "Annoty" and enter `https://api.annoty.app/mcp` as the **Server URL**.

3. Choose **OAuth** for authentication, confirm the warning and click **Create as a plugin**.

4. Install the plugin and sign in.

</Steps>

In a chat, type `@` and pick Annoty. ChatGPT asks you to confirm before the agent replies to or resolves a comment. In a Business, Enterprise or Edu workspace, an admin may need to allow plugins with custom MCP servers first.

</Tab>
<Tab value="Cursor">

In `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "annoty": { "url": "https://api.annoty.app/mcp" }
  }
}
```

Cursor asks you to sign in the first time it uses the server.

</Tab>
<Tab value="Codex">

```sh
codex mcp add annoty --url https://api.annoty.app/mcp
codex mcp login annoty
```

</Tab>
<Tab value="Other agents">

Use the Streamable HTTP transport with the URL `https://api.annoty.app/mcp`. Agents that support MCP's OAuth sign-in find it from the server's reply. For the others, use an [API key](#with-an-api-key).

</Tab>
</Tabs>

The agent acts as you: reviewers see its replies as "Your name via Claude Code", with the **Team** badge, and it can do what your role allows and you picked on the **Allow** page. Members with the **Admin** or **User** role can connect apps. A connection works in the organization you picked on the **Allow** page.

### With an API key [#with-an-api-key]

An agent that runs on its own, like a CI job or a [scheduled task](/agents/send-to-agent/), has nobody to sign in. Give it an API key instead:

<Steps>

1. In the dashboard, go to **Settings → API keys** and click **Create API key**.

2. Name it after the agent, like "Claude Code". Reviewers see the agent's replies under this name, with the **Team** badge.

3. Keep the default permissions. The agent needs **View**, **Reply** and **Resolve** under **Comments**, and **Create** under **Projects** and **Feedback sessions** to set up a site. Copy the key: the dashboard shows it once.

4. Send it in the `Authorization` header:

   ```sh
   claude mcp add --transport http annoty https://api.annoty.app/mcp \
     --header "Authorization: Bearer your_api_key_here"
   ```

   In Cursor's `mcp.json`, add `"headers": { "Authorization": "Bearer your_api_key_here" }` next to `url`. In Codex, put the key in an environment variable and pass `--bearer-token-env-var ANNOTY_API_KEY` to `codex mcp add`.

</Steps>

<Callout type="warn" title="Keep the key out of your repository">
  The key reads and answers your comments. Put it in your agent's user-wide
  config or an environment variable, not in a config file you commit.
</Callout>

## Let it set up your site [#let-it-set-up-your-site]

The dashboard's **Overview** has the setup steps: connect the agent, then **Copy setup prompt** and paste it in your site's repository. The agent finds the site's domain and preview deploys, creates the project, and picks how reviewers open it:

- In the site's code, it adds the [embed script](/share/embed/) to the layout every page uses. Reviewers comment on your own domain, behind a login too. Pro and Team.
- Without the site's code, it makes a [proxy link](/share/proxy/): nothing to install, public pages only.

It ends with the link to send reviewers. An embed link works once the change with the script is deployed.

## Ask for the work [#ask-for-the-work]

Name the feedback session the way it's labeled in the dashboard:

- "Fix the open Annoty comments on Homepage v2."
- "Which Annoty feedback sessions have open comments?"
- "Go through the comments on /pricing in Homepage v2 and fix the copy ones; leave the design ones open."
- "Open an Annoty feedback session for https://preview.example.com with a proxy link, and give me the link."

The agent replies to each comment with what it changed. It resolves a comment once the fix is live where the reviewer looks, so a fix still waiting for a deploy stays open. Tell it if you want something else, like "resolve them all" or "don't reply".

## Tools [#tools]

| Tool                      | What it does                                                                                | Permission needed         |
| ------------------------- | ------------------------------------------------------------------------------------------- | ------------------------- |
| `list_projects`           | Lists your projects                                                                         | Projects: View            |
| `create_project`          | Adds a site as a project and returns its embed script                                       | Projects: Create          |
| `list_feedback_sessions`  | Lists feedback sessions, for example the ones with open comments                            | Feedback sessions: View   |
| `list_comments`           | Lists a feedback session's comments, open ones by default                                   | Comments: View            |
| `get_comment`             | Reads one comment with its replies and its screenshot                                       | Comments: View            |
| `reply_to_comment`        | Replies in the comment's thread                                                             | Comments: Reply           |
| `update_comment_status`   | Resolves or reopens a comment                                                               | Comments: Resolve         |
| `create_feedback_session` | Opens a feedback session and returns its links: the embed link, and a proxy link when asked | Feedback sessions: Create |

## Permissions, rate limits and revoking access [#permissions-rate-limits-and-revoking-access]

- Replies and resolves show up on the reviewer's page right away.
- The agent can do only what you allowed. Connected with **Read**, or with a key that has only **View** under **Comments**, it reads and never answers.
- Requests count toward your API rate limit: 300 a minute, 100 during the trial.
- To cut an agent off, click **Revoke** beside it under **Account → Connected apps**, or revoke its key under **Settings → API keys**.
- A connected agent stops working when you leave the organization or your role there can no longer connect apps.
