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.

Connect new clients to the code server. The tools server keeps working for clients already connected to it. Both act as the agent you approve; the tools server supports a smaller set of commands.

• Code server: https://comment.io/mcp. One tool, run, that takes any command or a short script, as over SSH. Use it in chat apps and coding agents.
• Tools server: https://comment.io/mcp/tools. One tool for each command, such as doc_read or doc_append, with reads marked read-only. It serves clients already connected to it.

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 the URL https://comment.io/mcp. No API key or client ID is needed. In Claude Code, run claude mcp add --transport http commentio https://comment.io/mcp, 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 run help; its answer starts with “You are AGENT in workspace WORKSPACE.”

Authentication

Your client signs in with OAuth. Only a signed-in member of the workspace can approve it, on Comment.io’s own page; signing in alone approves nothing. Client developers find each server’s sign-in details at https://comment.io/.well-known/oauth-protected-resource/mcp and https://comment.io/.well-known/oauth-protected-resource/mcp/tools.

Each connection acts as one agent in one workspace, on one server; to use the other server, connect and approve again. A Microsoft Copilot connection to the code server also works at the tools server. If you connected Meta Muse to the tools server, connect and approve it again to use the code server.

A connection lasts until you end it: disconnect the agent in Settings, under Agents, and the client’s next call fails. It 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.

• Read, marked read-only: search (the documents most relevant to a query, best first), rg (exact text and regular expressions, or list every document), doc_read, doc_changes (a document’s unseen change sessions, newest first), doc_comments, doc_presence (who has a document open), thing_types, thing_get, people_list, name, teams (the agent’s level in each team and personal space: edit, comment or view), notify_list, thing_query (finds and summarizes items without changing them), skill_list, skill_view, skill_search (the workspace’s skills and the built-in ones), import_status and unzip_status.
• Add, marked not destructive: doc_create, doc_append, doc_insert, doc_comment, doc_reply, doc_comment_reopen, doc_suggest, doc_caught_up (marks a revision seen, only for you), notify_send, notify_wait, import_from_url (a file from a link), report_problem, report_problem_for_review.
• 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_upload, avatar_complete, avatar_remove, notify_complete, unzip.

Tools reach only the Comment.io workspace you approved, and can import files from links you give the agent. 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, search (ranked), rg (exact text), ls, doc-comments, people list, teams (the agent’s level in each team and personal space), 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.
• Lists and items: definition-set creates or changes a list, thing-set creates or changes an item, and thing-get and thing-types read them back. An item that doesn’t fit its list is left unchanged, and the problems are listed.
• 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 in Comment.io, not on your computer. They reach only the Comment.io workspace you approved, and can import files from links you give the agent. 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 and search, exit code 1 with nothing on stderr means no matches.
• After error: deadline (exit code 3), the call’s change may already have happened or may still happen, so the agent rereads the document instead of repeating the change. notify_wait ends with error: timeout when no notification arrives.
• Arguments that don’t fit a tool’s schema, or a tool the server doesn’t have, are refused before anything runs.

Limitations

• On the code server, watch reports only changes seen during one call.
• Images and other files can’t be uploaded from your computer over MCP. Import them from a link, add them in the browser, or copy them over SSH with scp.
• A client acts as one agent in one workspace. To use another workspace, connect again.

Data and privacy

The content your agent reads goes to your MCP client and its provider, under their terms. Each change in Comment.io shows which agent made it. See the privacy policy and terms of service.

Support

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