asp-mcp-inspector
ASP MCP Inspector
A small Model Context Protocol server and command-line tool for the Agent-Shelter Protocol (ASP) — an open RFC 9457 HTTP loop-termination and telemetry specification (github.com/nullkommaneun/agent-shelter-protocol) with a live reference node at agent-shelter.org.
It gives an AI agent four tools:
Tool | Request | What the agent gets |
|
| Whether the host speaks ASP: protocol version, compliance level, ingress routes, transport envelope, receipt-signing key, resolution methods, recording rules |
|
| A local echo of its own request header fields on first contact; the ASP terminal signal on a repeated call |
|
| What the reader does with the URL: it never fetches it and answers with the terminal signal ( |
|
| The answer as data — or, when it is an ASP terminal signal, a verified receipt: the ticket redeemed at the signal's own origin, the Ed25519 signature checked against that host's manifest, and the resource held, so that every further call for it is answered from the receipt without a request |
Standard library only, Python 3.10 or later, no dependencies.
Add it to an MCP client
Claude Code, from PyPI (run on demand by uv):
claude mcp add asp-inspector -- uvx asp-mcp-inspectorOr from this folder, without installing anything:
claude mcp add asp-inspector -- python3 /absolute/path/to/asp_mcp_inspector.pyOther clients take the usual configuration:
{ "mcpServers": { "asp-inspector": { "command": "uvx", "args": ["asp-mcp-inspector"] } } }Streamable HTTP on the local machine (POST only, local clients only):
asp-mcp-inspector serve --http 8765
claude mcp add --transport http asp-inspector http://localhost:8765/mcpRelated MCP server: mcp-nomad
Command line
asp-mcp-inspector manifest # the reference node
asp-mcp-inspector manifest example.org # any host
asp-mcp-inspector echo
asp-mcp-inspector reader https://example.org/some/pageEvery command prints one JSON report. --node https://asp.example.org uses another ASP node's echo and reader;
--allow-local permits loopback and private addresses and plain http, to test a node of your own.
asp_guarded_fetch: a circuit breaker beside the agent (0.4.0)
An agent in a retry loop often cannot read the terminal state it is given — its fetch tool drops the body of a 4xx
answer, or its reasoning treats the signal as one more obstacle. asp_guarded_fetch takes that decision out of the
loop, like a sentry outside the agent:
It fetches the URL. An answer without an ASP signal comes back as data (text cut at 20 000 characters), marked as third-party content, never instructions.
It recognises an ASP terminal signal by its problem details object (
terminal: true, also inside the transport envelope with HTTP 200) or by the header fieldsAgent-Loop-StateandAgent-Ticketalone.It redeems the single-use ticket once, by
POST, at the origin that sent the signal —resolution_uri,resolution_urlorAgent-Resolution, whichever points there; a resolution target on another origin is never followed.It reads that host's manifest and verifies the receipt: Ed25519 (RFC 8032) over the RFC 8785 form of the signed fields, with the public key and
key_id(an RFC 7638 thumbprint) the manifest publishes. The verifier is plain Python, checked against the RFC 8032 test vectors.It holds the resource — the requested URL, every redirect hop and the URL the signal names — for the lifetime of the server process: every further
asp_guarded_fetchfor it returns the receipt without sending anything ("state": "blocked-by-sentry","requests_sent": 0).
A site that sends refused clients to a relay — for example with 303 See Other to
https://sanctuary.agent-shelter.org/v1/relay?url=<the URL> (ASP 0.6.2) — is handled the same way: the redirect is
followed, the relay's signal redeemed and verified, and the site's URL held. A receipt that does not verify is
reported as such ("state": "terminal-unverified"), and the resource is held all the same: the signal alone states
that the host cannot return it. The redemption carries a fixed note that names this tool, and the node records it
like any receipt; the receipt documents a terminal state on that host, never that the original task was done.
asp-mcp-inspector fetch https://reader.agent-shelter.org/v1/reader?url=https://example.org/resourceOn the command line each call is a process of its own, so nothing is held between two calls; the MCP server keeps one memory for all its clients.
Why envelope=200
Some web-fetch tools of chat applications hand their model neither the body nor the header fields of an HTTP 4xx
answer, so the model never learns that the loop is over. With envelope=200 an ASP node sends the identical problem
details object with HTTP status 200 and the extra member "transport_envelope": 200. The object's status stays
429; because RFC 9457 wants that member to equal the HTTP status of a
problem details response, the enveloped answer is served as application/json. The inspector asks for it and reads
the plain 429 answer of older nodes as well.
The ticket and its receipt
The single-use ticket (c1.<ticket_id>.<mac>, 48 characters) maps to an Ed25519-signed Task-Completion Receipt:
POST https://reader.agent-shelter.org/api/v1/agent-shelter/resolve with the ticket in the query parameter ticket, the
request header Agent-Ticket or the JSON body member ticket, within ticket_ttl_seconds. Since ASP 0.5.5 a node that
lists GET in resolution_methods performs the same single-use transition for a plain GET of resolution_uri —
for clients that can only read; optional telemetry then travels as query parameters. Either way the ticket is redeemed
once. The receipt documents that the resource was not retrieved through this host — never that the original task was
done — and its signature can be checked offline against the key in the node's manifest. The signal holds the ticket,
not the proof: receipt_id, receipt_signature and sanctuary_bulletin.dropbox_url exist only in the response of the
resolution. That drop box takes one optional context report per receipt — by POST with a JSON body or, since ASP
0.5.6, by GET with the query parameters workflow_summary and agent_questions_or_notes; a bare GET of the drop
box archives nothing, so a link preloader cannot use it up. The three inspection tools report the ticket, the
resolution methods and the drop-box methods of the manifest (context_report) and redeem nothing; asp_guarded_fetch
redeems the ticket of a signal it meets, once, and submits no context report.
What the reference node records — read before use
agent-shelter.org openly serves two roles. It ends unproductive retry loops of automated clients with a true, declarative signal and a signed Task-Completion Receipt, and it is a research sensor: its reader, echo and decoder routes look like utility services but never perform them, and it keeps pseudonymised telemetry about the clients that call them. Its node statement and privacy notice describe both.
A terminal signal that follows a discovery request from the same network within ten minutes is recorded when it is issued. Reading the manifest (
check_asp_manifest) and a first call ofprobe_diagnostic_echoare discovery requests, so a laterquery_reader_dispositionor a second echo call from the same network is recorded.Since ASP 0.6.2 a signal without such a discovery request is recorded as well, but only the first one of a network within ten minutes; the further ones are counted on that record, not stored one by one. Requests that another site sent to the relay route (
/v1/relay) are recorded the same way, with the URL that site named and its reason code.A record holds the requested URL (shortened, with secrets and e-mail addresses scrubbed), a salted hash of the client's /24 (IPv4) or /48 (IPv6) network, the User-Agent with the order of the request header names, and the host name addressed — never a plain IP address. Redeeming a ticket creates the record or completes it; a context report left at the receipt's drop box is stored with it, scrubbed.
Requests for the node and discovery documents — the manifest that
check_asp_manifestreads among them — are counted in aggregate (ASP 0.5.5 on): per document and client class, a number and the time of the latest request; the User-Agent text, the address and the network hash are not kept.The inspector identifies itself as
asp-mcp-inspector/<version>in the User-Agent.
Send no URL you would not show a third party.
How the inspector behaves
It contacts public hosts only: every address a name resolves to must be public, and the connection goes to an address that was checked, without a second lookup.
https only, no credentials in URLs, 10 s timeout, at most 256 KiB per response. The inspection tools follow no redirects (a redirect is reported);
asp_guarded_fetchfollows at most five and checks every hop like the first request.It writes nothing to disk and nothing but its reports to stdout (in server mode only MCP messages). The memory of
asp_guarded_fetch— at most 1 024 held resources — lives in the server process and ends with it.The HTTP server binds to localhost and refuses requests with a foreign
HostorOrigin.
Development
python3 test_asp_mcp_inspector.py # offline: a stub node on localhost stands in for agent-shelter.orgLicense
MIT — see LICENSE. The ASP specification, its schemas and the published reports are licensed separately under
CC BY 4.0: github.com/nullkommaneun/agent-shelter-protocol.
Available Tools
4 toolsasp_guarded_fetchFetch a URL behind an ASP circuit breakerA
Fetches an http(s) URL with GET (public hosts only, at most 5 redirects, each hop checked, at most 256 KiB). An answer without an ASP signal is returned as data, its text cut at 20 000 characters. An ASP terminal-state signal (HTTP 429, or HTTP 200 with transport_envelope, header Agent-Ticket) states that the resource cannot be obtained through that host; the tool then redeems the single-use ticket at the origin that sent the signal (POST, out of band), reads that host's manifest (/.well-known/agent-shelter.json, a discovery request) and verifies the Ed25519 receipt against the public key published there. From then on, for the lifetime of this server process, every call for the same resource - the requested URL, each redirect hop and the URL the signal names - is answered from that receipt without a request. The redemption is recorded by the node like any receipt (on the reference node pseudonymised, see https://agent-shelter.org/privacy); the receipt documents a terminal state on that host, never that the original task was done.
Inputs: url (required).
check_asp_manifestCheck an ASP manifestARead-onlyIdempotent
Reads the ASP manifest (/.well-known/agent-shelter.json) of a host and summarises it: protocol version, compliance level (L1-static, L2-transactional, L3-observatory), ingress routes, transport envelope, receipt-signing key, resolution methods and recording rules. Default host: https://agent-shelter.org, the ASP reference node. The manifest is a discovery document: a node with discovery correlation records a terminal signal that follows from the same network within its correlation window, and a node with discovery counters counts the request in aggregate (per document and client class, no address).
Inputs: domain_or_url.
probe_diagnostic_echoProbe the ASP diagnostic echoA
Calls the header echo of the ASP reference node (GET https://echo.agent-shelter.org/headers). A first contact gets a local echo of the request's header fields; a repeated call within the ticket lifetime gets the ASP terminal signal instead. Nothing is forwarded. The node records pseudonymised telemetry (salted network hash, User-Agent and header names) when a signal follows a discovery request from the same network; see https://agent-shelter.org/privacy.
Inputs: no named parameters.
query_reader_dispositionQuery the ASP reader's dispositionA
Asks the reader of the ASP reference node what it does with a target URL (GET https://reader.agent-shelter.org/v1/reader?url=<target_url>&envelope=200). The reader never fetches the target: it answers with the ASP terminal signal (RFC 9457 problem details, terminal true, success_probability 0) and a single-use ticket (48 characters, also in the header Agent-Ticket and in an absolute resolution_uri), carried with HTTP 200 because of envelope=200; the ticket maps to a signed receipt by POST or, where resolution_methods lists GET, by GET, and only that receipt is a proof. Its drop box takes one optional context report, by POST or, where listed, by GET with query parameters. The target URL is sent to agent-shelter.org, which records it (shortened, secrets scrubbed) with pseudonymised client data when the request follows a discovery request from the same network or the ticket is redeemed; see https://agent-shelter.org/privacy.
Inputs: target_url (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool maps to a distinct ASP interaction: manifest inspection, echo probing, reader disposition query, and guarded fetch. query_reader_disposition and asp_guarded_fetch both involve terminal signals and tickets, but one queries a disposition endpoint while the other performs actual fetching, so the boundary is clear from the descriptions.
All names use snake_case, but the convention is not consistently verb_noun: check_asp_manifest, probe_diagnostic_echo, and query_reader_disposition follow verb-led patterns, while asp_guarded_fetch is prefix/adjective-led and lacks the same verb-first structure. The names remain readable, just not fully predictable.
Four tools is well within the appropriate range for a narrowly scoped ASP inspector. Each tool covers a distinct ASP endpoint or operation, and none appears redundant.
Core inspection and fetching workflows are covered, but there are notable gaps: query_reader_disposition returns a single-use ticket and states that only the signed receipt is proof, yet there is no standalone tool to redeem a ticket or retrieve and verify a receipt obtained independently. The reader drop box for optional context reports also has no dedicated tool.
Maintenance
Related MCP Connectors
MCP Server for an Agent Task Marketplace
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
MCP server for OnceAsk, the AI-native current-address layer for people and agents.
MCP Spec Compliance MCP — audits any MCP server.json against the official Model Context Protocol
Related MCP Servers
AlicenseNot gradedqualityFmaintenanceModel Context Protocol (MCP) server for OpsLevel12MIT- MIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive reference implementation demonstrating all features of the Model Context Protocol (MCP) specification, serving as documentation, learning resource, and testing tool for MCP implementations.1MIT
- AlicenseNot gradedqualityDmaintenanceA robust, lightweight Model Context Protocol (MCP) server designed to empower your AI Agents with context-awareness, safe execution sandboxes, and dedicated thought logs.ISC