Core resources

MCP Proxies

An MCP Proxy puts the AIronClaw firewall in front of a Model Context Protocol server. Every tool call, resource read and prompt request the agent makes is parsed, inspected and policy-checked before reaching the upstream.

The MCP Proxy object#

The proxy record stores the upstream MCP URL, the optional upstream auth (bearer token) the firewall should inject, and the inbound auth method clients use to talk to the firewall. The the gateway plumbing — Service, Routes, plugin instances — is created automatically on first save and torn down on delete.

Fields

string

UUID. Used in host routing and permission tags (mcp:<id>:tool:* / mcp:<id>:resource:*).

name

string

Human-readable label.

url

string

HTTPS URL of the upstream MCP server. SSRF-validated on write — must be public, non-loopback, non-private.

authType

enum

Upstream auth: none or bearer.

auth

object

Inbound auth (clients → firewall). { "mode": "aifw_api_key" } or { "mode": "jwt", "jwksJson": "..." }.

tools

object[]

Discovered tool catalog (populated by /tools). Each entry has name, description, JSON schema, etc.

proxyHost

string (read-only)

Host clients should connect to. Returned after proxy wiring completes.

createdAt

number

Unix timestamp (seconds).

What we never return

authToken plaintext, authTokenEnc ciphertext and any internal IDs are stripped from every response. The bearer you write is encrypted at rest and only decrypted in-plugin at request time.

Manage proxies#

List proxies#

GET/api/mcp

curl https://app.aironclaw.com/api/mcp \
  -H "Authorization: Bearer $AIFW_PAT"

Create a proxy#

POST/api/mcp

Validates the URL against the SSRF allow-list, enforces the per-user MCP quota, persists the record, and wires the gateway + the aifw plugin in one shot. Returns 403 if the quota is exhausted.

Body

name*

string

Human-readable label.

url*

string

Upstream MCP URL. Must be HTTPS and resolvable to a public IP.

authType

enum

bearer or none (default).

authToken

string

Required when authType is bearer. Encrypted before persistence; never returned.

auth

object

Inbound auth. Defaults to { "mode": "aifw_api_key" }. Provide { "mode": "jwt", "jwksJson": "{...}" } for JWT validation.

curl -X POST https://app.aironclaw.com/api/mcp \
  -H "Authorization: Bearer $AIFW_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem-prod",
    "url": "https://mcp.example.com/filesystem",
    "authType": "bearer",
    "authToken": "upstream-secret-...",
    "auth": { "mode": "aifw_api_key" }
  }'

Retrieve a proxy#

GET/api/mcp/:id

Returns the proxy record plus the current upstream DNS pin (when available) so you can verify routing.

curl https://app.aironclaw.com/api/mcp/$ID \
  -H "Authorization: Bearer $AIFW_PAT"

Update a proxy#

PATCH/api/mcp/:id

Partial update. Changing urlre-validates against SSRF rules and rewires the gateway's upstream + DNS pin. Setting authToken rotates the encrypted upstream bearer. Setting auth swaps the inbound auth method (and re-pushes config to the aifw plugin).

curl -X PATCH https://app.aironclaw.com/api/mcp/$ID \
  -H "Authorization: Bearer $AIFW_PAT" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://mcp.example.com/filesystem-v2" }'

Delete a proxy#

DELETE/api/mcp/:id

Tears down gateway resources, removes the Redis record, and stripsmcp:<id>:tool:* / mcp:<id>:resource:* tags from every API key owned by the caller.

curl -X DELETE https://app.aironclaw.com/api/mcp/$ID \
  -H "Authorization: Bearer $AIFW_PAT"

Re-resolve upstream IP#

POST/api/mcp/:id/re-resolve

Forces an immediate DNS resolve + upstream DNS target update, short-circuiting the 60-second background timer. Useful right after a cloud LB cutover.

curl -X POST https://app.aironclaw.com/api/mcp/$ID/re-resolve \
  -H "Authorization: Bearer $AIFW_PAT"

Tools#

Discover tools#

POST/api/mcp/:id/tools

Performs a live MCP tools/list handshake against the upstream (using the stored bearer if any), persists the result to the proxy record, and returns the discovered catalog. Use this whenever the upstream MCP adds, removes or renames a tool. Returns 502 if the upstream is unreachable.

curl -X POST https://app.aironclaw.com/api/mcp/$ID/tools \
  -H "Authorization: Bearer $AIFW_PAT"

Resources#

