Comment.io MCP servers

Bring your agent into the same documents your team uses. Connect a compatible MCP client to read, search, edit, comment, and suggest changes in the workspace you choose. See its work live in the Comment.io editor, under the agent’s name.

Choose the tools server for clients that review individual tools, or the code server for coding agents that compose commands. Both run the same commands, with the same results, as the agent you approve.

• Tools server (compat mode): https://comment.io/mcp/tools. One tool for each command, such as doc_read or doc_append, with reads marked read-only. Use it in chat apps and wherever tools are reviewed one by one.
• Code server (code mode): https://comment.io/mcp. One tool, run, that takes any command or a short script, as over SSH. Use it in coding agents that compose commands.

What you need

• A Comment.io account that is a member of at least one workspace. Join Comment.io if you don’t have one.
• An MCP client that supports remote servers over Streamable HTTP with OAuth.

Set up

1. Add a remote MCP server, or custom connector, with one of the URLs above. No API key or client ID is needed. In Claude Code, run claude mcp add --transport http commentio https://comment.io/mcp/tools, then authenticate it from /mcp.
2. Your client opens a Comment.io page. Sign in to Comment.io if asked.
3. Choose the workspace, then an existing agent or New agent with a name. The page shows the client’s name or address and the address it returns to. Approve only a client you just added.
4. Back in your client, ask it to list your documents. On the code server, ask it to run help; its answer starts with “You are AGENT in workspace WORKSPACE.”

Authentication

Comment.io is its own OAuth 2.1 authorization server, at https://comment.io. Each server is its own protected resource, with metadata at https://comment.io/.well-known/oauth-protected-resource/mcp/tools and https://comment.io/.well-known/oauth-protected-resource/mcp. A request without a token gets 401 with a WWW-Authenticate header that points there.

Any MCP client can connect. Public clients use PKCE, with no client secret, and identify themselves with a Client ID Metadata Document, with dynamic client registration at https://comment.io/oauth/register, or with any other client ID. A client with any other client ID, registered or not, is shown at approval only by the address it returns to; clients Comment.io knows are shown by name. Microsoft Copilot and the configured Meta Muse OAuth client use a client ID and secret that Comment.io issues to them. Microsoft defaults to the tools server; the Meta client defaults to the code server at https://comment.io/mcp, with its single run tool. This server-side OAuth configuration does not establish that Muse's callback or runtime accepts the connection. Approval happens only on Comment.io’s own page, by a signed-in member of the workspace. Signing in does not approve anything.

A Meta Muse connection approved before this change remains bound to the tools server, including after refresh. To use https://comment.io/mcp, connect and approve again; an existing token does not gain access to the code server.

The client receives tokens for one workspace, one agent and one server; a token for one server doesn’t work at the other, so each needs its own approval. Every request is checked against that grant. Access lasts until you end it: disconnect the agent on the workspace’s Team page, and the client’s next call fails. Access also ends when the person who approved it leaves the workspace, or when the workspace is deleted.

Tools server

Each tool runs one Comment.io command as the agent and returns its stdout, stderr and exitCode. Arguments are passed to the command as they are, never through a shell.

• Read, marked read-only: rg (search, or list every document), doc_read, doc_comments, doc_presence (who has a document open), thing_types, thing_get, team_list, name, notify_list, thing_query (a read-only SQL SELECT over Things), skill_list, skill_view and skill_search (the workspace’s skills and the built-in ones).
• Add, marked not destructive: doc_create, doc_append, doc_insert, doc_comment, doc_reply, doc_comment_reopen, doc_suggest, notify_send, notify_wait.
• Change or remove, marked destructive: doc_replace_text, doc_delete_text, doc_rename, doc_remove, doc_comment_resolve, doc_comment_edit, doc_comment_delete, doc_suggestion_edit, doc_suggestion_accept, doc_suggestion_reject, thing_set, definition_set, name_set, avatar_set, avatar_remove, notify_complete.

No tool reaches anything outside the workspace you approved. There is no tool for scripts, help, watch, grep or ssh-key-request.

Code server

The server has one tool, run. It takes a command and optional stdin, runs that Comment.io command in your workspace as the agent, and returns its stdout, stderr and exitCode. The commands are the same as over SSH. The main ones:

• Read: doc-read, rg (search), ls, doc-comments, team list, thing-query.
• Edit: doc-create, doc-append, doc-insert, doc-replace-text, doc-delete-text, doc-rename, doc-remove.
• Discuss: doc-comment, doc-reply, doc-suggest, and resolving, editing or deleting comments and suggestions.
• Typed records (Things): definition-set creates or changes a type, thing-set creates or changes a record, and thing-get and thing-types read them back. Every write to a record is checked against its type and refused, with the problems listed, when it doesn’t fit.
• Skills: skill list lists the instructions people in the workspace wrote for agents in skills/NAME.md, and skill view NAME prints one. help lists them too.
• Coordinate with other agents: notify send, notify wait, notify list, notify complete.

help lists every command and its options. Commands run on Comment.io’s servers in a restricted shell, not on your computer; they can reach only the workspace you approved. Because run can change and delete documents, it is marked as a destructive tool, and clients may ask you to confirm calls.

Results and errors

• Exit code 0 is success, 1 a failure named on stderr (for example error: not_found), 2 invalid input, and 3 a timeout. For rg, exit code 1 with nothing on stderr means no matches.
• Every call ends within 45 seconds. A call that times out ends with error: deadline (exit code 3); its outcome is unknown, so the agent rereads the document instead of repeating the change.
• Arguments that don’t fit a tool’s schema, or a tool the server doesn’t have, are refused as invalid parameters before anything runs.

Limitations

• notify wait waits at most 40 seconds per call. On the code server, watch reports only changes seen during one call.
• Text reaches a document as tool input. Images and other files can’t be uploaded over MCP; add them in the browser, or over SSH with scp.
• Text input is limited to 2,000,000 bytes per call, and comments to 16 KiB.
• A client acts as one agent in one workspace. To use another workspace, connect again.

Data and privacy

The content your agent reads is sent to your MCP client and its provider, under their terms. Comment.io records which agent made each change and keeps counts of agent activity, never document content, for analytics. See the privacy policy and terms of service.

Support

Email support@comment.io. See Support for what to include.

Comment.io · MCP server · Support · Privacy · Terms