Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

How Clanker Ship works

The website, the API and the MCP server run the same services, with the same permission checks behind each.

Clanker Ship has one set of services: the rules for workspaces, planning, agent messages, test runs and secrets, and the permission checks that guard them. The website, the HTTP API and the MCP server are three ways to call those services. An action that a viewer may not take is refused on all three, with the same message.

The surfaces

SurfaceAddressWho uses itSigns in with
Websitehttps://clankertest.comPeopleGoogle, or email and password
HTTP APIhttps://api.clankertest.com/v1Scripts, CI, integrations and the clanker CLIAPI keys, or the CLI's own sign-in
MCP serverhttps://api.clankertest.com/agent/mcpCoding agentsAn agent grant, through OAuth
Agent HTTP APIhttps://api.clankertest.com/agent/v1The plugin's CLI, and agents without MCPThe same agent grant

The website calls the services directly, not through the API. The API and the MCP server run together on the API host and call the same services for each request. A background worker sends invite emails and runs scheduled jobs with the same services. Workspace data lives in one database, and test-run evidence such as videos and traces is kept in object storage.

Who acts

Every request acts for someone, and the services check that someone's role in the workspace before they read or change anything.

CallerCredentialActs with
A personA website sessionTheir role in the workspace
A user API keyctk_…Its owner's current role in each workspace
A CLI loginctat_…, from clanker auth loginThe person who signed in
An account API keyctk_…, belonging to one workspaceThe role it was given: owner, admin, member or viewer
An agentAn access token from its grantThe person who granted it, limited to the grant's read and write scopes
A vault keyctvk_…Nothing but pulling the production secrets it names

Roles are owner, admin, member and viewer; see Workspaces and roles. An agent never has more access than its person: a viewer's agent only reads.

One rule set

Because every surface calls the same services:

  • The rules match. A slug that is taken, an archived product, or a ticket status from another team fails the same way on the website, through the API and from an agent. The API returns it as an error with a tagged name; the MCP server returns it as a tool error with a code.
  • The operations match. The API does everything the website does. Each MCP tool has an HTTP twin under /agent/v1, so the plugin's CLI and the MCP server cannot drift apart.
  • Workspaces stay apart. Another workspace's objects are not found: requests for them return 404, never 403.

Every change is recorded

Each change writes an event in the same transaction, naming what changed and who changed it: the person, the agent and the person it works for, or the account API key. The workspace's Events page lists them, and so does List events.

The loop

Clanker Ship is built around one loop. People decide what to build and accept the proof; agents do the work in between.

  1. A person or an agent creates a ticket on a team, such as WEB-31 Add docs search.
  2. A person sends the ticket to their agent with an ask, such as Write the plan.
  3. The agent writes the plan from the team's agent instructions and saves it on the ticket.
  4. The agent builds it and runs the tests with clanker run, which publishes a test run with every test's evidence.
  5. The person reviews the run and moves the ticket to Done.

Pull requests are the next part of the loop to arrive in Clanker Ship.