mcp-oidc-proxy
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-oidc-proxy Call the protected hello_world tool"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-oidc-proxy
Local prototype for exercising FastMCP OIDCProxy against a demo OIDC provider.
The repository packages two cooperating apps:
Auth server — a NanoIDP demo OIDC provider on
http://127.0.0.1:9000MCP server — a FastMCP HTTP server on
http://127.0.0.1:8000with a single protectedhello_worldtool
Together they prove that an MCP client can authenticate through OIDCProxy, call a protected tool, and be rejected when unauthenticated.
Prerequisites
Python 3.14+
Related MCP server: mcp-keycloak
Setup
uv sync
cp .env.example .envDemo client credentials are committed in config/ with defaults matching .env.example. Both servers read the same environment variable names so credentials stay aligned.
Running locally
Run each server in its own terminal from the repository root:
uv run python -m nanoidpuv run launch-mcpThe auth server listens on http://127.0.0.1:9000 and exposes standard OIDC discovery, JWKS, authorize, and token endpoints. NanoIDP reads committed configuration from ./config.
Demo-only warning: the auth server exists solely to validate the OIDC proxy flow during local development and testing. It is not a production identity provider.
Demo credentials:
User:
admin/adminOAuth client: values from
.env.example(mcp-proxy-client/dev-secret)
Tests
uv run pytest # unit/integration tests (smoke excluded)
uv run pytest -m smoke # end-to-end smoke tests (spawns both servers)Smoke tests launch real subprocesses for NanoIDP and the MCP server, complete the OAuth flow with FastMCP HeadlessOAuth, and verify both authenticated and unauthenticated tool calls.
Available Tools
26 toolsclear_audit_logC
Clear the audit log
Inputs: no named parameters.
create_clientB
Create a new OAuth client
Inputs: client_id (required), client_secret (required), description, footer_color, +7 more.
create_persona_userA
Create a password-less user for persona login mode (local dev/testing convenience, 'login.mode: persona' in settings). The user can only authenticate by identity selection in the interactive login UI - never via password-mode login or the OAuth password grant. To keep 'create_user' unambiguous (always creates a normal, password-protected user), this is a separate tool rather than an optional password on create_user.
Inputs: username (required), email, roles, groups, +6 more.
create_userC
Create a new user in NanoIDP
Inputs: password (required), username (required), email, roles, +7 more.
decode_tokenA
Decode and display the claims in a JWT token (without signature verification)
Inputs: token (required).
delete_clientB
Delete an OAuth client
Inputs: client_id (required).
delete_userC
Delete a user from NanoIDP
Inputs: username (required).
generate_tokenB
Generate an OAuth2 access token for a user
Inputs: username (required), scope, extra_claims, id_token_claims, +2 more.
get_audit_logB
Get audit log entries (what the IdP recorded: token requests, logins, SAML flows)
Inputs: limit, username, event_type.
get_audit_statsA
Get audit log statistics (event counts by type/status)
Inputs: no named parameters.
get_clientB
Get details of a specific OAuth client
Inputs: client_id (required).
get_jwksA
Get JSON Web Key Set for token verification
Inputs: no named parameters.
get_keys_infoB
Get information about the signing keys (active kid, previous keys)
Inputs: no named parameters.
get_oidc_discoveryA
Get OIDC discovery document (/.well-known/openid-configuration)
Inputs: no named parameters.
get_settingsB
Get current NanoIDP settings
Inputs: no named parameters.
get_userC
Get details of a specific user
Inputs: username (required).
list_clientsA
List all configured OAuth clients
Inputs: no named parameters.
list_usersA
List all configured users in NanoIDP
Inputs: no named parameters.
reload_configB
Reload configuration from files
Inputs: no named parameters.
rotate_keysA
Rotate the signing keys: the active key moves to 'previous' (still valid for verification) and a new active key is generated - useful to test clients' JWKS refresh handling
Inputs: no named parameters.
save_configA
Save current configuration to YAML files (persists changes made via create/update tools without persist=True support). Writes users.yaml and settings.yaml as one coordinated, conflict-checked save (#229) and then refreshes the running configuration from what was just written. To refuse the save if another writer (the web UI, another agent, a second nanoidp process on the same directory) changed a file since you read it, pass the expected_users_revision / expected_settings_revision a read tool handed back (list_users and get_user carry users_revision; list_clients, get_client and get_settings carry settings_revision; reload_config and a successful save_config carry both). save_config always writes both files, so there are exactly two modes: omitting both revisions keeps today's unconditional last-write-wins, and supplying either makes the WHOLE save conflict-checked - the omitted revision defaults to the one this runtime was loaded from, so a save guarded on users.yaml cannot silently overwrite a settings.yaml another writer changed, or vice versa. A failure response's 'kind' distinguishes four outcomes: 'conflict' (nothing was written - a supplied revision was stale; call reload_config, reapply your change on the fresh state and save with the revisions from its response), 'lock_timeout' or 'lock_unsupported' (nothing was written either - the write never started; lock_timeout is worth retrying, lock_unsupported means this config directory's filesystem does not support advisory locks and will not succeed on retry), a hook's own 'kind' under hooks.strict (both files ARE written; only the mirror push failed), or 'reload_after_save' (both files ARE written but the runtime could not adopt them - do not retry expecting a different result, the file on disk is authoritative).
Inputs: expected_users_revision, expected_settings_revision.
update_clientC
Update an existing OAuth client
Inputs: client_id (required), description, footer_color, header_color, +7 more.
update_settingsA
Update NanoIDP settings (issuer, audience, token expiry, SAML options, etc.). hooks: and plugins: (#185) are YAML-only, like secret_key and require_ui_login: they are reported by get_settings but cannot be changed here, since a command editable through the surface it observes would be a remote-execution primitive.
Inputs: issuer, audience, login_mode, require_pkce, +18 more.
update_userC
Update an existing user's attributes
Inputs: username (required), email, roles, groups, +6 more.
validate_configA
Validate the running configuration directory (settings.yaml, users.yaml, bootstrap.yaml): unknown keys as warnings, wrong types and refused values as errors. settings.yaml and users.yaml findings are what a startup or the next reload would hit; bootstrap.yaml findings are what would stop the NEXT startup (the bootstrap surface loads at startup only). Read-only and inert: it re-reads the files through the same loaders, runs no hook and loads no plugin. 'valid' is false on any error, and on a warning too under strict mode, which is when a start would refuse. 'strict' defaults to this server's effective validation mode; pass it explicitly to override.
Inputs: strict.
verify_tokenA
Verify a JWT token's signature and expiration
Inputs: token (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Every tool targets a distinct resource and action with clear descriptions that explicitly disambiguate similar pairs (e.g., decode_token vs verify_token, create_user vs create_persona_user). No two tools have overlapping purposes.
All tool names follow a consistent verb_noun pattern in snake_case, using standard verbs like get, list, create, update, delete, rotate, and save. Minor variations (list_users vs get_user) reflect conventional list-vs-fetch semantics.
At 26 tools, the server exceeds the 25-tool threshold for 'too many' defined in the rubric. While the broad scope of an OIDC proxy justifies many operations, the count is above the well-scoped range and may overwhelm an agent with options.
The tool set provides comprehensive coverage: CRUD for users and clients, token generation and verification, key management, audit logging, and config lifecycle (validate, reload, save). Minor gaps exist (e.g., no granular audit log deletion or token introspection), but they do not create dead ends.
Maintenance
Related MCP Connectors
One OAuth connector for your team's remote MCP servers, with Tool Packs, guardrails and logs.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Prove end users to agents and apps: login-links, OIDC clients, and API keys over remote MCP
Prove end users to agents and apps: login-links, OIDC clients, and API keys over remote MCP
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 gradedqualityDmaintenanceEnables secure MCP tool calls (add and multiply numbers) by validating OAuth2 tokens via Keycloak token introspection.-
- AlicenseNot gradedqualityCmaintenanceSecures MCP tools as an OAuth 2.1 resource server, validating short-lived delegated tokens, enforcing policy-as-code, and auditing AI agent actions.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to authenticate through Convex OAuth Provider, verifying access tokens and exposing a whoami tool for retrieving the authenticated user's identity and scopes.1MIT