# Workcamp MCP — setup instructions for an AI agent

You are being asked to connect this machine/repo to **Workcamp Manager** over MCP.
Follow these steps literally. Everything you need is on this page; do not guess
config formats from memory — the field names differ per client and a wrong one
fails silently.

Server: `https://mcp.workcamp.app/mcp`
Transport: Streamable HTTP · Auth: OAuth 2.1 + PKCE (dynamic client registration)
Scopes: `manager:read` `manager:write` `manager:comment` — request all three.

---

## Step 1 — Work out the environment

Determine, and state to the user what you found:

1. **OS** — macOS, Linux, or Windows.
2. **Harness** — which AI client you are running inside (Claude Code, Antigravity,
   Codex CLI, Cursor, VS Code, Windsurf, Zed, or something else).
3. **Location** — the repo or folder to connect. `git rev-parse --show-toplevel`
   if it is a git repo; otherwise the current directory.

## Step 2 — Run the installer once, globally

The MCP connection belongs to the USER, not to a repo: authenticate once and
every project is covered. Run this from anywhere — you do not need to be inside
a repo, and you must not re-run it per project.

One command does the whole setup: it installs the governance rules at user
level and **configures the MCP server for that client**. Pass the harness you
identified in Step 1.

Valid ids: `claude-code` `antigravity` `codex` `cursor` `vscode` `windsurf`
`zed` `generic`

**macOS / Linux**
```sh
curl -fsSL https://mcp.workcamp.app/install.sh | sh -s -- --harness=antigravity
```

**Windows (PowerShell)**
```powershell
$env:WORKCAMP_HARNESS='antigravity'; irm https://mcp.workcamp.app/install.ps1 | iex
```

Omit the harness and it will ask interactively. It also asks before touching a
config file that already exists (keeping a `.bak`), and merges with `jq` when
that is available so other MCP servers are preserved. It is idempotent — re-run
it any time; `--update` refreshes the governance block without touching pins.

If the installer completed, **skip to Step 4** — the MCP server is already
configured. Step 3 is only for doing it by hand or checking what was written.

`--repo` additionally installs the governance file and `.workcamp.yml` into the
current repo, for teams who want them committed. It is optional: per-project
setup otherwise happens by itself (Step 5).

## Step 3 — Manual alternative: connect the MCP server by hand

Only needed if the installer could not run, or you want to verify what it
wrote. **The URL field name is not the same across clients** — using the wrong
one means the server silently never appears.

### Claude Code
```sh
claude mcp add --transport http workcamp https://mcp.workcamp.app/mcp
claude mcp login workcamp
```
Headless/SSH: `claude mcp login workcamp --no-browser`, then paste the redirect
URL back.

### Antigravity (CLI `agy` and IDE — one shared config)
File: `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json`
(workspace). Windows: `%USERPROFILE%\.gemini\config\mcp_config.json`.

**The field MUST be `serverUrl`.** `url` and `httpUrl` are not supported and the
server will not appear.
```json
{
  "mcpServers": {
    "workcamp": {
      "serverUrl": "https://mcp.workcamp.app/mcp"
    }
  }
}
```
Sign in from Agent Settings: it opens a browser, you approve, then paste the
authorization code back into the settings panel.

### Codex CLI
File: `~/.codex/config.toml` (or project-scoped `.codex/config.toml`).
Windows: `%USERPROFILE%\.codex\config.toml`.

`codex mcp add` is for stdio servers only — edit the file for an HTTP server.
```toml
[mcp_servers.workcamp]
url = "https://mcp.workcamp.app/mcp"
auth = "oauth"
```
Then `codex mcp login workcamp`. **Without `auth = "oauth"` Codex connects
unauthenticated and every tool call is rejected** — that is the usual "it
connected but nothing works".

### Cursor
File: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project).
Windows: `%USERPROFILE%\.cursor\mcp.json`.
```json
{
  "mcpServers": {
    "workcamp": {
      "url": "https://mcp.workcamp.app/mcp"
    }
  }
}
```
No `type`/`transport` key. Cursor prompts you to sign in on first use.

### VS Code (Copilot / MCP)
File: `.vscode/mcp.json`. Note the key is `servers`, not `mcpServers`, and
`type` IS required.
```json
{
  "servers": {
    "workcamp": {
      "type": "http",
      "url": "https://mcp.workcamp.app/mcp"
    }
  }
}
```

### Windsurf / Zed / anything else
Add an HTTP (streamable) MCP server pointing at
`https://mcp.workcamp.app/mcp`. Most clients use `mcpServers` + `url`; check
your client's docs for the exact key. A spec-compliant client needs no manual
OAuth setup — it reads
`https://mcp.workcamp.app/.well-known/oauth-protected-resource` (RFC 9728),
finds the authorization server, registers itself and runs the browser flow.

### No interactive browser (CI, container, headless)
Complete the OAuth flow once on a machine that has a browser, then pass the
bearer token via whatever header mechanism the client supports:
`Authorization: Bearer <token>`. Antigravity and Cursor take a `headers`
object; Codex takes `bearer_token_env_var`. Keep tokens out of committed
files — every action is attributed to that user's identity.

## Step 4 — Verify

Call the `get_policy` tool. If it returns the governance rules, the connection
and your scopes are both good. Report the result to the user.

If it fails:
- **Server missing entirely** → wrong URL field name. Antigravity needs
  `serverUrl`; Cursor and Codex need `url`; VS Code needs `servers` + `type`.
- **Connects but every call is refused** → unauthenticated or under-scoped. Run
  the login step; for Codex confirm `auth = "oauth"` is present.
- **Tools work but the rules are ignored** → the governance file is missing.
  Re-run Step 2.

## Step 5 — Pinning a project (automatic, not an install step)

There is nothing to run per repo. On first tracked work in any folder, the
agent resolves which Workcamp project it belongs to and writes it into
`.workcamp.yml` as `projectId` + `projectName`.
Never guess it: call `resolve_project`, and if several match, ask the user which
exact one. If the location should not be tracked at all, set `tracking: off`.

---

## Rules you must follow once connected

Call `get_policy` for the authoritative, current version. In summary:

- Open a ticket with `start_task` **before** writing code; keep tickets coarse
  (one per multi-day chunk, not per edit).
- If the pinned project has sub-projects, `start_task` refuses to guess — ask
  the user which node the ticket belongs to.
- Log meaningful steps with `log_progress` and real hands-on hours with
  `log_time`.
- Descriptions and comments are **HTML, not Markdown**. Write plain prose or the
  small allowed subset; Markdown renders as literal punctuation.
- Give every ticket dates — supply `estimatedEffort` and the server derives them.
- Close with `complete_task` only when the full scope is genuinely done.
- For large multi-phase work, ask the user whether they want a milestone, flat
  tickets, or phases. Never create a milestone unasked.