Skip to main content
Glama
mcp-oidc-proxy

mcp-oidc-proxy

by Pappa

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:9000

  • MCP server — a FastMCP HTTP server on http://127.0.0.1:8000 with a single protected hello_world tool

Together they prove that an MCP client can authenticate through OIDCProxy, call a protected tool, and be rejected when unauthenticated.

Prerequisites

  • uv

  • Python 3.14+

Related MCP server: mcp-keycloak

Setup

uv sync
cp .env.example .env

Demo 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 nanoidp
uv run launch-mcp

The 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 / admin

  • OAuth 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 tools
clear_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

    B3.2/5.0

    Scored across 26 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables secure MCP tool calls (add and multiply numbers) by validating OAuth2 tokens via Keycloak token introspection.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      1
      MIT