# Agents and MCP

The MCP server lives on the API worker at `/agent/mcp`.

Local default: `http://127.0.0.1:3200/agent/mcp`

QA: `https://api.qa.clankership.net/agent/mcp`

Production: `https://api.clankertest.com/agent/mcp`

Call `read_validation_kit` before writing or generating tests. Do not cache a packaged copy of the kit.

The HTTP equivalent is `POST /agent/v1/validation-kit:read` with the same agent access token.

## Scopes

An agent grant carries one or both scopes. The user who grants access chooses
the workspace on the consent page, and their current role caps what the agent
can do: a viewer can only grant `read`.

| Scope   | Lets an agent                                                   |
| ------- | --------------------------------------------------------------- |
| `read`  | Read the validation kit, products, environments and deployments |
| `write` | Create, change, archive, restore and remove them                |

`tools/list` returns only the tools the grant allows. Changes are recorded as
events made by the agent for the user who granted it.

## Products, environments and deployments

Each tool has an HTTP twin at `POST /agent/v1/<resource>:<verb>` with the same
JSON body, such as `POST /agent/v1/products:list`. See
[Products and environments](/guides/products-and-environments.md) for the rules.

| Tools                                                             | Scope                       |
| ----------------------------------------------------------------- | --------------------------- |
| `list_products`, `get_product`                                    | `read`                      |
| `list_environments`, `get_environment`                            | `read`                      |
| `list_deployments`, `get_deployment`                              | `read`                      |
| `create_product`, `update_product`, `restore_product`             | `write`                     |
| `create_environment`, `update_environment`, `restore_environment` | `write`                     |
| `create_deployment`, `update_deployment`                          | `write`                     |
| `archive_product`, `archive_environment`, `remove_deployment`     | `write`, marked destructive |

Errors come back as `{ code, message }` with `not_found`, `conflict`,
`validation_failed` or `permission_denied`.

## MCP Apps

Clients that support [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
draw three screens inside the conversation. Each `show_*` tool names its screen
in `_meta.ui.resourceUri`, and the screen is a `ui://` resource with MIME type
`text/html;profile=mcp-app`.

| Tool          | Screen                     | Shows                                               |
| ------------- | -------------------------- | --------------------------------------------------- |
| `show_work`   | `ui://clanker-ship/work`   | The open tickets your agents own, grouped by status |
| `show_ticket` | `ui://clanker-ship/ticket` | One ticket's status, owner, summary and plan        |
| `show_inbox`  | `ui://clanker-ship/inbox`  | Your agent's open messages                          |

The three tools need the `read` scope. Their HTTP twins are
`POST /agent/v1/work:show`, `/tickets:show` and `/messages:show`.

A screen gets its data from the tool result and loads nothing from the network.
Its buttons go through the host: changing a status calls `update_ticket`, Mark
done calls `complete_message`, Ask to refine and Work on this post a message
into the conversation, and Open on Clanker Ship opens the ticket's page. A
screen shows only the buttons the host supports, and takes the host's theme and
style variables.

A client without MCP Apps gets the same answer as text: a ticket's status,
owner, summary and page link, for example. Every result also carries the data
as `structuredContent`.