Docs · MCP

Point your agent at the queue

pinwise is a remote MCP server. Your agent pulls the next ready ticket, does the work in your repo, and reports evidence. We rescan the branch and close the ticket only if the lockfile moved.

Server URL: https://api-staging.pinwise.dev/mcp
Transport: Streamable HTTP
Auth: Authorization: Bearer pw_… or OAuth

01Get an API key

Sign in with your email or GitHub, then install the read-only GitHub App on the repos you want tracked. Linking a new installation uses the GitHub sign-in, so pinwise can check that you are the one who installed it.
Open Settings → API keys and create a key per machine or agent. Name it so you can revoke it later.
Copy it straight away. Keys start with pw_, are shown once and stored only as a hash.

MCP access is part of every paid plan. Keep keys in your shell environment, never in a committed file.

02Add the server

One command adds the server for this project. Or commit .mcp.json and keep the key in your shell.

terminal

claude mcp add --transport http pinwise https://api-staging.pinwise.dev/mcp \
  --header "Authorization: Bearer pw_…"

.mcp.json

{
  "mcpServers": {
    "pinwise": {
      "type": "http",
      "url": "https://api-staging.pinwise.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${PINWISE_API_KEY}"
      }
    }
  }
}

Run /mcp inside Claude Code: pinwise should be listed as connected with 9 tools.

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this repo).

~/.cursor/mcp.json

{
  "mcpServers": {
    "pinwise": {
      "url": "https://api-staging.pinwise.dev/mcp",
      "headers": {
        "Authorization": "Bearer pw_…"
      }
    }
  }
}

Settings → MCP: pinwise shows a green dot. Ask the agent to "list my pinwise repos".

Codex reads remote servers from ~/.codex/config.toml and takes the key from an environment variable.

~/.codex/config.toml

[mcp_servers.pinwise]
url = "https://api-staging.pinwise.dev/mcp"
bearer_token_env_var = "PINWISE_API_KEY"

shell profile

export PINWISE_API_KEY="pw_…"

Run codex mcp list: pinwise should appear. Then ask "what is the next pinwise ticket?".

Windsurf uses serverUrl for remote servers in ~/.codeium/windsurf/mcp_config.json.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "pinwise": {
      "serverUrl": "https://api-staging.pinwise.dev/mcp",
      "headers": {
        "Authorization": "Bearer pw_…"
      }
    }
  }
}

Open Cascade → MCP servers and press refresh: pinwise lists its tools.

Prefer OAuth over a key?

Agents that support MCP OAuth can connect without a key. Use the app URL https://staging.pinwise.dev/api/mcp (not the API URL above): your agent opens a browser, you sign in (email or GitHub), pick a workspace and approve. API keys work on both URLs.

terminal (OAuth, no key)

claude mcp add --transport http pinwise https://staging.pinwise.dev/api/mcp

03Start working

The server also ships this as the work_next_ticket prompt. Paste it, or pick the prompt from your agent's MCP menu. One agent per lane; tickets inside a lane run in order.

work_next_ticket

Use the pinwise MCP server. Call list_tickets for this repo and take the first ready ticket.
Call start_ticket, then follow the ticket body exactly: pin the target version, regenerate the lockfile,
run the tests, lint, typecheck and build. Never delete, skip or loosen a test.
When done, call complete_ticket with the evidence the ticket asks for.

04Tools

pinwise MCP tools
Tool	Input	Returns
`list_repos`	—	Repos in the workspace with their last scan summary
`list_tickets`	repo, status?, lane?, limit?	Tickets, ready ones (blockers closed) first
`get_ticket`	id	Full markdown body plus structured fields
`start_ticket`	id, agent_name	A 30-minute renewable lease; status in_progress
`add_note`	id, text	Appended note, visible on the board; renews the lease
`complete_ticket`	id, evidence	Status verifying and a verification job id
`request_rescan`	repo, ref?	Scan job id
`get_scan`	repo	Latest summary and RAG rows
`approve_feature`	id, decision, note?	The recorded feature decision

Resources: ticket://<id> and repo://<owner>/<name>/scan. Results are markdown first, with a structured data block.

05Troubleshooting

401 Unauthorized: The key is missing, mistyped or revoked. The header must be exactly Authorization: Bearer pw_…. For OAuth, connect to https://staging.pinwise.dev/api/mcp; the API URL cannot run the browser sign-in.
403 plan required: MCP is on Solo and up. The free plan keeps the board and the top 3 researched tickets.
Ticket went back to in_progress: Verification failed: the rescan of your ref did not show the target. The ticket notes say what the scan saw.
Lease expired: Leases last 30 minutes and renew on add_note. An expired lease sends the ticket back to open.