An AI agent reaches your server through the Model Context Protocol, MCP: a
standard way for an agent’s client to call tools a server offers. In
Commentware an agent is a user like any other. It reads the threads you read,
replies in them under its own name, resolves them, and is mentioned with @
like anybody else — and every tool it calls is the same call the extension
makes.
The endpoint
The server speaks MCP over streamable HTTP, on the same port as its API and
behind the same gate. commentware start serves both. There is no second
process and no command that starts one — commentware mcp starts nothing, and
its entire output is instructions.
Which comments the agent sees
An agent works inside one project, and it chooses its own — separately from whatever your browser is in.
What the agent gets
The tools are listed with their arguments on MCP tools, prompts and resources, as the newest release ships them. An MCP client asks the server for them on connect, so the list your agent sees matches your server’s version, which may be older than the one listed there.
What is worth knowing is the shape of it:
- Reading — who you are, who else is here, the sites and pages on the server, the threads on a page, one thread in full, a thread’s screenshot, and a search across any of it.
- Writing — start a thread, reply, edit a comment, move a thread, change a page’s URL, resolve.
- Reading position — mark a thread read, or mark it unread from a point.
- Notifications — list what is waiting for this key, wait for something to arrive, acknowledge what it merely collected, and mark read what it actually handled.
- Projects — list, create, rename, choose the active one, edit the addresses one claims, move a site.
- Attachments — upload a file it holds and attach it to a comment, and read one back.
- Deleting — a comment or a thread, and only for a key holding
can_admin. - Documents, experimentally — open a Markdown document for comment, read it back, revise it at the same link, and end the review. See open a document for comment.
- Exporting and importing, experimentally — export a page’s, a site’s or a project’s threads to a file, through a link that downloads it once, and import a file’s threads through a link that takes one upload. See export threads through an agent and import threads through an agent.
The server also carries skills an agent can read — through
read_skill, for a client that does not read MCP resources — how to answer somebody in
a thread, how to triage what is waiting, how to place a comment — and four
prompts: one that answers a single thread, one that works through
everything addressed to this key and leaves the list clean, one that does
that and then keeps waiting for replies and answering them until you stop it,
and one that opens a document for comment.
The arguments each prompt takes are on
MCP tools, prompts and resources, under
answer_thread,
catch_up,
discuss and
open_in_planner, which is experimental.
The three skills are answering, triage and placing, in the order above,
and the address each is served at is under
answering,
triage and
placing on the same page.
How an agent signs in
Point the client at the endpoint carrying no credential at all. The server is also an OAuth authorization server, so the client registers itself and opens a page on your server, which asks for the access key once and then remembers that agent. The key is typed into a page on your own machine, and never reaches a config file, a shell history or the agent’s environment. Paste the whole connection string if that is what you have to hand; the page takes either, and reads the key out of the string itself. The token the client gets back works only on the MCP endpoint.
On a server only its own machine can reach, every client but VS Code can
skip the sign-in.
commentware mcp connect gives the client a user of its own and writes that
user’s key into the client’s config file. A key in a file is a credential to
the server wherever the file goes, and some of these files sync; a loopback
server’s key opens nothing beyond its own machine, so the trade is made there
and nowhere else. Connect the clients on the server’s
machine has the steps.
It exists where the server’s own address is loopback or HTTPS. A server
started with --host 0.0.0.0 and no HTTPS public address, or reached at a
plain http:// one, has no sign-in at all, because a token crossing a real interface in clear text
is a credential anybody on the path can read. commentware mcp says which your
server is. To get sign-in, bind loopback and reach the server over an SSH
forward, or put HTTPS in front of it and set its public
address. Forward to the same port number the server
listens on — ssh -L 7042:127.0.0.1:7042 for one on 7042 — because a sign-in
names the server’s own port, and a client reaching it on another one is refused.
On a server bound to 127.0.0.1, localhost works in place of the address
commentware mcp prints, because some clients check the address against what
the server says its own address is, and the server answers to both.
Comments an agent writes
A comment is read on the page it is pinned to, in a card beside the thing it is about, by somebody looking at that thing. The server’s own guidance to agents says the rest, and an agent that reads it writes shorter comments that lead with the answer.
One thing to tell an agent yourself: a name typed into a body mentions
nobody. An agent has to look the person up first — a comment reading @alex
that Alex never hears about is the one failure here with no error attached to
it. See Mention somebody.
What an agent cannot do
Everything that needs a browser is deliberately absent, and the rule is the same every time: a tool an agent could call and could not answer honestly is worse than no tool.
- It cannot report drift, because drift is what a client measured against a live page.
- It cannot upload a screenshot or a drawing, because those are pictures of a page it does not have. A file it does hold — a report, a log, an image it made — it can upload and attach to a comment.
- It cannot set a clip, because that is somebody dragging a box around the part of a screenshot that matters.
- A pin it places is coarser than one you placed by clicking, because it placed the comment against a URL rather than against an element.
Next steps
- Work with an AI agent: mint its key, add the server to your client, and sign in.
- MCP tools, prompts and resources: look up the arguments a tool or a prompt takes.