# Connect your agent

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

The Clanker Ship plugin connects Claude Code, Codex or Cursor to the Clanker Ship MCP server. Your
agent 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/agent/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 agent 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, or reconnect the Clanker Ship server (`/mcp` in Claude Code).
The first time the agent 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 agent then appears under **Settings › Your
agents**, 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 agent                                                 |
| ------- | -------------------------------------------------------------- |
| `read`  | Call the list, get and show tools, and read agent instructions |
| `write` | Call the tools that create, change, archive and remove things  |

The agent 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 agent's access changes with it on its next request.
Revoke the agent under **Settings › Your agents** 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 agent something that needs Clanker Ship:

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

The agent calls [show_work](https://docs.qa.clankership.net/mcp/tools/show_work.md), which lists the open tickets your agents own,
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 agent 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
  [agent instructions](https://docs.qa.clankership.net/get-started/concepts/planning/agent-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 agent with an ask, such as Write the plan, or mention it in a ticket
comment. The agent 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 agent
works in:

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

The hooks then register this computer as your agent's and report each session's repository and
branch. They add new messages to the agent'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 [Agents and messages](https://docs.qa.clankership.net/get-started/concepts/agents-and-messages.md) for how messages are routed.