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. An admin can revoke every grant from Settings → Tokens → Revoke. There is not yet a per-client revoke screen.

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 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.