Use TheSpider through MCP

The remote Model Context Protocol (MCP) server lets your coding agent run TheSpider without the thespider-agent binary. The coding agent reads your checkout with its own tools and performs each slice as the audit model.

Connect your MCP client

Add the server to Claude Code:

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

In Claude Desktop, open Settings → Connectors → Add custom connector, name it TheSpider, and set the connector URL to:

https://thespider.xyz/v1/mcp

The server uses the stateless MCP 2026-07-28 protocol. Your MCP client opens a browser once for OAuth 2.1 authorization. The consent screen shows the requesting application, its return address, and the organization whose projects, campaigns, findings, triage, readiness, usage, and PR gates it can read and write. Access tokens expire after one hour; the client rotates refresh tokens in the background.

What the token can do

The issued token is bound to the MCP endpoint (/v1/mcp) and is refused on every other API route, so an authorized MCP client can reach only what the 15 tools expose — not the organization, member, invitation, or import surfaces of the REST API.

The grant is also tied to the person who approved it. It stops working as soon as that account is banned, deleted, suspended, or removed from the organization, and a role change narrows it at once. An organization admin can end every grant from Settings → Tokens → Revoke, which also kills the refresh tokens behind them.

Ending a grant is currently an organization-wide action; there is no per-client revoke screen yet.

Roles

If you are a member and the repository has no project yet, ask an organization admin to create it once. Every later session — including thespider_init — works at the member role.

Initialize a repository

1. Open your coding agent in the repository you want to audit.
2. Ask it to call thespider_status. The agent must 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 the agent write the returned .thespider/mcp.json pointer file verbatim.
5. Keep the returned project_handle in the conversation. Every project-scoped tool requires it.

The pointer file contains the server, organization, project, profile, and model codes. It contains no token or opaque handle, is safe to commit, and lets a later session identify the same project. A new session calls thespider_init again to mint a fresh project_handle.

Run an audit

Use this loop:

1. Call thespider_start_audit with the project_handle and current branch, commit, and dirty state.
2. Call thespider_next_slice with the returned campaign ID.
3. Analyze the repository against the complete slice prompt with the coding agent's file-reading tools. Do not edit the target code during the audit.
4. Call thespider_submit_findings with the returned slice_handle and the findings array. Submit findings: [] when the slice is clean.
5. Repeat steps 2–4 until thespider_next_slice reports that no claimable slices remain.
6. Call thespider_list_findings to review results. For an incremental campaign, call thespider_pr_gate to read the gate result.

Report campaign progress as completed of total. Do not call a campaign complete while slices remain.

Keep handles with the matching tool call

project_handle identifies the selected organization, project, profile, model, and local workspace for the current session. slice_handle identifies one claimed lease and carries the prompt hash and finding marker needed by thespider_submit_findings. Both handles are opaque and integrity-protected. They do not replace the OAuth token or grant additional access.

If a handle is unreadable, call thespider_init again for a project handle or thespider_next_slice again for a slice handle. Do not edit either value.

Add another model

Each MCP session declares one model family because the connected coding agent is the model. To add a second model's perspective, open the same repository with a different coding agent or model family, authorize the same TheSpider organization, and call thespider_init again with the same git_remote_url — that argument is how the server matches the existing project instead of creating a second one. It then enables the new model on that project.

Start an audit at the same commit from the new session. The existing campaign is reused and topped up with slices for the newly enabled model, so both perspectives land in one campaign. Each session claims only its own model's slices, and findings pass through the same server-side parser, scrubber, fingerprinting, and deduplication pipeline.

thespider_init changes nothing else about the project's model configuration. Enabling a host-agent model never affects campaigns started by thespider-agent or by a webhook: those plan only the models a local agent can claim.

See Data handling for what TheSpider receives and what your coding-agent provider can receive while it reads the checkout.