Gateway Overview

The PBAC Gateway is a Policy Enforcement Point (PEP) that sits between MCP clients (Claude Code, AI agents) and backend services. It enforces authorization on every tool call by delegating to the PBAC Authorization Server.

The gateway has no policy logic. It calls the AS /introspect endpoint, gets back yes/no plus obligations, and enforces the result.

MCP client (Claude Code)
    |
    | POST /mcp  (Bearer token, JSON-RPC 2.0)
    v
+------------------+
|   MCP Gateway    |  1. Validate token via /introspect
|   (PEP)          |  2. Enforce scopes + obligations
+--------+---------+  3. Route to protected resource
         |
    +----+----+
    |         |
    v         v
PBAC AS     Your backend APIs
(PDP)       (Drive, Jira, Slack, etc.)

---

What a gateway protects

A single gateway fronts one or more backends — your own APIs, SaaS providers, databases — and exposes their operations as MCP tools, each with a required scope.

Concept	What it is
Backend	An HTTP API the gateway sits in front of (e.g. your GitHub, your internal Postgres, a SaaS app)
Tool	A named MCP operation on that backend (e.g. github_list_issues, db_query)
Scope	The OAuth scope the token must carry for the gateway to forward the call (e.g. github:issues:read, db:read)

You define backends, tools, and scopes through the dashboard's Gateway tab.

---

Request flow

Every tool call follows the same path — this is what "policy on every call" means in practice:

1. The MCP client sends POST /mcp with a bearer token.
2. The gateway looks up the scope required by the requested tool.
3. The gateway calls the AS /introspect with the token, the required scope, and the resource context.
4. OPA evaluates policy and returns active: true or active: false plus any obligations.
5. If authorized, the gateway forwards the call to the backend.
6. The backend's response is returned to the client.

Every step is logged to the instance's audit trail: user, agent, tool, scope, decision, timestamp.

---

Security model

• Fail-closed everywhere: missing token → 401; invalid/inactive token → 403; AS unreachable → 403; unknown obligation → 403
• Per-route scope enforcement: each tool and resource declares its required scope
• Resource context: resource type and ID passed to introspection for fine-grained policies
• Protocol in context: introspection includes "protocol": "mcp" or "protocol": "http" for OPA
• WWW-Authenticate headers: RFC 6750 with resource_metadata URL for MCP client step-up flows

Fail-closed details

If the AS is unreachable or returns an error during introspection, the request is denied. Every path leads to 403 — never "allow on error." This prevents authorization bypass during an AS outage.

Condition	Result
Connection error or timeout fetching the gateway's RS token	Deny (403)
Connection error or timeout calling /introspect	Deny (403)
Non-200 from /introspect	Deny (403)
active: false in the introspection response	Deny (403)

---

Health and diagnostics

Health endpoint — the gateway exposes a cheap, no-auth health probe via its protected-resource metadata:

curl -sf https://<your-gateway>.policyarc.com/.well-known/oauth-protected-resource

HTTP 200 means the gateway is up and its AS is reachable. The dashboard runs this check automatically and surfaces the result on the Gateway tab.

Dashboard signals — the Instance page surfaces:

• Gateway health tile (green / yellow / red)
• Per-call audit log with scope, decision, timestamp
• Live logs for the gateway container

For troubleshooting specific failure modes, contact us.

---

Discovery endpoints

The gateway exposes standard OAuth discovery so MCP clients can find the AS automatically:

Endpoint	Standard	Purpose
GET /.well-known/oauth-protected-resource	RFC 9728	Resource indicator, AS URLs, supported scopes
GET /.well-known/oauth-authorization-server	RFC 8414	Proxies the AS metadata document

---

Next steps

• Start Here — dashboard onboarding: create an instance, provision a gateway, write policy, test
• MCP Protocol Flows — How clients discover, authenticate, and interact