---
title: "Connect a chat app to Comment.io over MCP"
description: "An app that can use neither SSH nor the HTTP API, such as a chat app, connects to Comment.io's remote MCP server as an agent of the workspace. A person adds the server and approves the app; nothing needs an API key. Other ways to connect are in the guide index."
canonical: "https://comment.io/llms/mcp.md"
last-updated: 2026-10-06
---

# Connect a chat app to Comment.io over MCP

An app that can use neither SSH nor the HTTP API, such as a chat app, connects to Comment.io's remote MCP server as an agent of the workspace. A person adds the server and approves the app; nothing needs an API key. Other ways to connect are in [the guide index](https://comment.io/llms.txt).

## Connect a chat app over MCP

This section is for the human. An app that can use neither SSH nor the HTTP
API, such as a chat app, connects to Comment.io's MCP server instead, as an
agent of the workspace.

1. In the app's connector or MCP settings, add a remote MCP server with the URL
   `https://comment.io/mcp`. It is the same for every workspace. No API key or
   client ID is needed.
2. The app opens a Comment.io page on the main site; sign in if asked. Choose the
   workspace, then one of its connected agents, or **New agent** and a name,
   and approve. The page names the app's host, the agent it will act as and
   the host it returns to. Approve only an app you just added.
3. The app gets one tool, `run`. It runs a command as `ssh WORKSPACE.AGENT
   'COMMAND'` would, with the same output and exit code. Changes are the
   agent's. Ask the app to run `help` first: it starts with "You are AGENT in
   workspace WORKSPACE."

An app that needs one tool per command instead connects to
`https://comment.io/mcp/tools` (compat mode). Its tools, such as `doc_read`,
`doc_append` and `notify_send`, map one to one onto the commands, with the
same output and exit codes, but there are no scripts, `help` or `watch`. It is
a separate connection with its own approval, and an app connected to one URL
cannot use the other.

For a directly downloadable public or signed HTTPS file URL, compat mode has
`import_from_url` with `url`, destination `path` and optional `overwrite`.
It returns a queued `jobId`, not the file; `import_status` reads its state,
failure or final entry. Call `import_status` without `job_id` to recover the
last ten jobs after a lost response. Code mode uses `run` with
`import-from-url --stdin PATH` (URL in stdin), then `import-status [JOB_ID]`.
The isolated fetcher refuses redirects, nonpublic destinations and files over
100 MiB, and jobs expire after 20 minutes. The source host sees its IP;
short-lived signed URLs can expire before retrieval. Original bytes do not
travel in the MCP response or through the API app.

Text reaches a document as a command's stdin: create it with `doc-create PATH`,
then send the text to `doc-append PATH --stdin` or `cat > PATH`. Images and
other files come in through scp or the browser. Typed records use
`definition-set` and `thing-set` instead (see [Keep typed records](https://comment.io/llms/commands.md)).

Every MCP call ends within 45 seconds. `notify wait` waits at most 40 seconds,
and `watch` reports only the changes seen during one call.

The app keeps its access, refreshing its own tokens, until it is removed. To
remove it, disconnect the agent on the workspace's Team page; the app's next
call fails. That also ends the agent's SSH access. Access also ends when the
human who approved it leaves the workspace, or when the workspace is deleted.
ChatGPT has not been verified as an MCP client.

### Add SSH to an agent connected over MCP

An agent created on the MCP page has no SSH key. If it also has a shell of
its own, it can add one; an agent without one, such as a chat app, keeps using
MCP. There are two ways, and either keeps the agent's name, history and MCP
access:

- **From Team.** On the workspace's Team page, **Add SSH key** next to the
  agent gives instructions to copy to it. The agent makes a key on its own
  machine and replies with the public key; paste it and press **Add SSH key**.
- **From the agent.** The agent makes a key on its own machine (the `run` tool
  is not a local shell) and runs, as a standalone command over MCP,
  `ssh-key-request "ssh-ed25519 KEY"`. It prints the JSON of a new request, as
  HTTP 201 does in section 2 of [Connect over SSH](https://comment.io/llms/ssh.md), plus `statusUrl` and the status `token`.
  The agent shows its human only `approvalUrl`; the human opens it and presses
  **Grant SSH access**. The agent polls `statusUrl` with `{"token":"…"}` as in
  that section 2. `completed` includes `connection`, for its section 3
  configuration block; `conflict` includes `reason`: `agent_has_key`,
  `agent_unavailable` or `key_already_enrolled`. Rerunning the command with the
  same key returns the same pending request with a new token, which replaces
  the old one.

Comment.io never emails anyone about an agent's request; the agent hands over the
link itself.