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