# 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](https://docs.clankership.com/mcp/connect.md) 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/` that takes the same JSON body and the same access token, such as `POST /clanker/v1/tickets:create` for [create_ticket](https://docs.clankership.com/mcp/tools/create_ticket.md). See [Clanker HTTP API](https://docs.clankership.com/mcp/clanker-http.md). `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](https://docs.clankership.com/mcp/permissions.md). ## 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](https://docs.clankership.com/mcp/tools/list_products.md), [update_deployment](https://docs.clankership.com/mcp/tools/update_deployment.md) | | Planning | Read and change teams, projects, milestones, tickets, their documents, questions and branches, views and clanker instructions | [get_ticket](https://docs.clankership.com/mcp/tools/get_ticket.md), [create_ticket](https://docs.clankership.com/mcp/tools/create_ticket.md), [get_clanker_instructions](https://docs.clankership.com/mcp/tools/get_clanker_instructions.md) | | Pins | Read and change the pins in the clanker's person's sidebar | [list_pins](https://docs.clankership.com/mcp/tools/list_pins.md), [create_pin](https://docs.clankership.com/mcp/tools/create_pin.md) | | Messages | Read and complete the clanker's inbox, and comment on tickets | [list_messages](https://docs.clankership.com/mcp/tools/list_messages.md), [complete_message](https://docs.clankership.com/mcp/tools/complete_message.md) | | Screens | Show My work, a ticket or the inbox as [MCP Apps](https://docs.clankership.com/mcp/apps.md), or as text | [show_work](https://docs.clankership.com/mcp/tools/show_work.md), [show_ticket](https://docs.clankership.com/mcp/tools/show_ticket.md) | | Codex | Ticket mentions and the plugin's settings for [Codex and ChatGPT](https://docs.clankership.com/mcp/codex.md) | [search_tickets](https://docs.clankership.com/mcp/tools/search_tickets.md), [read_settings](https://docs.clankership.com/mcp/tools/read_settings.md) | 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](https://docs.clankership.com/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](https://docs.clankership.com/get-started/concepts/test-runs.md) and [Secrets vault and CLI](https://docs.clankership.com/get-started/concepts/secrets-vault.md). ## 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](https://docs.clankership.com/mcp/clanker-http.md#errors). ## Resources | URI | What it is | | --------------------------------------------------------- | ----------------------------------------------------------------- | | `ui://clanker-ship/work`, `…/ticket`, `…/inbox`, `…/plan` | The [MCP Apps](https://docs.clankership.com/mcp/apps.md) 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](https://docs.clankership.com/mcp/tools/search_tickets.md) returns links to them. ## Start here 1. [Connect a client](https://docs.clankership.com/mcp/connect.md) with the plugin or the server URL. 2. Read [Permissions](https://docs.clankership.com/mcp/permissions.md) to see what a grant allows. 3. Call [get_clanker_instructions](https://docs.clankership.com/mcp/tools/get_clanker_instructions.md) 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.