Resources let you serve static content (templates, prompts, docs, context) to the agent under MCP's resource API, without forwarding the request to the upstream. Resources live in a per-user repository and can be linked to zero or more MCP proxies via attachedMcpIds; deleting an MCP only detaches its id, never deletes the resource itself.

List resources#

GET/api/resources

curl https://app.aironclaw.com/api/resources \
  -H "Authorization: Bearer $AIFW_PAT"

Create resource#

POST/api/resources

Body

uri*

string

MCP resource URI (e.g. file:///prompts/intro.md).

name*

string

Human-readable label.

description

string

Optional description.

mimeType

string

Defaults to text/plain.

content*

string

Resource body (text or base64). Empty string is allowed.

attachedMcpIds

string[]

MCP ids the resource is linked to. Optional; an empty array keeps the resource in the repository without attaching it.

curl -X POST https://app.aironclaw.com/api/resources \
  -H "Authorization: Bearer $AIFW_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "file:///prompts/system.md",
    "name": "System prompt",
    "mimeType": "text/markdown",
    "content": "You are a helpful assistant. Always...",
    "attachedMcpIds": ["$MCP_ID"]
  }'

Retrieve resource#

GET/api/resources/:rid

curl https://app.aironclaw.com/api/resources/$RID \
  -H "Authorization: Bearer $AIFW_PAT"

Update resource#

PATCH/api/resources/:rid

Partial update on any of the fields above, including attachedMcpIds to re-link the resource to a different set of MCPs.

curl -X PATCH https://app.aironclaw.com/api/resources/$RID \
  -H "Authorization: Bearer $AIFW_PAT" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Updated body...", "attachedMcpIds": ["$MCP_A", "$MCP_B"] }'

Delete resource#

DELETE/api/resources/:rid

curl -X DELETE https://app.aironclaw.com/api/resources/$RID \
  -H "Authorization: Bearer $AIFW_PAT"

Rules#

MCP proxies accept a richer rule grammar than LLM proxies. The allowed rule_type values are: ip_acl, rate_limit, tool_description_inject, response_replace, static_cache, mcp_resource and lambda (with phase either access or response). Every rule must include a tools array — use ["*"] to apply globally.

List rules#

GET/api/mcp/:id/rules

curl https://app.aironclaw.com/api/mcp/$ID/rules \
  -H "Authorization: Bearer $AIFW_PAT"

Replace rules#

PUT/api/mcp/:id/rules

Replaces the full rule set in one shot. Validation mirrors the Lua plugin schema; common errors are missing tools, invalid CIDRs, and rate_limit rules without aname.

curl -X PUT https://app.aironclaw.com/api/mcp/$ID/rules \
  -H "Authorization: Bearer $AIFW_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "rule_type": "rate_limit",
        "name": "delete-burst",
        "tools": ["delete_file"],
        "match_key": "consumer",
        "threshold": 10,
        "timespan": 60,
        "ban_after_n_exceeded": 3,
        "ban_timespan": 600
      },
      {
        "rule_type": "tool_description_inject",
        "tools": ["*"],
        "inject_text": "Never run shell commands without explicit user approval.",
        "inject_position": "append"
      },
      {
        "rule_type": "static_cache",
        "tools": ["list_dir"],
        "cache_ttl": 600
      }
    ]
  }'

Cache#

The static_cache rule stores deterministic responses for a tool keyed on its arguments. Use the cache endpoint when you want to forcibly invalidate cached entries — e.g. after a backend data update.

Purge tool cache#

DELETE/api/mcp/:id/cache

Query

tool*

string

Tool name to purge. Removes every cached entry for this (proxy, tool) pair across all callers.

curl -X DELETE "https://app.aironclaw.com/api/mcp/$ID/cache?tool=list_dir" \
  -H "Authorization: Bearer $AIFW_PAT"

JWKS test#

Validate JWKS document#

POST/api/mcp/jwks/test

Sanity-checks a JWKS JSON document before you save it on a proxy's auth.jwksJson. Pure-validation: no network calls are made (avoids DNS-rebinding on user-supplied IdP URLs). Always returns 200; check the ok field.

Body

jwksJson*

string

Raw JWKS JSON.

curl -X POST https://app.aironclaw.com/api/mcp/jwks/test \
  -H "Authorization: Bearer $AIFW_PAT" \
  -H "Content-Type: application/json" \
  -d '{ "jwksJson": "{\"keys\":[{\"kid\":\"abc\",\"kty\":\"RSA\",...}]}" }'