# Connect your clanker

Install the Clanker Ship plugin, sign your clanker in, and make its first tool call.

The Clanker Ship plugin connects Claude Code, Codex or Cursor to the Clanker Ship MCP server. Your
clanker can then read and change tickets, write plans from your team's instructions, receive the
tickets people send it, and follow your team's instructions when it writes tests. It acts as you, with
the access you grant it.

## What the plugin adds

| Part   | What it does                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------ |
| MCP    | Connects to `https://api.clankertest.com/mcp`, which serves every [MCP tool](https://docs.qa.clankership.net/mcp.md)                           |
| Skills | `create-ticket`, `write-plan`, `test-case-writing`, `test-code-generation`, and `setup` for first-time setup |
| Hooks  | Report each session's repository and branch, and hand the clanker its new messages as they arrive            |
| CLI    | Installs the standalone `clanker` CLI, about 320 MB with its own Node, Playwright and Chrome, on first use   |

The first session without the CLI starts its install in the background and says so; `clanker`
commands wait until it finishes. It installs into `~/.local/bin` and `~/.local/share/clanker`
(Windows: `%LOCALAPPDATA%\Clanker`), changes no shell profile, and updates itself in the background.

## Install the plugin

In Claude Code, add the marketplace and install the plugin:

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

In Codex, add the same repository as a marketplace from a terminal and install the plugin:

```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.
Until then, or for any other MCP client such as VS Code, connect with the server URL; see
[Connect a client](https://docs.qa.clankership.net/mcp/connect.md).

## Sign in

Restart the client after installing. In Claude Code, type `/mcp`, choose
`plugin:clanker-ship:clanker-ship` and choose **Authenticate**; Claude Code lists no Clanker
Ship tools until you do. In other clients, the first time the clanker calls a Clanker Ship tool, the
client opens Clanker Ship's sign-in page in your browser:

1. Sign in to the website if you are not signed in already.
2. The **Authorize** page names the client, such as Claude Code, and lists what it can do.
3. Choose the workspace, such as Acme, and choose **Authorize**.

The client finishes the sign-in on its own. Your clanker then appears under **Settings › Your
clankers**, and across the website as the client and your name, such as Claude Code · Maya Patel.

## What you grant

The grant names one workspace and one or both scopes:

| Scope   | Lets the clanker                                                 |
| ------- | ---------------------------------------------------------------- |
| `read`  | Call the list, get and show tools, and read clanker instructions |
| `write` | Call the tools that create, change, archive and remove things    |

The clanker acts as you. Your current role in the workspace caps what it can do, and a viewer can
grant only `read`, so the page lists only the workspaces where your role allows every scope the
client asks for. If your role changes, the clanker's access changes with it on its next request.
Revoke the clanker under **Settings › Your clankers** at any time; every one of its sign-ins ends at
once. See [Permissions](https://docs.qa.clankership.net/mcp/permissions.md) for the details.

## Make the first call

Ask your clanker something that needs Clanker Ship:

```markdown
What's on my plate in Clanker Ship?
```

The clanker calls [show_work](https://docs.qa.clankership.net/mcp/tools/show_work.md), which lists the open tickets you own or your clankers work on,
grouped by status. Clients that draw [MCP Apps](https://docs.qa.clankership.net/mcp/apps.md), such as Codex desktop and Cursor, show
it as a screen where you can open a ticket or ask the clanker to start one. A terminal gets the same
list as text, with a link to each ticket on the website.

Other first requests to try:

- "File a ticket for the bug we just found." The `create-ticket` skill reads your team's
  [clanker instructions](https://docs.qa.clankership.net/get-started/concepts/planning/clanker-instructions.md) and calls
  [create_ticket](https://docs.qa.clankership.net/mcp/tools/create_ticket.md).
- "Write the plan for WEB-31." The `write-plan` skill follows your team's plan instructions and
  saves the plan with [update_ticket](https://docs.qa.clankership.net/mcp/tools/update_ticket.md).
- "Set up Clanker Ship." The `setup` skill checks the sign-in, shows your work and offers your
  settings, such as the default team for new tickets.

## Receive tickets from your team

People send tickets to your clanker with an ask, such as Write the plan, or mention it in a ticket
comment. The clanker can always read them with [list_messages](https://docs.qa.clankership.net/mcp/tools/list_messages.md). For the
plugin's hooks to deliver them as they arrive, sign the CLI in and link each repository the clanker
works in:

```bash
clanker auth login
clanker link acme
```

The hooks then register this computer as your clanker's and report each session's repository and
branch. They add new messages to the clanker's context at session start and on each prompt (in
Cursor, at session start and stop), and the stop hook keeps a turn going while new messages wait.
In Claude Code, start a session with the plugin's channel so a message also reaches an idle
session:

```bash
claude --channels plugin:clanker-ship@clankership
```

> [!NOTE]
> The Claude Code channel is a research preview. In Codex, the plugin hands each new message to its
> thread unless you turn off **Wake idle threads for new messages**; see
> [Codex extensions](https://docs.qa.clankership.net/mcp/codex.md).

See [Clankers and messages](https://docs.qa.clankership.net/get-started/concepts/clankers-and-messages.md) for how messages are routed.