MCP-OIDC4VCI

AI-Assisted Verifiable Credential Issuance using MCP

This project explores how the Model Context Protocol (MCP) can be used to expose capabilities from an OpenID for Verifiable Credential Issuance (OIDC4VCI) ecosystem to an AI agent. It targets OIDC4VCI 1.0 (final specification).

The goal is not to replace a wallet, nor to give an LLM access to private keys or unrestricted credentials. Instead, the project investigates a more constrained architecture:

An MCP server acts as an agent-facing orchestration layer for understanding and progressing through an OIDC4VCI credential issuance flow, while security-sensitive operations remain under the control of dedicated components such as the wallet or credential holder.

The project starts from a concrete scenario:

A user receives an OIDC4VCI Credential Offer and wants an AI agent to help understand what is being offered and guide or orchestrate the issuance process.

Motivation

OIDC4VCI defines a protocol for issuing Verifiable Credentials to a wallet or credential holder. A typical flow involves a Credential Offer, a Credential Issuer and its metadata, an Authorization Server, authorization or pre-authorized flows, credential requests, proofs and cryptographic key binding, and credential delivery and storage — a significant amount of structured information for a user to parse on their own.

An AI agent can potentially help by understanding a credential offer, explaining what's being offered, discovering supported credential configurations, determining the required issuance flow, identifying what's needed next, and orchestrating non-sensitive protocol interactions.

The central question this project explores is:

How can OIDC4VCI capabilities be exposed to an AI agent through MCP without compromising the security boundaries of wallets and cryptographic key material?

For the full system design, see Architecture.

Building or operating a wallet and want to offer issuance without implementing OIDC4VCI yourself? See the Wallet Integration Guide — nothing about using this server that way requires an AI agent in the loop; any MCP client, including a plain deterministic orchestrator, can drive these tools.

Related MCP server: Cheqd MCP Toolkit

Architecture at a glance

   AI Agent ──MCP──▶ OIDC4VCI MCP Server ──▶ Credential Issuer / Authorization Server
                              │
                              ▼
                       Wallet Boundary
                              │
                              ▼
              Key Management / Proofs / User Authorization

The MCP server acts as an intermediary between the AI agent and the OIDC4VCI ecosystem — it should not automatically become a wallet. Sensitive operations (keys, proofs, consent) stay behind an explicit wallet boundary, never in the LLM context.

Full details, component responsibilities, data flows, tool contracts, and security requirements live in docs/ARCHITECTURE.md.

Feature support

See docs/ARCHITECTURE.md for the design reasoning behind each of these.

Current capabilities

This project is under active development. Here's what's implemented today.

Credential Offer inspection. inspect_credential_offer resolves a Credential Offer by value or by reference (credential_offer_uri), validates it against OIDC4VCI 1.0, and returns the issuer, requested credential configuration IDs, and grants. See src/mcp_oidc4vci/credential_offer.py.

Credential Issuer metadata discovery. get_credential_issuer_metadata fetches and validates a Credential Issuer's metadata from its well-known endpoint (correctly inserting the well-known path segment ahead of any path component in the issuer identifier, per spec), verifies the returned credential_issuer matches what was requested, and returns the credential endpoint, authorization servers, and supported credential configurations. It transparently handles either the unsigned JSON or the signed-JWT metadata representation (RFC 7515), verifying the JWS signature against the x5c certificate conveyed in the JOSE header — see Architecture for exactly what "verified" does and doesn't mean here (no certificate chain-of-trust validation is performed). See src/mcp_oidc4vci/credential_issuer_metadata.py.

Issuance flow orchestration. describe_issuance_flow, initiate_issuance, and get_issuance_status run on top of an in-memory IssuanceSessionStore. For the pre-authorized code grant, initiate_issuance completes the full Token Request end to end — OAuth Authorization Server discovery via RFC 8414, then the token exchange, including a DPoP proof of possession when the Authorization Server requires one. For the authorization code grant, it resolves the Authorization Server's metadata and leaves the session ready for begin_authorization. See src/mcp_oidc4vci/issuance.py, src/mcp_oidc4vci/authorization_server_metadata.py, src/mcp_oidc4vci/token_request.py, and src/mcp_oidc4vci/dpop.py.

Authorization code grant. begin_authorization builds the Authorization Request URL (PKCE, RFC 7636, S256; authorization_details naming the requested credential configurations, RFC 9396 — replaced by each configuration's own scope, when one is available, for an Authorization Server that doesn't support Rich Authorization Requests) for a human to open and complete — pushing its parameters first via Pushed Authorization Requests when the Authorization Server requires it, transparently to the caller — and submit_authorization_result exchanges the resulting code/state for an access token, rejecting a mismatched state before ever making a Token Request. This server has no HTTP endpoint of its own to receive the browser redirect, so the code/state are supplied back explicitly rather than captured automatically — see Architecture for why. Both grants converge on the same ready_for_credential_request state from here. See src/mcp_oidc4vci/authorization_request.py, src/mcp_oidc4vci/pushed_authorization_request.py, and src/mcp_oidc4vci/pkce.py.

