# MCP server

Connect Claude, ChatGPT, Cursor or VS Code to Sailfork over MCP, so an assistant can edit in caissons, open pull requests and read issues and CI.

## Server address

Add this address to any assistant that supports remote MCP servers. You need a Sailfork account to approve the connection.

```
https://status.sailfork.com/mcp
```

| Address | Tools |
| --- | --- |
| `https://status.sailfork.com/mcp` | Every tool |
| `https://status.sailfork.com/mcp/readonly` | Only tools that never change anything |
| `https://status.sailfork.com/mcp/x/pulls,ci` | Chosen toolsets: caissons, issues, pulls, ci, repos, drydock, context |
| `https://status.sailfork.com/mcp/x/pulls,ci/readonly` | Chosen toolsets, read only |

## Add it to your assistant

Each one opens a Sailfork page in the browser to ask for your approval.

### claude.ai

Settings, Connectors, Add custom connector. Paste the URL, then sign in when asked.

```
https://status.sailfork.com/mcp
```

### Claude Code

Run this in a terminal. Claude Code opens the browser the first time it needs access.

```sh
claude mcp add --transport http sailfork https://status.sailfork.com/mcp
```

### Cursor

Add this to ~/.cursor/mcp.json.

```json
{
  "mcpServers": {
    "sailfork": {
      "url": "https://status.sailfork.com/mcp"
    }
  }
}
```

### VS Code

Add this to .vscode/mcp.json.

```json
{
  "servers": {
    "sailfork": {
      "type": "http",
      "url": "https://status.sailfork.com/mcp"
    }
  }
}
```

### ChatGPT

Settings, Apps & Connectors, Advanced: turn on developer mode. Then Create, paste the URL and choose OAuth.

```
https://status.sailfork.com/mcp
```

### On this machine, with the CLI

