Security tooling

Inspector

A manual console for driving any MCP proxy by hand. Fire JSON-RPC envelopes through the gateway, inspect every response byte, save reusable cases, and replay findings from a Security Scan in one click.

What the inspector is#

The inspector is a power-user console at /dashboard/inspector. It lets you pick any MCP proxy you've configured, choose a tool (or hand-craft any JSON-RPC method), set the arguments, fire the request through the AIronClaw gateway, and read the parsed response — status, headers, body, latency, and the raw envelope as the upstream returned it.

Compared to a generic HTTP client (curl, Postman) the inspector adds:

  • Automatic session-id handling — the inspector tracks the mcp-session-id across the initialize handshake so each subsequent call carries it correctly without manual copy-pasting.
  • Schema-driven argument forms — when the selected tool ships an inputSchema the inspector renders the matching fields and validates types before sending.
  • Identity multiplexing — pick which AIronClaw consumer (your-self, an API key, none) the request will be authenticated as, so you can verify the firewall's per-key policy live.
  • One-click replay from a Security Scan finding — see Replay from a finding.

Opening the inspector#

Open Inspector in the dashboard sidebar. You'll see a server picker at the top — your configured MCP proxies are listed. Pick one and the right-hand pane loads that proxy's tool catalog plus any saved cases for the proxy.

You can also reach the inspector pre-filled from a finding's proof of concept: the "Open in Inspector" button on a Security Scan finding navigates here with the tool, the payload, and the identity hydrated from the URL.

Building a request#

The request panel has three editable sections.

Request controls

Method
string
Any JSON-RPC method. Common ones: initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get. The MCP spec methods are pre-populated in the dropdown; you can type a custom one.
Tool
select
Visible only for tools/call. Picks one of the tools the proxy exposes. When selected, the params panel renders the tool's input schema as a form.
Arguments
JSON / form
Switch between a JSON editor (full control) and a form view (rendered from inputSchema). The two views stay in sync — switching back and forth doesn't lose state.
Identity
self / api-key / none
Who sends the request: your dashboard identity (signed via the inspector trust path), one of your API keys, or no credentials. Lets you verify rule scoping from the consumer's perspective without provisioning a separate test client.
Session
auto / manual
Auto reuses the session id captured on the previous initialize. Manual lets you paste a custom session id or leave it blank to test session-less calls.
Headers
key / value
Extra request headers (X-Custom-Auth, X-Tenant, etc.) get added before the request leaves the gateway. Useful when the upstream needs a header the standard inspector doesn't set.
The gateway is in the loop

Every inspector request transits the AIronClaw gateway — the same path production traffic takes. Rules, DLP, prompt guards and rate limits apply. The inspector lets you observe what the firewall does on a real request without spinning up a test client. To bypass the firewall and reach the upstream raw, you'd use a different tool — that's intentional.

Response inspection#

After clicking Send the response panel shows:

  • Status code + latency in milliseconds.
  • Headers — full response headers including the AIronClaw-emitted observability headers (x-aironclaw-request-id, x-aironclaw-upstream-latency, etc.) so you can cross-reference the request in Logs.
  • Body — pretty-printed JSON when the content-type is JSON, raw text otherwise. SSE responses (text/event-stream) are decoded event-by-event.
  • Decisions — when the firewall blocked, redacted, transformed, or rate-limited the request, that decision is summarised here with the rule id that fired.

Saved test cases#

The inspector can persist the current request as a case for the active MCP proxy. Cases capture method + tool + arguments + identity + headers. They're listed in the right-hand sidebar and stay grouped by the proxy they belong to.

Cases are useful for:

  • Regression set — every time you ship a new rule, replay your saved cases to verify nothing broke that used to work.
  • Proof set — keep the exact request that triggered a finding, so a re-test after remediation is trivial.
  • Onboarding — a new operator can read your saved cases to learn how each tool is expected to be called.

What a case stores

Label
string
Human-readable name shown in the sidebar.
Method + tool
auto
Captured from the current request panel state.
Arguments
JSON
Stored verbatim. Restoring re-hydrates both the JSON editor and the schema form.
Identity
consumer / key id
When you restore the case, the identity selector returns to the saved value.
Headers
k/v
Custom headers are persisted with the case.

Replay from a finding#

Every Security Scan finding includes a replay envelope — the exact JSON-RPC request that confirmed the vulnerability. The finding card has an Open in Inspector button that pre-fills the inspector with that envelope. From there you can re-fire it, tweak the payload, save it as a case, or hand it to a colleague via a shareable URL (deep-linking is done with base64url-encoded URL params so nothing sensitive lands in server logs).

Closing the loop on a finding

The intended flow:

  1. Security Scan finds a vulnerability — say SQL injection on get_customers.
  2. Apply the suggested rule (or write a custom one) under MCP rules.
  3. Click Open in Inspector on the finding and re-fire the same envelope.
  4. The inspector shows the firewall's block / redact decision in the response panel. The vulnerability is confirmed mitigated.
  5. Save the case so the next scan / next operator can verify the rule still holds.

REST API#

The inspector is also available over REST so an agent or CI job can drive it programmatically. Authentication uses the personal access token described in Authentication.

Endpoints

POST /api/mcp/:id/inspect
fire a request
Body: { method, tool, params, identity, headers, sessionId }. Returns { status, headers, body, latencyMs, decisions[] }. The request transits the gateway with the inspector trust path.
GET / POST /api/mcp/:id/inspect/cases
saved cases
List or create a saved case for the MCP.
GET / PATCH / DELETE /api/mcp/:id/inspect/cases/:caseId
single case
Read, update label/body, or delete a saved case.
POST /api/mcp/:id/inspect/compliance
compliance check
Convenience endpoint that runs a curated set of compliance probes against the MCP — see Compliance.