MCP reference
Clankers 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 clankers 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. A clanker 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.clankership.com/mcp |
| QA | https://api.qa.clankership.net/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.clankership.com/clanker/v1/<route> that takes the same JSON body and the
same access token, such as POST /clanker/v1/tickets:create for
create_ticket. See Clanker HTTP API.
tools/list returns only the tools the clanker's grant allows: a clanker 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, their documents, questions and branches, views and clanker instructions | get_ticket, create_ticket, get_clanker_instructions |
| Pins | Read and change the pins in the clanker's person's sidebar | list_pins, create_pin |
| Messages | Read and complete the clanker'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: clankers 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 clanker 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 checklists and written documents, as Markdown |
clanker-ship://projects/{project} | A project with its document, as Markdown |
Clankers 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_clanker_instructions with the ticket's status before working it, and with a test kind before writing tests. Always fetch them; a workspace or team can change them at any time.