MCP

Spider Sense is a Model Context Protocol server, so a host that cannot run a command still gets the answers the CLI gives.

Eight tools cover the loop: status, findings, trace, mark, resolve, compare, check and sql. Each one is an adapter over the agent-facing endpoints (Agent-facing endpoints). A tool call is one call into the same handlers the CLI and the UI use, and its result is the same text rendering the matching command prints, so an MCP answer and a CLI answer over the same window are the same bytes.

When to use it

MCP is for the host that has no shell. MCP and the CLI give the same answers, so the choice depends on whether the host can run a command.

Host Use

An agent with a shell (Claude Code, Codex CLI, Gemini CLI, Aider, a script)

the CLI and the skill: init, then the commands of The CLI

A host without a shell (Claude Desktop, an IDE chat panel)

MCP: init --mcp, or http://127.0.0.1:4000/mcp

CI or a build gate

check, which exits 0 when every rule is within its limit and 1 when one is over, or the Gradle plugin’s task (Check as a build step)

The application has crashed

the CLI, or MCP over stdio, because both open the H2 file in process

Do not enable both the CLI and MCP in one host. Two tools that give the same answer make the model choose between them, and the MCP tool schemas take up context for answers the CLI already gives.

The skill teaches the loop for the CLI (The Agent Skill), and the MCP server’s instructions field carries the same loop in one paragraph, so a host on MCP gets the same steps as a host on the CLI.

The transports

Streamable HTTP

The Streamable HTTP transport is POST /mcp on the server’s own port, which is the port the UI answers on. One JSON-RPC 2.0 message travels per request, with Content-Type: application/json both ways. A request is answered with 200 and the JSON-RPC response, and a notification with 202 and no body.

The server is stateless. No session id is issued or required, GET /mcp is 405, and a JSON array, the batch of older protocol revisions, is refused with -32600. A message is at most 1 MB (1,048,576 bytes), and a larger one is 413 with a JSON-RPC error -32600 whose id is null, so the answer is still a JSON-RPC message. Over stdio such a call, forwarded to a running server, is a failed tool result saying so (stdio). An MCP-Protocol-Version header naming a revision other than 2025-06-18, 2025-03-26 or 2024-11-05 is 400. A parameter of the wrong type, such as a protocolVersion that is not a string or arguments that are not an object, is -32602. A request whose Origin is not the server’s own, or whose Host is not a name of this machine, is 403, as on every endpoint (API conventions), which is the Origin check the transport asks of a server. So a web page, such as a browser-based agent or a browser extension, cannot call /mcp: its request carries an Origin, and no CORS preflight is answered.

This transport needs the server to be up, so it stops answering when the application stops.

stdio

java -jar spider-sense.jar mcp [--url=<base url>] [--db=<path or jdbc url>]

The mcp command reads newline-delimited JSON-RPC on stdin and writes it on stdout, both in UTF-8 whatever the platform’s charset. Nothing else goes to stdout, diagnostics go to stderr, and the command ends at end of input.

initialize, ping and tools/list are answered in the process. A tools/call goes to the Spider Sense at --url when one answers there. Without --url, the CLI’s default and SPIDERSENSE_URL apply. When none answers, the mcp command opens the H2 file in process exactly as the CLI does, with the same line on stderr saying so. --db reads a file without asking any server (The direct-file fallback). A --url named on the command line states that a server is there, so when nothing answers it the call is a failed tool result saying so, rather than a read of a file that may hold a different application. A Spider Sense that is busy past the CLI’s 2 minutes answers that call with a failed tool result saying so, and the next call asks it again. So does one that answers a call with an error status other than 404 or 405: it is running and refused that one message. A 404 or 405 means what answers at the URL is not a Spider Sense of this version, and the session turns to the file as when nothing answers. So does a success that is not a JSON-RPC message in application/json, such as a redirect or a web page, which would otherwise reach the host as the answer to its call or leave the call unanswered. So does any answer without the X-Spider-Sense header every Spider Sense answer carries (API conventions), an error status among them.

stdio is the transport for a host on the same machine, and the one that still answers after the application has crashed.

The tools

Every argument is the CLI option of the same meaning, and a selector is a string as in Time selectors. An empty service is no filter, as service= is over HTTP (API conventions), since a model fills an optional argument with an empty string as often as it leaves it out; mark records no service for it. For the same reason an empty or blank since, until, endpoint or diff is an argument left out: since is then 15m, until is now, check judges every endpoint and trace answers the one trace.

