STOA Learn

Training · Controlling API Access with STOA

Module 2 of 2 · Free access

Understand which actions an AI agent is allowed to execute

AI Agents: Which Tools Can They Run?

Objective. Separate the tools an AI agent can see in the catalogue from those it is allowed to execute, and check how denials surface across channels.

View the verified details

MCP Tool Policies, Tool Execution, and the /health/ready Probe. Observe how a signed policy affects the /health/ready probe and execution of two MCP tools on the STOA Gateway and Keycloak bench.

Module guide · Quick guide

Your goal in this module (20 min)

Replay the lab tool calls and read the gateway readiness probe after a signed policy loads.

Excerpt from the recorded trace Local MCP bench · /mcp/tools/call: allowed call, HTTP 200. Policy denies the call, HTTP 403.
View the verified details

Module 2 guide: real gateway, lab CP provider, and capture provenance

This second module continues the Helios case, from REST route access to MCP tool execution.

STOA Gateway (639e8b9a) and Keycloak (26.5.3) are real; in Compose, the entire control-plane service is replaced by an announced lab CP provider (policy_fixture.py: JWS signing, /health, and three minimal discovery routes).

The responses come from Python urllib captures of the HTTP status and body. The curl -w commands are reproduction equivalents. The 17-tool list is shown as a filtered excerpt.

The case · fictional company

Helios Distribution opens a read MCP tool while blocking a restricted action

Building on its first API route, Helios Distribution wants to allow a read tool for an AI agent while strictly blocking a sensitive operation.

View the verified details

After validating its first REST route in Module 1, Helios Distribution wants to expose an allowed MCP tool (ping-api-0) and block a second tool (ping-api-1), while wiring an orchestrator to GET /health/ready.

At the same commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913, stoa-gateway requests an Ed25519-signed JWS artifact at GET /v1/tenants/quickstart/tool-permissions/artifact, and that request returned HTTP 405 Method Not Allowed in the test with the pinned control-plane-api:1.14.1 image.

Without modifying stoa-gateway or Keycloak (both 100% real), the team replaces the control-plane service in Compose with an identified lab CP provider (policy_fixture.py: JWS signing, /health, and minimal discovery responses) without qualifying the production Control Plane.

Around the table, each stakeholder asks the question of their role.

  • Claire, CIO If /health/ready returns 200 and the agent sees the tool in the list, what proves active blocking and what caveat comes with the lab CP provider?
  • Mehdi, API Project Lead What exact acceptance criteria should I write for /health/ready, POST /mcp/tools/list, and both call routes (/mcp/tools/call and JSON-RPC /mcp)?
  • Nadia, Security Architect How does stoa-gateway authenticate via private_key_jwt (RSA) and verify the Ed25519 JWS against pinned JWKS keys, what does /health/ready check, and why does JSON-RPC return HTTP 200?
  • Lucas, Platform Engineer Which STOA_POLICY_* variables, payloads, and isolated runner (tools/run-lab-m2.sh) reproduce 503 -> 200, the 17-tool list, and the 403 / -32001 denials?

Fictional company. The case illustrates a realistic API exposure project; only the outputs captured during verified runs on the local STOA benches count as evidence (status codes and bodies reproduced untouched).

Your view

“Once GET /health/ready returns HTTP 200 READY and a tool appears in POST /mcp/tools/list, that tool is authorized for execution.”

Rather agree

Needs nuance. Common pitfall: /health/ready checks configured CP/OIDC health and attests in particular that a policy is available, while POST /mcp/tools/list returns every registered tool — including denied ones.

Rather disagree

The trial backs you up. Correct: ping-api-1 appears in the HTTP 200 response from POST /mcp/tools/list, yet its execution is rejected by the gateway policy engine.

See what the trial shows

On the verified bench, GET /health/ready returns 200 READY and POST /mcp/tools/list includes uac:quickstart:ping-api:ping-api-1, yet calling it fails with HTTP 403 on /mcp/tools/call and JSON-RPC error -32001 under HTTP 200 on /mcp.

Lesson 1

Pinned Control Plane Image (405), Ed25519 Signed Policy, and Switching /health/ready from 503 to 200

Real traces captured on 15 November 2026

Claire, CIO Why replace control-plane with a lab provider in Compose, and what does /health/ready turning 200 actually attest?

Mehdi, API Project Lead What prerequisite separates Module 1’s 503 probe from a usable 200 /health/ready probe?

Nadia, Security Architect How do stoa-gateway, Keycloak, and the Ed25519 JWS provider interact at boot?

Lucas, Platform Engineer What does control-plane-api:1.14.1 return on /tool-permissions/artifact, and how does /health/ready react to an altered versus valid signature?

