# Connect a client

Connect Claude Code, Codex, Cursor, VS Code or any MCP client to Clanker Ship with the plugin or the server URL.

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.

| Way        | Clients                         | Adds                                                      |
| ---------- | ------------------------------- | --------------------------------------------------------- |
| Plugin     | Claude Code, Codex, Cursor      | MCP, skills, message hooks and the `clanker` CLI          |
| Server URL | Any MCP client, such as VS Code | MCP only; the clanker reads messages with the inbox tools |

## The plugin

In Claude Code:

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

In Codex, from a terminal:

```bash
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](https://docs.clankership.com/get-started/connect-your-clanker.md#update-the-plugin).

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

- **Skills** that follow your team's
  [clanker instructions](https://docs.clankership.com/get-started/concepts/planning/clanker-instructions.md): `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](https://docs.clankership.com/mcp/claude-code.md).

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:

```bash
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**:

```text
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](https://docs.clankership.com/mcp/tools/list_messages.md) and [complete_message](https://docs.clankership.com/mcp/tools/complete_message.md).

**Claude Code**, from a terminal:

```bash
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:

```bash
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:

```json
{
  "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`:

```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:

| Step                | Where                                                                    |
| ------------------- | ------------------------------------------------------------------------ |
| Resource metadata   | `GET https://api.clankership.com/.well-known/oauth-protected-resource`   |
| Server metadata     | `GET https://api.clankership.com/.well-known/oauth-authorization-server` |
| Client registration | `POST https://api.clankership.com/oauth/register`                        |
| Authorization page  | `https://clankership.com/oauth/authorize`, on the website                |
| Tokens and refresh  | `POST https://api.clankership.com/oauth/token`                           |

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](https://docs.clankership.com/mcp/permissions.md) for what the grant allows.

## Check the connection

Ask the clanker "What's on my plate in Clanker Ship?". It calls [show_work](https://docs.clankership.com/mcp/tools/show_work.md)
and shows your open tickets. Your clanker is listed under **Settings › Your clankers**, where you can
revoke it.