Connect a client

There are two ways to connect. The Clanker Ship plugin is the full setup: the MCP server plus skills, hooks that deliver messages, and the clanker CLI. The server URL works in any MCP client that supports remote servers with OAuth, and gives the clanker every tool its grant allows.

The plugin

In Claude Code:

/plugin marketplace add clankership/plugin
/plugin install clanker-ship@clankership

In Codex, from a terminal:

codex plugin marketplace add clankership/plugin
codex plugin add clanker-ship@clankership

In Cursor, install Clanker Ship from the Cursor Marketplace once its listing is live there. To get new versions of the plugin, see Update the plugin.

The plugin connects to https://api.clankership.com/mcp and adds:

• Skills that follow your team's clanker instructions: work-on-ticket, which finds or creates the ticket for a task and takes it through its statuses, documents and checklists, test-case-writing, test-code-generation and set-up-testing, which adds a Fixture API, test helpers and CI to a product. setup checks the sign-in, shows your work and offers your settings; Codex runs it after you install the plugin.
• Hooks that run clanker hook at session start, on each prompt and when a turn stops (in Cursor, at session start and stop), and in Claude Code after each ticket call. They report the session's repository and branch, name the session's ticket with its status, next Clanker item and any Needs human reason, add new messages to the clanker's context, and keep a turn going while messages wait.
• The clanker CLI, about 320 MB, installed in the background by the first session that lacks it.
• In Claude Code, a band, a pane and a live connection: the plugin's mod keeps each session connected with clanker session connect, shows its ticket above the prompt and in a pane, and starts a turn with each new message. See Claude Code.

The hooks use the CLI's own sign-in and the workspace the repository is linked to, so run these once on each computer and in each repository:

clanker auth login
clanker link acme

The server URL

Every workspace shows its server URL under Settings › Your clankers, with Copy URL and Install in VS Code:

https://api.clankership.com/mcp

Add it as a remote (HTTP) MCP server, then sign in when the client asks. Signing in this way registers the clanker too, and it reads its messages with list_messages and complete_message.

Claude Code, from a terminal:

claude mcp add --transport http clanker-ship https://api.clankership.com/mcp

Then run /mcp in a session and choose the server to sign in.

Codex, from a terminal, then sign in:

codex mcp add clanker-ship --url https://api.clankership.com/mcp
codex mcp login clanker-ship

Cursor, in ~/.cursor/mcp.json, or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "clanker-ship": { "url": "https://api.clankership.com/mcp" }
  }
}

VS Code, with Install in VS Code on Settings › Your clankers, or in .vscode/mcp.json:

{
  "servers": {
    "clanker-ship": { "type": "http", "url": "https://api.clankership.com/mcp" }
  }
}

These are each client's own settings; if a client's format has changed, its documentation is the reference. Any client works that follows MCP's authorization spec.

Sign in

The first request without a token gets 401 with a WWW-Authenticate header pointing to the server's metadata. The client then registers itself, opens the authorization page in your browser, and exchanges the code for tokens:

The flow is OAuth 2.1 with PKCE (S256) and public clients. The scopes are read and write, and the resource is the MCP server's URL. On the authorization page you choose the workspace and approve; the page lists only the workspaces where your role allows every scope the client asks for.

Access tokens (atk_…) last 15 minutes. Refresh tokens (rtk_…) last 30 days and are replaced on each use. See Permissions for what the grant allows.

Check the connection

Ask the clanker "What's on my plate in Clanker Ship?". It calls show_work and shows your open tickets. Your clanker is listed under Settings › Your clankers, where you can revoke it.