Connect over MCP

The remote MCP server lets a coding agent run TheSpider with no thespider-agent binary. The agent reads the checkout itself and is the audit model.

If you already installed the CLI, you usually want the skills catalog instead (npx skills add https://thespider.xyz -g).

Connect

Claude Code:

claude mcp add --transport http thespider https://thespider.xyz/v1/mcp

Claude Desktop: Settings → Connectors → Add custom connector, name TheSpider, URL:

https://thespider.xyz/v1/mcp

The client opens a browser once for OAuth. You approve access for one organization. Tokens last an hour; the client refreshes them in the background.

The MCP token works only on /v1/mcp. It cannot call the rest of the API. You can revoke your own authorizations on Account → Security → Agents and integrations; an admin can revoke every grant from Settings → Tokens → Revoke.

If the organization has a sign-in policy, approve the client while signed in with an allowed method. The consent page marks organizations your current sign-in does not satisfy. A client authorized before the policy stops working (org_policy_sign_in_method) until you authorize it again.

Who can do what

If you are a member and the repo has no project yet, ask an admin to create it once.

First session in a repo

1. Open the coding agent in the repository.
2. Ask it to call thespider_status (do this at the start of every session).
3. Ask it to call thespider_init with the repository path and its model family.
4. Let it write .thespider/mcp.json exactly as returned. That file is safe to commit: server, org, project, profile, model codes. No token.
5. Keep the returned project_handle in the conversation. Project-scoped tools need it.

A new session calls thespider_init again for a fresh handle.

Run an audit

1. thespider_start_audit with the project_handle and current branch, commit, and dirty state.
2. thespider_next_slice with the campaign ID.
3. Read the repo against the slice prompt. Do not edit the target code.
4. thespider_submit_findings with the slice_handle and a findings array ([] if the slice is clean).
5. Repeat 2–4 until no claimable slices remain.
6. thespider_list_findings to review. For a PR campaign, thespider_pr_gate reads the gate.

Report progress as completed of total. Do not call the campaign done while slices remain.

If the campaign was cancelled

A member can cancel a campaign while a coding agent is working on it. An MCP host agent sends no heartbeat, so it cannot be interrupted: a slice it is already working on keeps running, and the cancel only reaches it at its next thespider_next_slice or thespider_submit_findings call. thespider_next_slice then answers that the campaign was cancelled (by whom, when, why) and tells the agent to stop. thespider_submit_findings for a slice that was in progress is not counted: the output is kept as provenance only, no findings are ingested, and the answer says to stop. thespider_campaign_progress reports status cancelled, and thespider_pr_gate reads degraded with the cancellation noted. The agent should not claim, submit, repair or resume that campaign. The agent should report the cancellation and ask you before starting any new audit; a fresh campaign is billed again. Findings from slices that finished before the cancel stay, and claims already billed are not refunded. There is no MCP tool to cancel; use the web UI or thespider-agent campaigns cancel.

If a handle looks unreadable, call thespider_init or thespider_next_slice again. Do not edit the value.

Add a second model

Each MCP session is one model family, because the connected agent is the model. To add another perspective, open the same repo with a different agent, authorize the same org, and call thespider_init with the same git_remote_url. That is how the server finds the existing project.

Start an audit at the same commit. The campaign is reused and topped up with slices for the new model. Each session only claims its own model's slices.

MCP models do not change campaigns started by thespider-agent or a webhook. Those still plan only models a local agent can claim.

See Data handling for what TheSpider receives while the coding agent reads the checkout.