Tool Arguments Answers

findings

since, until, service, limit (1 to 100), full, hideAcked

the findings text (Findings)

trace

traceId (required), full, diff

the trace tree, or the two traces aligned when diff names a second one (Trace diff)

mark

name (required), note, service

the mark, as the CLI prints it

resolve

findingId (required), note

the resolution, as the CLI prints it (Resolutions); a failure naming the id when no finding has it

compare

before, after (both required), until, service

the compare text (Compare)

check

since, until, service, endpoint, maxP95Ms, maxErrors, maxErrorRate, maxQueriesPerRequest, maxSlowQueries, maxNPlusOne, maxLogErrors, maxRegressions, minApdex

the check text (Check)

sql

sql (required), limit (1 to 5000)

the sql text (SQL)

status

none

the status text, as status prints it: the mode, the port, the database, the thresholds in force, the services seen and how much is stored

status is the step the instructions name first, confirming that the application is collecting, so every step they name has a tool. Over HTTP it is GET /api/status of the server that answers; over stdio with no server it is the file’s status, whose mode is file, as the CLI’s status prints it there.

A mark name matches [A-Za-z0-9._-]{1,64}, and is not one a selector reads as something else, such as 5m, now or start.

A result is { "content": [ { "type": "text", "text": "<the Markdown>" } ] }. check also carries structuredContent with pass and requests, so a host need not read the heading for the verdict.

An answer the CLI reports on stderr with exit code 4, such as no such trace or no such mark, becomes a tool result with isError: true whose text is that message on one line. A refused statement, a bad selector and a sql call over a database that has no read-only user yet are reported the same way. So is a sql limit below 1, which POST /api/sql answers with a 400. A limit past its maximum, however large, is the maximum. A missing required argument or an unknown tool is a JSON-RPC -32602.

Tool descriptions are one sentence each and say when to use the tool, not how the output looks, because the output is the text rendering and needs no description.

Methods

initialize answers the client’s protocolVersion when it is one the server knows (2025-06-18, 2025-03-26, 2024-11-05), and 2025-06-18 otherwise. It also answers capabilities: { "tools": {} }, serverInfo: { "name": "spider-sense", "version": "<version>" }, and instructions, which is the loop in one paragraph: start the application under the agent, status to confirm it is collecting, mark, exercise, findings, fix, mark, compare, check, and resolve once the fix holds.

notifications/initialized is accepted and ignored, ping answers an empty object, tools/list is the eight tools, and tools/call runs one. Anything else is -32601.

Configuring a host

init --mcp writes the stdio server into the project’s .mcp.json:

java -jar spider-sense.jar init --mcp

It sets mcpServers.spider-sense to { "command": "java", "args": ["-jar", "<jar path>", "mcp"] }, with the same absolute jar path the CLAUDE.md block names (init). With --url=<base url>, the arguments end in "--url=<base url>" too, so every tool call asks the Spider Sense the project’s application sends to rather than the one on port 4000. An existing file is parsed as JSON and every other entry is kept, though the file is rewritten in Spider Sense’s own JSON formatting. A file that is not a JSON object is left alone, with a message on stderr and exit code 2, and init then writes nothing at all.

--mcp hands the host MCP instead of the CLI, never beside it, as the warning under When to use it asks. The block it writes still says where the jar is and how to start the application under it, and names the MCP server’s tools where the CLI’s lines would be. It installs no skill, because both skills teach the loop through the CLI, and the server’s instructions carry the same loop, and it removes the skills an earlier init installed (What it prints).

Without --mcp, init writes no server, because a host with a shell is meant to use the CLI, and it removes the spider-sense server an earlier init --mcp wrote, so a second run in the other mode leaves one interface and not both.

A host that reaches a running Spider Sense over HTTP is configured by hand instead:

{ "type": "http", "url": "http://127.0.0.1:4000/mcp" }

Considered and deferred

MCP over HTTP only

The first design served MCP on the existing port and nothing else, which is the least code. It was rejected as the only transport, because a host on the same machine could then ask nothing after the application crashed, while the CLI still reads the H2 file with the server gone. The stdio transport reuses the CLI’s own decision, a server if one answers and the file otherwise, and adds no third way of answering.