MCP reference
Coding agents connect to the Clanker Ship MCP server to read and change the workspace as the person who granted them access.
The Clanker Ship MCP server lets coding agents such as Claude Code, Codex and Cursor work in your workspace: read and change tickets, projects and views, read their inbox, describe products and deployments, and read your team's instructions before they write tickets, plans or tests. An agent signs in with OAuth and acts as the person who granted it access, never with more than that person's role.
The server
| Server | URL |
|---|---|
| Production | https://api.clankertest.com/agent/mcp |
| QA | https://api.qa.clankership.net/agent/mcp |
It speaks MCP's Streamable HTTP transport and answers each request with JSON. Clients discover how
to sign in from /.well-known/oauth-protected-resource on the same host. The
Clanker Ship plugin configures all of this for you; any MCP client that supports
remote servers and OAuth can connect with the URL.
Tools and their HTTP twins
Every tool is one operation, with a JSON input schema and an example. Each tool also has an HTTP
twin at POST https://api.clankertest.com/agent/v1/<route> that takes the same JSON body and the
same access token, such as POST /agent/v1/tickets:create for
create_ticket. See Agent HTTP API.
tools/list returns only the tools the agent's grant allows: an agent with only the read scope
does not see the tools that change things. See Permissions.
How the reference is organized
Tools are grouped by area, in the order tools/list returns them:
| Area | What the tools do | Examples |
|---|---|---|
| Catalog | Read and change products, environments and deployments | list_products, update_deployment |
| Planning | Read and change teams, projects, milestones, tickets, views and agent instructions | get_ticket, create_ticket, get_agent_instructions |
| Messages | Read and complete the agent's inbox, and comment on tickets | list_messages, complete_message |
| Screens | Show My work, a ticket or the inbox as MCP Apps, or as text | show_work, show_ticket |
| Codex | Ticket mentions and the plugin's settings for Codex and ChatGPT | search_tickets, read_settings |
Each tool's page shows its description, the scope it needs, its hints (read-only, destructive, idempotent), its input fields with an example, its HTTP twin, and the screen it opens, if any. Every page has a Markdown twin, and /mcp/tools.json lists every tool with its input schema.
Test runs and secrets have no tools: agents run clanker run and the clanker vault commands in
the CLI, as their person. See Test runs and
Secrets vault and CLI.
Results and errors
A tool's result carries its data as structuredContent, and the same data as JSON text for clients
that read only text. The show_* tools answer with readable text and a link to the website
instead, for clients that do not draw their screens.
A tool that fails returns a result with isError: true and a body such as
{ "code": "not_found", "message": "No ticket WEB-99.", "requestId": "…" }. The codes are the same
as the agent HTTP API's.
Resources
| URI | What it is |
|---|---|
ui://clanker-ship/work, …/ticket, …/inbox, …/plan | The MCP Apps screens, as text/html;profile=mcp-app |
clanker-ship://tickets/{ticket} | A ticket with its summary and plan, as Markdown |
clanker-ship://projects/{project} | A project with its document, as Markdown |
Agents read the ticket and project resources with resources/read after
search_tickets returns links to them.
Start here
- Connect a client with the plugin or the server URL.
- Read Permissions to see what a grant allows.
- Call get_agent_instructions before writing a ticket, a plan or tests. Always fetch them; a workspace or team can change them at any time.