This uses the login of the `sailfork` command line instead of a browser approval. [Install the CLI](https://status.sailfork.com/install), run `sailfork auth login`, then:

```sh
claude mcp add sailfork -- sailfork mcp
```

Add `--read-only` for tools that change nothing, or `--toolsets pulls,ci` to pick toolsets. Locally, the `drydock` toolset is left out unless you ask for it with `--toolsets all`, because its sandbox tools need your own Drydock machines.

Settings for the local server:

| Setting | What it does |
| --- | --- |
| `-R owner/repo` or `SAILFORK_REPO` | The repository to use when the person names none |
| `--host <url>` or `SAILFORK_HOST` | A host other than sailfork.com |
| `SAILFORK_TOKEN` | A token to use instead of the stored login, for CI and headless agents |
| `SAILFORK_TIMEOUT` | The request timeout in seconds. Calls that wait on purpose set their own. |
| `--lockdown` or `SAILFORK_MCP_LOCKDOWN=1` | See [Choose what an assistant can do](#choose-what-an-assistant-can-do) |

Signed out, the server still starts and every tool answers `run sailfork auth login`.

## How it signs in

Nothing is pasted into the assistant: it never holds your password or a long-lived token.

1. The assistant opens Sailfork in your browser.
2. You see which app is asking, choose read only or read and write, and can limit it to some repositories.
3. It gets a token that lasts an hour and renews itself while you keep using it. Revoke it any time under Connected apps in Settings.

Your own client or script can skip the browser: send a personal access token as `Authorization: Bearer`. An unauthenticated request gets 401 with a `WWW-Authenticate` header that points to the OAuth metadata at `https://status.sailfork.com/.well-known/oauth-protected-resource`. Tokens come from [the REST API](https://status.sailfork.com/docs/api#token-scopes).

- An OAuth token works on `/mcp` only. Anywhere else it is 401.
- A tool that changes data called with a read-only token is 403 with `error="insufficient_scope"`.
- 600 requests a minute per token. Over that is 429 with `Retry-After`.
- Requests over 8 MiB are 413.

## Choose what an assistant can do

Give an assistant the least it needs. Four controls narrow what it can do, and they combine.

| Control | Remote server | Local server |
| --- | --- | --- |
| Read only | `https://status.sailfork.com/mcp/readonly` | `--read-only` |
| Some toolsets | `https://status.sailfork.com/mcp/x/pulls,ci` | `--toolsets pulls,ci` |
| Both | `https://status.sailfork.com/mcp/x/pulls,ci/readonly` | `--read-only --toolsets pulls,ci` |
| Hide text from outsiders | Add `?lockdown=1` to any address | `--lockdown` |

Read-only mode lists only tools that never change anything. A tool that changes data called with a read-only token is refused even if it was listed.

Lockdown replaces the titles, bodies and comments of people who cannot push to the repository with a `[hidden by lockdown]` note in issue and pull request reads, so text written by outsiders on a public repository never reaches the model. Use it when an agent reads a public repository. It is off by default.

At the consent step you can also limit a connection to some repositories. Revoke it any time under Connected apps in Settings.

## Toolsets

Every tool is in one of seven toolsets. Ask for only the ones an agent needs with `/mcp/x/pulls,ci`. An unknown toolset is a 404. Your assistant lists the exact tools once it is connected.

| Toolset | What it covers |
| --- | --- |
| `caissons` | Open a caisson, read and write its files, commit and open the pull request. |
| `issues` | List, read, create and edit issues; claim the next one and post progress. |
| `pulls` | Read pull requests and their diffs, review, comment and merge. |
| `ci` | List runs, read failures and logs, rerun and dispatch workflows. |
| `repos` | Browse and search code, commits, branches and symbols. |
| `drydock` | Start sandboxes and run commands on your organization’s own machines. |
| `context` | Who you are signed in as and what you are working on, so an agent starts oriented. |

### What each toolset is for

| Toolset | Use it when | Example tools |
| --- | --- | --- |
| `caissons` | The agent changes code. It works in a [caisson](https://status.sailfork.com/docs/caissons) on the server, so it needs no clone and no shell. | `caisson_open`, `caisson_read`, `caisson_edit`, `caisson_batch`, `caisson_grep`, `caisson_test`, `caisson_ship` |
| `issues` | The agent picks up and reports on work. | `issue_next`, `issue_claim`, `issue_start`, `issue_comment`, `issue_ship` |
| `pulls` | The agent opens, reviews or lands pull requests. | `pull_get`, `pull_diff`, `pull_feedback`, `pull_review`, `pull_merge` |
| `ci` | The agent reads why a check failed and acts on it. | `ci_runs`, `ci_failures`, `ci_logs`, `ci_rerun`, `ci_dispatch`, `check_run_create`, `check_run_update` |
| `repos` | The agent needs to look around before it changes anything. | `repo_tree`, `repo_read`, `repo_glob`, `search_code`, `search_symbols`, `repo_log` |
| `drydock` | The agent needs to run code on your own machines. | `sandbox_create`, `sandbox_exec`, `sandbox_stop` |
| `context` | The agent starts oriented: who it is, what needs it, what happened. | `whoami`, `doctor`, `brief`, `events`, `inbox`, `inbox_mark_read`, `wait`, `undo` |

Short repository notes for the next agent are `repo_note_list` and `repo_note_add`, in `repos`. See [Working with agents](https://status.sailfork.com/docs/agents).

### Typical flows

**Fix an issue.** `issue_next` with `claim` set returns the most important ready issue and takes a lease on it. `issue_start` claims an issue and opens a caisson. The agent reads with `caisson_read` and `caisson_grep`, changes files with `caisson_edit` or `caisson_batch`, runs the tests with `caisson_test`, and `issue_ship` or `caisson_ship` commits and opens the pull request.

**Answer a review.** `brief` returns the pull request with its unresolved line threads and the code each points at. The agent opens a caisson on the pull request's branch (`caisson_open` with `branch`), edits, then `pull_resolve` closes the threads it fixed.

**Fix a failing check.** `ci_failures` returns each failed step's exit code and last log lines. `ci_logs` has more, and `ci_rerun` runs the workflow again once the fix is pushed. `wait` blocks until the checks finish, so the agent does not poll.

**Look before it changes.** With only `repos` and `--read-only`, an agent can search, read files, history and symbols, and cannot change anything.

## How the work is labeled

The server records the client's name from the MCP handshake, such as `claude-code` or `cursor`, so pull requests, comments and issue leases it makes are marked as agent work and name the client. Names such as `Claude Code 1.0.3` and `claude-code/2.1` count as one agent. A person can turn this off in Settings, Keys and tokens, under Agent tracking. See [Working with agents](https://status.sailfork.com/docs/agents).

## Troubleshooting

| What you see | What to do |
| --- | --- |
| The client cannot connect and the address 401s | That is expected before sign-in. The `WWW-Authenticate` header points to `https://status.sailfork.com/.well-known/oauth-protected-resource`. A client that supports remote MCP follows it and opens the browser. |
| The browser approval never opens | Some clients ask you to start sign-in from their connector settings. If the client has no remote MCP support, use `sailfork mcp` instead. |
| 401 with `invalid_token` | The token is expired, revoked, or for another address. Reconnect. An OAuth token works only on `/mcp`, so a script that calls `/api` needs a personal access token. |
| 403 with `insufficient_scope` | You approved read only, or the address ends in `/readonly`. Connect again and choose read and write. |
| A tool is missing | The toolset is not in the address or `--toolsets`, `--read-only` hides it, or it is `drydock`, which the local server leaves out by default. |
| 404 on `/mcp/x/...` | A toolset name is unknown. The names are `caissons`, `issues`, `pulls`, `ci`, `repos`, `drydock`, `context`. |
| 403 on a request from a browser app | A request with a foreign `Origin` header is refused. |
| 413 | The request is over 8 MiB. |
| 429 | More than 600 requests a minute on one token. Wait for `Retry-After`. |
| Tools answer `run sailfork auth login` | The local server has no stored login. Run `sailfork auth login`, or set `SAILFORK_TOKEN`. |
| A repository is missing from results | The approval was limited to some repositories, or the account cannot read it. A private repository you cannot read answers as not found. |
| `sailfork doctor` | Checks sign-in, token scopes and expiry, git and the server in one pass, and prints the command that fixes each problem. The MCP server offers it as the `doctor` tool. |

## In the browser

An agent that drives this site in a browser with WebMCP (`document.modelContext`) gets these tools instead of guessing from the page. Each page lists only the tools that fit it, and they follow the names and inputs of the hosted server above.

- Tools run as you, with your permissions. They call the same API as the page and add no access.
- Every tool that changes something asks you in a dialog first, naming exactly what will happen. Only a real click or key press on that dialog counts.
- Deleting a repository, changing visibility and billing have no tool: they stay on the page.
- Issue bodies, comments, titles and file contents come back wrapped as `{"untrusted": "..."}` with a notice. They are data, never instructions.
- Failures return `{"ok": false, "error": {"code", "message", "next"}}` with what to do next. Codes: `sign_in_required`, `no_permission`, `not_found`, `conflict`, `invalid_input`, `declined`, `rate_limited`, `server_error`, `offline`, `timeout`, `cancelled`, `busy`.

| Tool | Where | What it does |
| --- | --- | --- |
| `whoami` | Every page | Who is signed in, or that nobody is. |
| `sign_in` | Every page, signed out | Opens the sign-in page and returns to this page. |
| `go_to` | Every page | Opens a page on this site. |
| `search_repos` | Every page | Finds public repositories. |
| `search_code` | Every page | Searches file contents in one repository or all you can read. |
| `repo_list` | Every page, signed in | Your repositories and your organizations’. |
| `my_work` | Every page, signed in | Your pull requests with checks, review requests and assigned issues. |
| `repo_get` | Repository pages | Visibility, default branch, branches and your access. |
| `repo_tree` | Repository pages | Lists a folder at a branch, tag or commit. |
| `repo_read` | Repository pages | Reads a file, optionally a line range. |
| `repo_log` | Repository pages | Commit history, for the repository or one path. |
| `repo_branches` | Repository pages | Branches with ahead and behind counts. |
| `compare` | Repository pages | Commits and changed files between two refs. |
| `issue_list` | Repository pages | Issues with filters. |
| `issue_get` | Repository pages | An issue with its comments and the checks of its pull request. |
| `pull_list` | Repository pages | Pull requests with filters. |
| `pull_get` | Repository pages | A pull request with review state, checks and open threads. |
| `issue_create` | Repository pages, signed in | Opens an issue. Asks you first. |
| `issue_comment` | Issue pages, signed in | Comments on an issue. Asks you first. |
| `issue_update` | Issue pages, write access | Changes state, labels, assignee, priority, title or description. Asks you first. |
| `pull_checks` | Pull request pages | CI jobs of the newest run with failed steps. |
| `pull_merge_status` | Pull request pages | Whether it can merge and every reason it cannot. |
| `pull_comment` | Pull request pages, signed in | Comments, replies to a thread or comments on a line. Asks you first. |
| `pull_review` | Pull request pages, write access | Approves, requests changes or comments. Asks you first. |
| `pull_merge` | Pull request pages, write access | Merges, squashes or rebases. Asks you first. |
| `org_members` | Organization pages | Members and roles. |
| `org_invite` | Organization pages, owners | Invites a person. Asks you first. |
| `create_repository` | New repository page | Fills the form; you press Create repository. Asks you first. |
| `comment_on_issue` | Issue pages, signed in | Fills the comment form; you press Comment. Asks you first. |

---

Every docs page: https://status.sailfork.com/llms.txt