In Module 1, GET /health/ready stayed at HTTP 503 because no policy was loaded. With STOA_POLICY_BOOT_TENANTS=quickstart (commit 639e8b9a), stoa-gateway authenticates to Keycloak via private_key_jwt (RSA assertion) to obtain an access token, calls GET /v1/tenants/quickstart/tool-permissions/artifact, and verifies the Ed25519 JWS with its pinned JWKS. Let us inspect control-plane-api:1.14.1 first, then the lab CP provider.

Verified M2 Bench: Real STOA Gateway & Keycloak + Lab CP Provider
Verified M2 Bench: Real STOA Gateway & Keycloak + Lab CP ProviderFive steps: loading the Ed25519 JWS from the lab CP provider, declaring a 2-endpoint contract, listing 17 MCP tools, enforcing JWT + policy, and calling http://backend:80 only for the allowed tool.1. Signed JWS2. Contract3. tools/list4. JWT + Policy5. :80lab CP providerEd25519 JWSMCP ClientAdmin & callskeycloakRealm & servicegatewayRust 0.9.25backendnginx 1.27.5
  1. STOA Gateway authenticates to Keycloak via private_key_jwt (RSA), receives an access token, and verifies the Ed25519 JWS against its pinned JWKS: altered signature -> /health/ready 503, valid -> 200 READY.
  2. After the policy is loaded, the operator posts the ping-api contract (/ping and /blocked, both declaring backend_url http://backend:80) to POST /admin/contracts.
  3. With quickstart-caller’s token, POST /mcp/tools/list returns HTTP 200 with 17 tools, including both ping-api-0 and ping-api-1.
  4. In the captures, the signed policy is applied to calls with the quickstart tenant JWT on /mcp/tools/call and /mcp.
  5. Only ping-api-0 (allowed: true) triggers a request to root http://backend:80; ping-api-1 (allowed: false) is rejected before any upstream call.
lab CP provider Ed25519 JWS
Entire control-plane Compose service replaced by policy_fixture.py (:8890) for JWS signing, /health, and three minimal discovery responses.
MCP Client Admin & calls
Publishes the contract (/ping and /blocked), calls /mcp/tools/list, then invokes ping-api-0 and ping-api-1 over plain HTTP and JSON-RPC.
keycloak Realm & service
Real Keycloak 26.5.3: authenticates the gateway via private_key_jwt (RSA assertion) to issue its access token, and issues quickstart-caller’s client_credentials token.
gateway Rust 0.9.25
Real STOA Gateway: verifies the Ed25519 JWS against pinned JWKS keys, checks CP/OIDC health + policy state on /health/ready (200), and filters every tool.
backend nginx 1.27.5
Upstream backend_url http://backend:80: called at its root by ping-api-0 (allowed), never reached by ping-api-1 (denied).

Your prediction

On the original quickstart stack, what does pinned control-plane-api:1.14.1 return on GET /v1/tenants/quickstart/tool-permissions/artifact?

HTTP 200 with a signed Ed25519 JWS token.

Not quite. No: that signed-artifact export route is absent from control-plane-api:1.14.1.

HTTP 405 with {"detail":"Method Not Allowed"} (the pinned image’s OpenAPI does not expose /tool-permissions/artifact).

Correct. Correct: this measured gap on the unmodified image explains replacing the control-plane service with an identified lab CP provider.

HTTP 500 caused by PostgreSQL.

Not quite. No: the pinned control-plane-api:1.14.1 image returned 200 on /health and 405 on the artifact request.

Reveal the recorded answer

Measured fact on the pinned control-plane-api:1.14.1 image: the signed-artifact route expected by stoa-gateway returns HTTP 405.

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 405
{"detail":"Method Not Allowed"}
See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X GET "http://127.0.0.1:8890/v1/tenants/quickstart/tool-permissions/artifact"

Ordering

Put the four steps that switch GET /health/ready from 503 to 200 on the verified bench into exact order:

See the verified order
  1. Start stoa-gateway with STOA_POLICY_BOOT_TENANTS=quickstart, the pinned Ed25519 JWKS (STOA_POLICY_TRUST_JWKS_FILE), and its RSA client authentication key for private_key_jwt. The gateway needs the boot tenant, Ed25519 trust anchor, and OIDC service identity.
  2. Initially serve an altered-signature JWS from the lab CP provider: stoa-gateway rejects the signature and keeps /health/ready at HTTP 503. This negative check verifies via readiness that Ed25519 signatures are genuinely enforced.
  3. Switch the lab CP provider to a valid Ed25519 signature (typ: stoa-tool-policy+jws, aud: stoa-gateway, ping-api-0 allowed, ping-api-1 denied). Background sync then loads the signed policy for tenant quickstart.
  4. Query GET /health/ready and observe HTTP 200 READY (configured CP/OIDC healthy and policy available). The /health/ready handler checks configured CP and OIDC health alongside boot-tenant policy availability.

Your prediction

Once the valid Ed25519 JWS is loaded (and configured CP/OIDC checks pass), what does GET /health/ready return?

HTTP 200 with body “READY”, attesting in particular that the policy is available without granting every tool.

Correct. Correct: the handler checks configured CP/OIDC health and policy state, then answers READY.

HTTP 200 listing every allowed tool in JSON.

Not quite. No: /health/ready returns only the minimal READY string.

HTTP 503 until a client calls POST /mcp.

Not quite. No: readiness depends on configured dependency health and loaded policy, not client traffic.

Reveal the recorded answer

Verified transition on real STOA Gateway: GET /health/ready switches to HTTP 200 READY.

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 200
READY
See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X GET "http://127.0.0.1:8892/health/ready"

The rule On STOA Gateway (commit 639e8b9a), GET /health/ready checks configured CP/OIDC health and policy state: switching from 503 to 200 READY attests in particular that a valid Ed25519 JWS is loaded, served here by a lab CP provider after the 405 observed on the pinned control-plane-api:1.14.1 image.

Expert detail: signature altered at first raw byte (XOR 1) and JWS claims

In policy_fixture.py, the initial mode alters the raw Ed25519 signature at its first byte (signature[0] ^ 1); that altered signature was tested via the /health/ready probe, which stays at HTTP 503 NOT READY: tool policy unavailable. The valid artifact carries alg: EdDSA, typ: stoa-tool-policy+jws, kid: cp-policy-202611-1, iss: stoa-control-plane, aud: stoa-gateway, and tenant_id: quickstart.

Full trace of GET /health/ready while the JWS signature is altered: HTTP 503 rejection.

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 503
NOT READY: tool policy unavailable
See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X GET "http://127.0.0.1:8892/health/ready"

Check what you have learned

Pick an answer: the correction appears at once.

Which description accurately states policy_fixture.py’s role in the Module 2 Compose setup?

It replaces an Ed25519 verifier missing from STOA Gateway.

Not quite. False: STOA Gateway verifies Ed25519 signatures itself.

It replaces the entire control-plane service in Compose as a lab CP provider (JWS signing after the 405 observed on the pinned image, /health, and minimal discovery responses), without qualifying the production Control Plane.

Correct. Correct: stating that the full control-plane service is replaced avoids suggesting a partial proxy of the production Control Plane.

It replaces Keycloak 26.5.3 to mint OIDC tokens.

Not quite. False: unmodified Keycloak 26.5.3 is used.

Lesson 2

Two-Endpoint Contract, POST /mcp/tools/list Discovery, and Presence of the Denied Tool

Real traces captured on 15 November 2026

Claire, CIO Why does seeing a tool in the catalogue returned to an AI agent never prove permission to run it?

Mehdi, API Project Lead How should we write test cases for POST /admin/contracts and POST /mcp/tools/list without confusing discovery and authorization?

Nadia, Security Architect How does stoa-gateway name UAC tools, and what attributes does the caller token carry during discovery?

Lucas, Platform Engineer Which tool names are generated for /ping and /blocked once the policy is already loaded, and what does the filtered excerpt of fixture-list.txt show?

The signed policy (allowing ping-api-0 and denying ping-api-1) is already loaded in memory when the operator posts the ping-api contract with two GET endpoints (/ping and /blocked) to POST /admin/contracts.

Your prediction

When the operator sends POST /admin/contracts with /ping and /blocked while the policy denying ping-api-1 is already loaded, what does STOA Gateway return?

HTTP 403, because the second endpoint is marked allowed: false in the loaded policy.

Not quite. No: MCP policy filters tool execution, not administrative contract registration.

HTTP 201 with routes_generated: 2 and tools_generated: 2 for quickstart:ping-api.

Correct. Correct: both routes and both tool descriptors (ping-api-0 and ping-api-1) are registered despite the active policy.

HTTP 201 with tools_generated: 1 after silently omitting the forbidden tool.

Not quite. No: tools_generated is 2.

Reveal the recorded answer

Full trace of POST /admin/contracts: 2 routes and 2 tools registered after prior policy load.

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 201
{"key":"quickstart:ping-api","llm_capabilities":0,"routes_generated":2,"status":"ok","tools_generated":2}
See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/admin/contracts" \
>   -H "authorization: Bearer <STOA_ADMIN_API_TOKEN>" \
>   -H 'content-type: application/json' \
>   -d '{"name":"ping-api","version":"1.0.0","tenant_id":"quickstart","status":"published","classification":"H","inboundAuth":"jwt","endpoints":[{"path":"/ping","methods":["GET"],"backend_url":"http://backend:80"},{"path":"/blocked","methods":["GET"],"backend_url":"http://backend:80"}]}'

Console · Recorded trace replay

Replay POST /mcp/tools/list without a token and then with quickstart-caller’s Keycloak token:

Confirm anonymous 401 rejection, then inspect the filtered excerpt (names and descriptions, 6 of 17 tools) from fixture-list.txt (8046 bytes).

STOA Gateway (127.0.0.1:8892) · 1. POST /mcp/tools/list without token
View captured response

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 401
{"error":"unauthorized","message":"Missing Authorization header"}

Full HTTP 401 body: {"error":"unauthorized","message":"Missing Authorization header"}.

See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/list" \
>   -H 'content-type: application/json' \
>   -d '{}'
STOA Gateway (127.0.0.1:8892) · 2. POST /mcp/tools/list with valid token
View captured response

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 200
# fixture-list.txt (filtered excerpt: name + description only, 6 of 17 tools, 8046 bytes)
{"name":"stoa_platform_health","description":"Health check all platform components (Gateway, Keycloak, Database, Kafka)"}
{"name":"stoa_tools","description":"Tool discovery: list, schema, search"}
{"name":"uac:quickstart:ping-api:ping-api-0","description":"GET /ping — ping-api [quickstart]"}
{"name":"uac:quickstart:ping-api:ping-api-1","description":"GET /blocked — ping-api [quickstart]"}
{"name":"stoa_catalog","description":"API catalog: list, get, search, versions, categories. Returns paginated API listings with filtering support."}
{"name":"stoa_uac","description":"UAC contracts: list, get, validate, sla"}
# ... +11 built-in stoa_* tools (inputSchema and outer JSON omitted)

HTTP 200 (filtered excerpt: names and descriptions of 6 out of 17 tools from fixture-list.txt, inputSchema and outer JSON omitted): uac:quickstart:ping-api:ping-api-1 is listed even though execution is denied.

See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/list" \
>   -H "authorization: Bearer <ACCESS_TOKEN>" \
>   -H 'content-type: application/json' \
>   -d '{}'

Spotting in the trace

In this filtered excerpt (names and descriptions) of POST /mcp/tools/list, click the line showing the tool forbidden by policy:

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 200
# fixture-list.txt (filtered excerpt: name + description only, 6 of 17 tools, 8046 bytes)
{"name":"stoa_platform_health","description":"Health check all platform components (Gateway, Keycloak, Database, Kafka)"}
{"name":"stoa_tools","description":"Tool discovery: list, schema, search"}
{"name":"uac:quickstart:ping-api:ping-api-0","description":"GET /ping — ping-api [quickstart]"}
{"name":"uac:quickstart:ping-api:ping-api-1","description":"GET /blocked — ping-api [quickstart]"}
{"name":"stoa_catalog","description":"API catalog: list, get, search, versions, categories. Returns paginated API listings with filtering support."}
{"name":"stoa_uac","description":"UAC contracts: list, get, validate, sla"}
# ... +11 built-in stoa_* tools (inputSchema and outer JSON omitted)
See the target line

{"name":"uac:quickstart:ping-api:ping-api-1","description":"GET /blocked — ping-api [quickstart]"} This entry shows uac:quickstart:ping-api:ping-api-1 (GET /blocked) returned under HTTP 200 despite allowed: false in the tenant policy.

  • These lines note HTTP 200 and the filtered nature of the excerpt (names and descriptions, 6 of 17 tools).
  • Those are four built-in stoa_* gateway tools; check the uac:quickstart:ping-api:* entries.
  • ping-api-0 maps to GET /ping (allowed); check the next line.
See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/list" \
>   -H "authorization: Bearer <ACCESS_TOKEN>" \
>   -H 'content-type: application/json' \
>   -d '{}'

The rule Neither /health/ready at 200 nor a tool appearing in POST /mcp/tools/list (17 tools returned in HTTP 200) grants execution permission: at this commit, the list includes the denied tool.

Expert detail: load order, viewer + stoa:read token, and gateway log codes

Three reading facts matter on this bench: (1) the JWS policy is loaded before POST /admin/contracts; (2) fixture-list.txt (8046 bytes) holds 17 tools (15 built-in stoa_* tools + ping-api-0 and ping-api-1); (3) quickstart-caller’s token carries both realm role viewer and scope stoa:read — the test does not causally separate those two attributes, does not test missing scope or a second tenant, and a permission_absent code in gateway logs can accompany an allowed: false entry.

Check what you have learned

Pick an answer: the correction appears at once.

What happens when an authenticated client calls POST /mcp/tools/list while ping-api-1 is marked allowed: false in the loaded policy?

POST /mcp/tools/list returns HTTP 200 with 17 tools including both ping-api-0 and ping-api-1; policy filtering applies at execution time.

Correct. Correct: tool listing does not prune the denied tool at verified commit 639e8b9a.

POST /mcp/tools/list automatically removes ping-api-1.

Not quite. False: uac:quickstart:ping-api:ping-api-1 is present in fixture-list.txt.

POST /mcp/tools/list answers without requiring an Authorization header.

Not quite. False: without a Bearer token, the route returns HTTP 401.

What does quickstart-caller’s token prove regarding OIDC roles and scopes in this run?

It carries both role viewer and scope=stoa:read: the run validates that nominal pair without causally separating them or testing missing scope or cross-tenant isolation.

Correct. Correct: strict trace reading never attributes behaviour to a single unseparated attribute without a dedicated negative test.

It proves full isolation across two distinct tenants.

Not quite. False: only tenant quickstart is exercised in this module.

Lesson 3

Tool Execution: HTTP 403 on /mcp/tools/call Versus JSON-RPC -32001 Under HTTP 200

Real traces captured on 15 November 2026

Claire, CIO What blind spot do we create if MCP monitoring only tracks HTTP 200 status rates on JSON-RPC?

Mehdi, API Project Lead How should acceptance criteria distinguish denial on POST /mcp/tools/call from denial on POST /mcp?

Nadia, Security Architect Which exact upstream URL does the dynamic tool invoke, and how does each MCP route wrap a denial?

Lucas, Platform Engineer What HTTP statuses and JSON bodies return for ping-api-0 and ping-api-1 on /mcp/tools/call versus /mcp?

STOA Gateway exposes plain HTTP POST /mcp/tools/call and JSON-RPC 2.0 POST /mcp (tools/call). Compare all four full responses below for ping-api-0 (allowed) and ping-api-1 (denied).

Console · Recorded trace replay

Compare allowed (ping-api-0) and denied (ping-api-1) calls across both MCP interfaces:

Switch the target (POST /mcp/tools/call then POST /mcp) and scenario to inspect all four untouched bodies.

POST /mcp/tools/call (plain HTTP) · 1. Tool allowed by policy · uac:quickstart:ping-api:ping-api-0
View captured response

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 200
{"content":[{"type":"text","text":"<!DOCTYPE html>\n<html>\n<head>\n<title>Welcome to nginx!</title>\n<style>\nhtml { color-scheme: light dark; }\nbody { width: 35em; margin: 0 auto;\nfont-family: Tahoma, Verdana, Arial, sans-serif; }\n</style>\n</head>\n<body>\n<h1>Welcome to nginx!</h1>\n<p>If you see this page, the nginx web server is successfully installed and\nworking. Further configuration is required.</p>\n\n<p>For online documentation and support please refer to\n<a href=\"http://nginx.org/\">nginx.org</a>.<br/>\nCommercial support is available at\n<a href=\"http://nginx.com/\">nginx.com</a>.</p>\n\n<p><em>Thank you for using nginx.</em></p>\n</body>\n</html>\n"}]}

Full HTTP 200: the dynamic tool calls the exact backend_url http://backend:80 (its root, without appending the contract route path /ping) and returns “Welcome to nginx!”.

See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/call" \
>   -H "authorization: Bearer <ACCESS_TOKEN>" \
>   -H 'content-type: application/json' \
>   -d '{"name":"uac:quickstart:ping-api:ping-api-0","arguments":{}}'
POST /mcp/tools/call (plain HTTP) · 2. Tool denied by policy · uac:quickstart:ping-api:ping-api-1
View captured response

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 403
{"content":[{"type":"text","text":"Tool 'uac:quickstart:ping-api:ping-api-1' is not allowed for this tenant"}],"isError":true}

Full HTTP 403 with isError: true and “Tool 'uac:quickstart:ping-api:ping-api-1' is not allowed for this tenant”. Zero requests reach http://backend:80.

See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/call" \
>   -H "authorization: Bearer <ACCESS_TOKEN>" \
>   -H 'content-type: application/json' \
>   -d '{"name":"uac:quickstart:ping-api:ping-api-1","arguments":{}}'
POST /mcp (JSON-RPC 2.0) · 1. Tool allowed by policy · uac:quickstart:ping-api:ping-api-0
View captured response

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 200
{"jsonrpc":"2.0","result":{"content":[{"text":"<!DOCTYPE html>\n<html>\n<head>\n<title>Welcome to nginx!</title>\n<style>\nhtml { color-scheme: light dark; }\nbody { width: 35em; margin: 0 auto;\nfont-family: Tahoma, Verdana, Arial, sans-serif; }\n</style>\n</head>\n<body>\n<h1>Welcome to nginx!</h1>\n<p>If you see this page, the nginx web server is successfully installed and\nworking. Further configuration is required.</p>\n\n<p>For online documentation and support please refer to\n<a href=\"http://nginx.org/\">nginx.org</a>.<br/>\nCommercial support is available at\n<a href=\"http://nginx.com/\">nginx.com</a>.</p>\n\n<p><em>Thank you for using nginx.</em></p>\n</body>\n</html>\n","type":"text"}]},"id":2}

Full HTTP 200: the JSON-RPC object (id: 2) returns in result.content the “Welcome to nginx!” HTML from http://backend:80.

See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp" \
>   -H "authorization: Bearer <ACCESS_TOKEN>" \
>   -H 'content-type: application/json' \
>   -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"uac:quickstart:ping-api:ping-api-0","arguments":{}}}'
POST /mcp (JSON-RPC 2.0) · 2. Tool denied by policy · uac:quickstart:ping-api:ping-api-1
View captured response

Python urllib capture from 15 November 2026 (status and body, no headers)

HTTP 200
{"jsonrpc":"2.0","error":{"code":-32001,"message":"Tool call rejected","data":{"httpStatus":403,"result":{"content":[{"text":"Tool 'uac:quickstart:ping-api:ping-api-1' is not allowed for this tenant","type":"text"}],"isError":true}}},"id":3}

Key subtlety: HTTP transport returns HTTP 200, while the JSON-RPC body (id: 3) carries error.code = -32001 (“Tool call rejected”) and error.data.httpStatus = 403 with isError: true.

See equivalent curl command (reproduction with -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp" \
>   -H "authorization: Bearer <ACCESS_TOKEN>" \
>   -H 'content-type: application/json' \
>   -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"uac:quickstart:ping-api:ping-api-1","arguments":{}}}'

Classifying

Match each verified behaviour to its STOA Gateway interface:

  1. Signals policy denial directly at transport level with status HTTP 403 and isError: true.
    See the answer

    POST /mcp/tools/call (plain HTTP route). On /mcp/tools/call, denying ping-api-1 directly returns HTTP 403.

  2. Returns HTTP 200 transport while placing the denial in error.code = -32001 and error.data.httpStatus = 403.
    See the answer

    POST /mcp (JSON-RPC 2.0 envelope). In JSON-RPC 2.0 on POST /mcp, checking HTTP 200 alone misses the -32001 rejection.

  3. Checks configured CP/OIDC health and attests in particular that the policy is available by returning 200 READY, without allowing all tools.
    See the answer

    GET /health/ready (orchestration probe). READY confirms dependency health and loaded policy, while each tool remains filtered per call.

  4. Returns on an allowed call (id: 2) a JSON-RPC envelope carrying result.content.
    See the answer

    POST /mcp (JSON-RPC 2.0 envelope). An allowed JSON-RPC call returns HTTP 200 with result.content.

The rule Tool denial returns HTTP 403 on POST /mcp/tools/call but HTTP 200 with error.code = -32001 (data.httpStatus = 403) on POST /mcp: always inspect the JSON-RPC body without extrapolating beyond the single tested tenant.

Expert detail: upstream target http://backend:80, error -32001, and out-of-scope limits

The dynamic tool calls the contract’s exact backend_url (http://backend:80, i.e. its root) rather than the REST route path /ping. On POST /mcp denial, fixture-rpc-denied.txt shows error.code = -32001 and error.data.httpStatus = 403 under HTTP 200. Unproved boundaries remain: the production Control Plane, cross-tenant isolation, missing-scope checks, and TTL expiry.

Check what you have learned

Pick an answer: the correction appears at once.

A test sends tools/call for ping-api-1 to POST /mcp (JSON-RPC) and checks only “HTTP status == 200”. What false conclusion does it reach?

It treats the call as allowed even though the gateway rejected it with error.code = -32001 and error.data.httpStatus = 403 under HTTP 200.

Correct. Correct: on POST /mcp, application rejection sits inside the JSON-RPC error object over HTTP 200.

It observes an HTTP 403 status identical to POST /mcp/tools/call.

Not quite. No: only POST /mcp/tools/call returns HTTP 403 at transport level.

It receives HTML from http://backend:80 with a warning.

Not quite. No: the rejected call never reaches the backend.

Decision case

Claire, CIO Before opening MCP tools in Helios Distribution’s pilot, which factual decisions do you sign off?

Mehdi, API Project Lead For the pilot MCP acceptance plan, which proved requirements do you record?

Nadia, Security Architect During the MCP architecture review, which safeguards and scope caveats do you log?

Lucas, Platform Engineer For automated checks on stoa-gateway, which assertions do you enforce together?

Several answers count. Pick them all.

Require proof of both allowed and denied execution (ping-api-0 in 200, ping-api-1 rejected), never inferring rights from POST /mcp/tools/list or /health/ready 200.

Worth keeping. Essential: the list includes the forbidden tool, and READY attests in particular that a policy is available without allowing everything.

On POST /mcp (JSON-RPC 2.0), assert absence of error (and expect -32001 / data.httpStatus: 403 on negative tests) rather than HTTP 200 alone.

Worth keeping. Critical: JSON-RPC rejection returns under HTTP 200.

Claim that control-plane-api:1.14.1 natively serves signed artifacts and that cross-tenant isolation is proved.

To set aside. False: the artifact request returned 405 on the pinned image and the second lab setup uses a lab Control Plane provider and only quickstart is tested.

Document replacing control-plane with the lab CP provider and schedule dedicated gates for the target Control Plane and multi-tenant isolation.

Worth keeping. Sound engineering: separating real gateway/Keycloak proofs from the lab CP provider prevents blind spots.

Decision case

Claire, CIO A team reports GET /health/ready stuck at 503 on boot with STOA_POLICY_BOOT_TENANTS=quickstart. What do you check first?

Mehdi, API Project Lead In integration, the gateway stays at 503 on /health/ready even though Keycloak is up. Which check comes first?

Nadia, Security Architect STOA Gateway keeps /health/ready at 503 during bootstrap. Which chain do you inspect?

Lucas, Platform Engineer With STOA_POLICY_BOOT_TENANTS=quickstart, /health/ready stays at 503. What do you verify?

One answer only holds. Pick it.

Check CP/OIDC health, HTTP 200 on GET /v1/tenants/quickstart/tool-permissions/artifact (not 405), pinned Ed25519 JWKS (STOA_POLICY_TRUST_JWKS_FILE), and RSA client auth (private_key_jwt).

Worth keeping. Correct: an unhealthy dependency, missing route (405), or invalid JWS signature keeps /health/ready at 503.

Switch readinessProbe to GET /health to hide the 503.

To set aside. Unsafe: that masks failed policy bootstrap.

Post contracts to POST /admin/contracts to unblock /health/ready.

To set aside. Ineffective: /health/ready does not depend on declared contracts.

The decision of the team

Helios uses the bench traces for the pilot. Acceptance criteria include the JSON-RPC outcome and tests on the target Control Plane.

What the trace proves. Python urllib captures from the bench show /health/ready changing from 503 to 200, both tools listed and the ping-api-1 call denied.

Key points

  1. The lab provider supplies the Ed25519 JWS. On this bench, /health/ready returns 503 with an altered signature and 200 with a valid signature.
  2. Neither /health/ready at 200 nor a tool appearing in POST /mcp/tools/list (17 tools in HTTP 200, including uac:quickstart:ping-api:ping-api-1) grants execution permission.
  3. The allowed tool calls root http://backend:80, whereas the forbidden tool is blocked with HTTP 403 (/mcp/tools/call) or JSON-RPC error -32001 under HTTP 200 (/mcp) — without qualifying the production Control Plane, cross-tenant isolation, or TTL expiry.

Reproduce on your machine (local Docker)

Reproduce the MCP Bench with Lab CP Provider in a Fresh Folder (tools/run-lab-m2.sh)

Run an isolated local reproduction from the project root at clean commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 via tools/run-lab-m2.sh: real STOA Gateway (ephemeral personal tag) and Keycloak 26.5.3, control-plane replaced by a personal copy of policy_fixture.py, secrets in a 0700 folder deleted even on failure, never touching verification-module-2/ or references/.

Prerequisites
Active Docker Compose v2 + python3 with cryptography (ephemeral keys for the local CP provider) · Free loopback ports 127.0.0.1:8890–8892 and no active stoa-lab-m2-* project · Variable cold gateway build (5 to 15 min depending on hardware/network, ~1 min with warm cache)
Estimated time
Variable build + ~1 min MCP verification

Local verification script & checklist

bash tools/run-lab-m2.sh --prepare-only --out .lab-test/m2-prep
bash tools/run-lab-m2.sh --out .lab-test/m2-essai-1
cat .lab-test/m2-essai-1/fixture-audit.json
cat .lab-test/m2-essai-1/fixture-call-denied.txt .lab-test/m2-essai-1/fixture-rpc-denied.txt

Wrapper copying the qualified scripts from verification-module-2/ into a fresh folder with a stoa-lab-m2-* project, cleaned personal gateway tag, bounded *_TIMEOUT limits, and try/finally removal of the 0700 folder.

  1. Prepare a fresh folder without Docker first (checks clean commit, positive timeouts, and isolated copy of the CP provider and runner):
    bash tools/run-lab-m2.sh --prepare-only --out .lab-test/m2-prep
  2. Run the live bench in a new folder (checks free 127.0.0.1:8890–8892, builds personal tag <project>-gateway:639e8b9a if absent, starts Keycloak, nginx, policy_fixture.py, and STOA Gateway):
    bash tools/run-lab-m2.sh --out .lab-test/m2-essai-1
  3. Inspect fixture-audit.json (503 -> 200, contract 201, list 401/200, calls 200/403, and JSON-RPC 200/-32001) and both denial bodies:
    cat .lab-test/m2-essai-1/fixture-audit.json
    cat .lab-test/m2-essai-1/fixture-call-denied.txt .lab-test/m2-essai-1/fixture-rpc-denied.txt
  4. Confirm .runtime-fixture (0700) is gone and no stoa-lab-m2-* container remains:
    ls -la .lab-test/m2-essai-1
    cat .lab-test/m2-essai-1/remaining-containers.txt

You have succeeded if fixture-audit.json validates every expected status (503 -> 200, 201, 401, 200, 200, 403, and rpcDenied -32001/403), .runtime-fixture is deleted, logs are scrubbed of secrets/JWTs, remaining-containers.txt is empty, and verification-module-2/ is untouched.

Apply

What about you?

Ask yourself these questions about your own organisation. Your ticks and notes are neither sent nor stored: print them or copy them.

Claire, CIO

  • Do we require proof of a denied MCP tool alongside an allowed tool in every demo?
  • Do we separate what is proved on real STOA Gateway from what relies on a lab CP provider?
  • Do our MCP dashboards track JSON-RPC code -32001 rather than HTTP 200 alone?
  • Have we scheduled dedicated tests before claiming cross-tenant isolation or TTL expiry?

Mehdi, API Project Lead

  • Do acceptance criteria state that a tool listed in POST /mcp/tools/list must still be blocked on execution if denied?
  • Do test suites cover both POST /mcp/tools/call (403) and JSON-RPC POST /mcp (HTTP 200 with error.code = -32001)?
  • Is the 405 observed on the pinned control-plane-api:1.14.1 image tracked ahead of target Control Plane integration?
  • Are local ports 8890–8892 and variable Rust build times documented for engineers?

Nadia, Security Architect

  • How will we distribute the pinned Ed25519 JWKS (STOA_POLICY_TRUST_JWKS_FILE) and the gateway’s RSA key for private_key_jwt client auth?
  • Do orchestrators wire GET /health/ready with full awareness of its CP, OIDC, and policy checks?
  • Do MCP clients handle error.code = -32001 and isError: true under HTTP 200?
  • Which follow-up tests will cover a second tenant, missing scope, and TTL expiry?

Lucas, Platform Engineer

  • Do we test 503 on an altered JWS signature before validating 200 READY?
  • Do we isolate every run in stoa-lab-m2-* with a personal gateway tag and try/finally removal of the 0700 folder?
  • Do CI assertions verify both HTTP 403 on /mcp/tools/call and error.data.httpStatus == 403 on /mcp?
  • Do we verify zero tokens or private keys remain in collected logs?

End of module 2

Module 2 Wrap-Up: Signed Policies, Filtered MCP Execution, and Explicit Limits

The bench with STOA Gateway, Keycloak and the lab provider shows both readiness states and the allowed and denied calls.

  • Explain what /health/ready checks (configured CP/OIDC health and available policy in 200 READY after valid Ed25519 verification) and why Compose replaces control-plane with a lab CP provider.
  • Prove from traces that neither /health/ready at 200 nor ping-api-1 appearing in POST /mcp/tools/list (HTTP 200) authorizes its execution.
  • Verify both MCP tool denial forms: HTTP 403 on POST /mcp/tools/call and JSON-RPC error -32001 (data.httpStatus: 403) under HTTP 200 on POST /mcp.
  • Keep the production Control Plane, cross-tenant isolation, missing-scope checks, and TTL expiry strictly outside unproved claims.

Where to go next

Return to the course sheet to review the two modules. On the Expert path, bash tools/run-lab-m2.sh reproduces the lab on 127.0.0.1:8890–8892.