Skip to Content
annotyDocs

Coding agents (MCP)

Claude Code, Cursor, Codex, Claude or ChatGPT reads the open comments, fixes the code, replies to the reviewer and resolves the thread.

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

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

FieldWhat the agent does with it
Element textSearches your code for it. Usually the fastest way to the right file
Element HTMLMatches its classes and attributes when the text is generated or appears many times
Page addressFinds the route, including the query string
Window sizeTells a phone layout bug from a desktop one
BrowserTells a Safari bug from a Chrome one
ScreenshotSees 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 when the reviewer left it out or their browser couldn't take one.

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.

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

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

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

An agent that runs on its own, like a CI job or a scheduled task, has nobody to sign in. Give it an API key instead:

  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:

    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.

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.

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 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: 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

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

ToolWhat it doesPermission needed
list_projectsLists your projectsProjects: View
create_projectAdds a site as a project and returns its embed scriptProjects: Create
list_feedback_sessionsLists feedback sessions, for example the ones with open commentsFeedback sessions: View
list_commentsLists a feedback session's comments, open ones by defaultComments: View
get_commentReads one comment with its replies and its screenshotComments: View
reply_to_commentReplies in the comment's threadComments: Reply
update_comment_statusResolves or reopens a commentComments: Resolve
create_feedback_sessionOpens a feedback session and returns its links: the embed link, and a proxy link when askedFeedback sessions: Create

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.

On this page