# 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](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) (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](docs/ARCHITECTURE.md).

**Building or operating a wallet and want to offer issuance without implementing OIDC4VCI yourself?** See the [Wallet Integration Guide](docs/WALLET_INTEGRATION.md) — 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.

---

## Architecture at a glance

```text
   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](docs/ARCHITECTURE.md).

---

## Feature support

| Feature | Status |
| --- | --- |
| Credential Offer, by value or by reference | Supported |
| Pre-Authorized Code Grant | Supported |
| Authorization Code Grant | Supported |
| PKCE ([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636), `S256`) | Supported |
| Pushed Authorization Requests ([RFC 9126](https://www.rfc-editor.org/rfc/rfc9126)) | Supported, auto-detected from Authorization Server metadata |
| DPoP ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) | Supported, auto-detected from Authorization Server metadata |
| Rich Authorization Requests / `authorization_details` ([RFC 9396](https://www.rfc-editor.org/rfc/rfc9396)) | Supported, replaced by a `scope` fallback when one is available, for Authorization Servers that don't support RAR |
| Transaction Code (`tx_code`) | Supported |
| Nonce Endpoint / `c_nonce` | Supported |
| `jwt` Proof Type | Supported |
| `attestation` Proof Type / key attestation | Not yet |
| Deferred Credential Issuance | Supported |
| Multiple credential configurations per offer | Supported — one Credential Request per configuration, one per tool call |
| Signed (JWT) Credential Issuer Metadata | Supported — signature verified against the `x5c` leaf certificate; no certificate chain-of-trust validation |
| Credential Request/Response Encryption | Not yet |
| Batch Credential Issuance | Not yet |
| Notification Endpoint | Supported — one scalar `notification_id` per session; a multi-configuration session can only act on the most recently issued configuration's |

See [docs/ARCHITECTURE.md](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](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](docs/ARCHITECTURE.md#get_credential_issuer_metadata) 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](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](https://www.rfc-editor.org/rfc/rfc9449) 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/issuance.py), [src/mcp_oidc4vci/authorization_server_metadata.py](src/mcp_oidc4vci/authorization_server_metadata.py), [src/mcp_oidc4vci/token_request.py](src/mcp_oidc4vci/token_request.py), and [src/mcp_oidc4vci/dpop.py](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](https://www.rfc-editor.org/rfc/rfc9126) 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](docs/ARCHITECTURE.md#begin_authorization-and-submit_authorization_result) 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/authorization_request.py), [src/mcp_oidc4vci/pushed_authorization_request.py](src/mcp_oidc4vci/pushed_authorization_request.py), and [src/mcp_oidc4vci/pkce.py](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/wallet.py), [src/mcp_oidc4vci/credential_request.py](src/mcp_oidc4vci/credential_request.py), and [src/mcp_oidc4vci/nonce.py](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](docs/ARCHITECTURE.md#request_wallet_proof-and-submit_wallet_proof) 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](docs/ARCHITECTURE.md#send_credential_notification) for the scalar `notification_id` scope limit on multi-configuration sessions. See [src/mcp_oidc4vci/notification.py](src/mcp_oidc4vci/notification.py) and [src/mcp_oidc4vci/session_request.py](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](src/mcp_oidc4vci/models.py), with tests in [tests/](tests/) (99% coverage, 305 tests).

---

## Tech Stack

- **[Python](https://www.python.org/)** — implementation language.
- **[uv](https://docs.astral.sh/uv/)** — dependency management, virtual environments, and running the project.
- **[FastMCP](https://github.com/jlowin/fastmcp)** — high-level Python framework for building the MCP server and its tools.
- **[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)** — the underlying official protocol SDK that FastMCP builds on.
- **[MCP Inspector](https://github.com/modelcontextprotocol/inspector)** — interactive tool for testing and debugging the MCP server's tools during development.

---

## Getting Started

```bash
# 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](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](docs/ARCHITECTURE.md#request_wallet_proof-and-submit_wallet_proof)) when there's no real wallet app on hand:

```bash
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](docs/ARCHITECTURE.md#begin_authorization-and-submit_authorization_result)), 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](docs/ARCHITECTURE.md) — components, design principles, wallet boundary, data flow, MCP tool contracts, security requirements.
- [Wallet Integration Guide](docs/WALLET_INTEGRATION.md) — 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](docs/ROADMAP.md) — delivery phases, MVP scope, and what's explicitly out of scope.