Wallet boundary. WalletAdapter (a Protocol with generate_proof and receive_credential) backs request_credential, which completes a Credential Request for a ready_for_credential_request session: fetch issuer metadata, get a fresh nonce if the issuer needs one, ask the wallet for a signed proof (a real EC-signed openid4vci-proof+jwt, never signed by this server), send it — DPoP-bound if the session's access token is — and hand the issued credential to the wallet, whose contents never reach the agent. The spec's Credential Request only ever names one credential configuration, so an offer requesting several gets one Request per configuration: request_credential handles one per call and returns to ready_for_credential_request (not completed) while more remain, for the caller to call it again. If the issuer defers issuance instead of responding immediately, the session moves to awaiting_deferred_credential and poll_deferred_credential checks back later, reusing the same authentication, response handling, and one-at-a-time rule. The bundled MockWalletAdapter makes both grants work end to end for local testing. See src/mcp_oidc4vci/wallet.py, src/mcp_oidc4vci/credential_request.py, and src/mcp_oidc4vci/nonce.py.

Manual wallet handoff. request_wallet_proof / submit_wallet_proof split the Credential Request into two tool calls for when the proof must come from something other than the in-process MockWalletAdapter — a real wallet, or a human signing by hand — without needing any blocking-wait or webhook machinery: the handoff happens through the session, the same way initiate_issuance → get_issuance_status already does. request_credential (the automatic path) is unchanged and still there for fast, fully-automated testing. See Architecture for the design reasoning.

Notification Endpoint. send_credential_notification reports a previously issued credential's outcome (credential_accepted, credential_failure, or credential_deleted) back to the Credential Issuer, using the notification_id a prior Credential Response or Deferred Credential Response carried — authenticated with the same Bearer/DPoP access token, never a new Token Request. Both sending a notification (the Wallet's side) and the issuer supporting this endpoint at all are optional per spec, so "nothing to notify about yet" and "this issuer doesn't support notifications" are reported as clear errors rather than silently ignored — but neither one, nor a rejected notification, ever fails the session: this is a side-channel courtesy to the issuer, not a step in the issuance flow. See Architecture for the scalar notification_id scope limit on multi-configuration sessions. See src/mcp_oidc4vci/notification.py and src/mcp_oidc4vci/session_request.py (the Bearer/DPoP-with-nonce-retry POST helper shared with request_credential).

Shared data models live in src/mcp_oidc4vci/models.py, with tests in tests/ (99% coverage, 305 tests).

Tech Stack

• Python — implementation language.

• uv — dependency management, virtual environments, and running the project.

• FastMCP — high-level Python framework for building the MCP server and its tools.

• MCP Python SDK — the underlying official protocol SDK that FastMCP builds on.

• MCP Inspector — interactive tool for testing and debugging the MCP server's tools during development.

Getting Started

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Run the MCP server through the MCP Inspector for interactive testing
uv run fastmcp dev inspector src/mcp_oidc4vci/server.py:mcp

# Lint, type-check, and run the test suite
uv run ruff check .
uv run mypy src
uv run pytest

Testing the manual wallet-proof path without a real wallet

scripts/sign_proof.py signs a spec-shaped proof JWT the same way MockWalletAdapter does, but as a separate process — useful for exercising request_wallet_proof / submit_wallet_proof (see Architecture) when there's no real wallet app on hand:

uv run scripts/sign_proof.py --audience https://issuer.example.com --nonce abc123

Pass its output straight to submit_wallet_proof's proof_jwt argument.

Testing the authorization code grant

This server has no HTTP endpoint of its own to receive a browser redirect (see Architecture), so completing this grant needs a real Authorization Server, a client_id/redirect_uri registered with it, and a browser: call begin_authorization, open the returned authorization_url, authenticate, and copy the code/state query parameters from wherever the browser lands after the redirect into submit_authorization_result.

Documentation

• Architecture — components, design principles, wallet boundary, data flow, MCP tool contracts, security requirements.

• Wallet Integration Guide — for a team integrating their own wallet against this server instead of implementing OIDC4VCI issuance themselves: the two supported integration shapes, the full tool catalog, the session state machine, and current limitations to check against your target issuer(s).

• Roadmap — delivery phases, MVP scope, and what's explicitly out of scope.