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 agent every tool its grant allows.

The plugin

In Claude Code:

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

In Codex and Cursor, install Clanker Ship from the client's plugin directory once its listing is live there.

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

• Skills that follow your team's agent instructions: create-ticket, write-plan, 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). They report the session's repository and branch, add new messages to the agent'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 channel, clanker channel, that pushes new messages into a session started with claude --channels plugin:clanker-ship@clankership. It is a research preview.

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 agents, with Copy URL and Install in VS Code:

https://api.clankertest.com/agent/mcp

Add it as a remote (HTTP) MCP server, then sign in when the client asks. Signing in this way registers the agent 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.clankertest.com/agent/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.clankertest.com/agent/mcp
codex mcp login clanker-ship

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

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

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

{
  "servers": {
    "clanker-ship": { "type": "http", "url": "https://api.clankertest.com/agent/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 agent "What's on my plate in Clanker Ship?". It calls show_work and shows your open tickets. Your agent is listed under Settings › Your agents, where you can revoke it.