mcp-authz-reference
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-authz-reference
A minimal, reproducible reference for securing an MCP server with an OAuth authorization server. Keycloak is the teaching IdP; the example shows audience binding and scope × role limits on tools.
flowchart LR
CC["Claude Code<br/>client: claude-code"]
KC["Keycloak<br/>login and scopes"]
subgraph MCP["MCP server"]
CHK["Check the token<br/>signature, iss, aud<br/>then scope x role"]
end
subgraph TOOLS["Fictitious ITSM tools"]
R["read<br/>search_tickets, get_ticket"]
W["write<br/>add_comment"]
D["destructive<br/>close_ticket"]
end
CC -- "1. login with PKCE, asks for scopes" --> KC
KC -- "2. access token with aud, scope, roles" --> CC
CC -- "3. Bearer token" --> CHK
CHK -- "itsm:read" --> R
CHK -- "itsm:write and operator role" --> W
CHK -- "itsm:close and operator role" --> DAll data is fictitious. Passwords in .env.example are test-only.
Quick start
Requires Docker and Node 24.
cp .env.example .env # optional; tests and compose fall back to .env.example
docker compose up -d --wait # Keycloak 26.8.2 and the MCP server
npm ci
npm test # unit tests, no Docker needed
npm run test:e2e # real tokens from Keycloak against the container
docker compose down -vTo connect Claude Code by hand, see docs/claude-code.md.
Related MCP server: Auth0 MCP Server Demo — CRM
What this protects, and what it does not
Protected | Not protected yet |
A token issued for another MCP server is rejected ( | Sender-constrained tokens (DPoP, mTLS). A stolen bearer token works until it expires. |
Tools the caller may not use are not listed, and are checked again on every call. A tool needs both the scope (what the client may do) and the role (what the user may do). | Malicious MCP servers. This repository protects one server, not the client from a bad one. |
The server does not publish internal hostnames. Authorization server metadata is fetched from the issuer, not served by the MCP server. | Prompt-injection-driven destructive calls. The three tiers only reduce the damage: a client with the |
Revocation of tokens already issued. A token stays valid until it expires. | |
No | |
The Keycloak workaround binds |
The three tool tiers:
Tier | Tools | Needs scope | Needs role |
read |
|
|
|
write |
|
|
|
destructive |
|
|
|
Test users: alice has the operator role, bob has the viewer role. The policy is a pure function in
src/authz/policy.ts.
Design notes
The server is IdP-neutral. It does standard JWT checks (JWKS,
iss,aud,exp) and reads scopes fromscopeand roles from a top-levelrolesclaim. Everything Keycloak-specific (realm, audience mappers, therolesmapper) lives inkeycloak/. The realm file is generated bykeycloak/setup-realm.sh; signing keys are stripped from it.Audience binding. Resource indicators (RFC 8707) are only experimental in Keycloak 26.8.2 (
--features=resource-indicators), so the default setup does not rely on them; the verification memo compares the flag on and off. Instead eachitsm:*scope has an audience mapper that putshttp://localhost:3000/mcpintoaud, so asking for the scope is what puts the resource in the token. A token without anyitsm:*scope has no matchingaudand is rejected with 401.MCP protocol version
2025-11-25. SDK 1.32.2 negotiates up to that version. The authorization requirements checked here (RFC 9728 protected resource metadata, audience validation) are the same as in the 2026-07-28 revision; the version moves up when the SDK supports it.Stateless server. Every request gets a fresh server and transport; there are no sessions.
Test-only things.
lab-testeris a client with the password grant (ROPC), used only so the e2e tests can get tokens without a browser. OAuth 2.1 removes this grant; do not copy it.The passwords in
.env.exampleand the Keycloak admin default incompose.yamlare for local use only.
Verified on
Date | What | Keycloak | MCP SDK | Node | Result |
2026-11-18 | Unit tests and e2e tests ( | 26.8.2 | 1.32.2 | 24 | Passed |
2026-11-18 | Claude Code 2.1.327 manual walkthrough | 26.8.2 | 1.32.2 | 24 | Passed (see below) |
Claude Code walkthrough (2026-11-18): with the pre-registered claude-code client and oauth.scopes
set per entry, alice saw 2 tools (itsm:read) and 4 tools (all scopes); bob saw 2 tools with both.
The server log confirmed azp = claude-code and that the granted scopes followed each entry's
setting. Two observations: Claude Code also requested offline_access (a refresh token), and it
first sent server/discover (a 2026-07-28 method) before falling back to initialize.
More: docs/claude-code.md · resource indicators verification memo
License
Apache-2.0. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Demo banking MCP server: accounts, transactions and payments. OAuth 2.1 with DPoP.
Helpdesk tickets from your AI: find, reply, take, hold, complete — within your own role. OAuth.
OAuth 2.1 short-link tools for AI agents with scoped tokens, approvals, audit logs, and revocation.
Read tickets, users, orgs, macros and satisfaction ratings; create, update and comment on tickets.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceDemonstrates MCP remote authentication boundary with OAuth 2.0, Keycloak token introspection, audience and scope validation, and protected tools.1-
- FlicenseNot gradedqualityCmaintenanceA secure MCP server for CRM operations (contacts and deals) with Auth0 OIDC authentication, role-based access control (sales-rep read-only vs sales-manager full access), and on-behalf-of token exchange.-
- -licenseNot gradedqualityFmaintenanceA minimal remote (Streamable HTTP) MCP server that is an OAuth 2.1 resource server, demonstrating the MCP authorization spec with token validation and audience checks.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to connect over stateless Streamable HTTP and authenticate through an existing OAuth 2.1 / OpenID Connect authorization server, with JWT validation, per-tool scope enforcement, and step-up challenges. It ships example scoped tools for reading and creating per-user notes that developers replace with their own.MIT