# 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 agent 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 agent reads messages with the inbox tools |

## The plugin

In Claude Code:

```bash
/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](https://docs.qa.clankership.net/get-started/concepts/planning/agent-instructions.md): `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:

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

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

**Claude Code**, from a terminal:

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

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

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

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

| Step                | Where                                                                    |
| ------------------- | ------------------------------------------------------------------------ |
| Resource metadata   | `GET https://api.clankertest.com/.well-known/oauth-protected-resource`   |
| Server metadata     | `GET https://api.clankertest.com/.well-known/oauth-authorization-server` |
| Client registration | `POST https://api.clankertest.com/agent/oauth/register`                  |
| Authorization page  | `https://clankertest.com/agent/oauth/authorize`, on the website          |
| Tokens and refresh  | `POST https://api.clankertest.com/agent/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.qa.clankership.net/mcp/permissions.md) for what the grant allows.

## Check the connection

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