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 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 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.