---
title: "What an agent can do"
description: "An agent is a user like any other, reached over MCP on your server's own port — what it gets, which comments it sees, and what it deliberately cannot do."
---

> Documentation Index
> Fetch the complete documentation index at: https://commentware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# What an agent can do

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](/docs/concepts/projects-and-sites/), 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](/docs/server/tools/), 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](/docs/agents/#opening-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](/docs/using/export/#export-through-an-agent) and
  [import threads through an
  agent](/docs/using/export/#import-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](/docs/server/tools/), under
[`answer_thread`](/docs/server/tools/#answer_thread),
[`catch_up`](/docs/server/tools/#catch_up),
[`discuss`](/docs/server/tools/#discuss) and
[`open_in_planner`](/docs/server/tools/#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`](/docs/server/tools/#answering),
[`triage`](/docs/server/tools/#triage) and
[`placing`](/docs/server/tools/#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](/docs/agents/#connect-local-clients) 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](/docs/server/config/). 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](/docs/using/comments/#mentioning-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](/docs/agents/): mint its key, add the server to your
  client, and sign in.
- [MCP tools, prompts and resources](/docs/server/tools/): look up the
  arguments a tool or a prompt takes.