Skip to main content
Glama

MCP-OIDC4VCI

使用 MCP 的 AI 辅助可验证凭证签发

本项目探讨如何利用 Model Context Protocol (MCP) 将 OpenID for Verifiable Credential Issuance (OIDC4VCI) 生态系统的能力暴露给 AI 智能体。它以 OIDC4VCI 1.0(最终规范)为目标。

目标不是取代钱包,也不是让 LLM 访问私钥或不受限制的凭证。相反,本项目研究一种更受约束的架构:

MCP 服务器充当面向智能体的编排层,用于理解并推进 OIDC4VCI 凭证签发流程,而安全敏感的操作仍由钱包或凭证持有者等专用组件控制。

本项目从一个具体场景出发:

用户收到一个 OIDC4VCI 凭证要约,希望 AI 智能体帮助理解所提供的内容,并引导或编排签发流程。


动机

OIDC4VCI 定义了一种向钱包或凭证持有者签发可验证凭证的协议。一个典型流程涉及凭证要约、凭证签发者及其元数据、授权服务器、授权流程或预授权流程、凭证请求、证明与密码学密钥绑定,以及凭证交付与存储——用户需要自行解析大量结构化信息。

AI 智能体可以通过理解凭证要约、解释所提供的内容、发现支持的凭证配置、确定所需的签发流程、识别下一步需要什么,以及编排非敏感的协议交互来提供帮助。

本项目探索的核心问题是:

如何通过 MCP 将 OIDC4VCI 的能力暴露给 AI 智能体,同时不损害钱包和加密密钥材料的安全边界?

完整的系统设计请参阅 架构。计划构建内容和当前范围请参阅 路线图。


Related MCP server: Cheqd MCP Toolkit

架构概览

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

MCP 服务器充当 AI 智能体与 OIDC4VCI 生态系统的中介——它不应自动变成钱包。敏感操作(密钥、证明、同意)保留在明确的钱包边界之后,绝不进入 LLM 上下文。

完整细节、组件职责、数据流、工具契约和安全要求位于 docs/ARCHITECTURE.md 中。


项目状态

早期阶段。架构和 MVP 范围已在 docs/ARCHITECTURE.md 和 docs/ROADMAP.md 中起草。

阶段 1(MCP 凭证要约检查器)——已完成。 inspect_credential_offer 按值或按引用(credential_offer_uri)解析凭证要约,根据 OIDC4VCI 1.0 对其进行验证,并返回签发者、请求的凭证配置 ID 和授权类型。参见 src/mcp_oidc4vci/credential_offer.py。

阶段 2(元数据发现)——已完成。 get_credential_issuer_metadata 从其 well-known 端点获取并验证凭证签发者的元数据(按照规范,将 well-known 路径段正确插入到签发者标识符中任何路径组件之前),验证返回的 credential_issuer 与请求的一致,并返回凭证端点、授权服务器和支持的凭证配置。参见 src/mcp_oidc4vci/credential_issuer_metadata.py。

阶段 3(签发流程引擎)——已完成。 describe_issuance_flow、initiate_issuance 和 get_issuance_status 基于内存中的 IssuanceSessionStore 实现。对于预授权码授权,initiate_issuance 完成真正的令牌请求(通过 RFC 8414 进行 OAuth 授权服务器发现,然后进行令牌交换);对于授权码授权,则停在 waiting_for_user_authorization,因为完成该流程需要钱包驱动的重定向,而阶段 4 同样未涵盖这一点(见下文)。参见 src/mcp_oidc4vci/issuance.py、src/mcp_oidc4vci/authorization_server_metadata.py 和 src/mcp_oidc4vci/token_request.py。

阶段 4(钱包边界)——已完成(范围缩小)。 WalletAdapter(一个带有 generate_proof 和 receive_credential 的 Protocol)和 MockWalletAdapter 为新的 request_credential 工具提供支持,该工具为 ready_for_credential_request 会话完成凭证请求:获取签发者元数据,如果签发者需要 nonce 则获取新的 nonce,向钱包请求签名的证明(一个真正的 EC 签名的 openid4vci-proof+jwt,绝不是由本服务器签名的),将其 POST,并将签发的凭证交给钱包——其内容绝不会到达智能体。预授权码授权现在可以端到端工作。参见 src/mcp_oidc4vci/wallet.py、src/mcp_oidc4vci/credential_request.py 和 src/mcp_oidc4vci/nonce.py。

共享数据模型位于 src/mcp_oidc4vci/models.py 中,测试位于 tests/(99% 覆盖率,124 个测试)。


技术栈

  • Python —— 实现语言。

  • uv —— 依赖管理、虚拟环境以及运行项目。

  • FastMCP —— 用于构建 MCP 服务器及其工具的高级 Python 框架。

  • MCP Python SDK —— FastMCP 所基于的底层官方协议 SDK。

  • MCP Inspector —— 开发过程中用于测试和调试 MCP 服务器工具的交互式工具。


快速入门

# 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

文档

  • 架构 —— 组件、设计原则、钱包边界、数据流、MCP 工具契约、安全要求。

  • 路线图 —— MVP 范围、开发阶段、非目标、成功标准、未来扩展。

Available Tools

6 tools
describe_issuance_flowB

Describe the steps required to obtain the credential(s) offered by a Credential Offer.

Resolves the offer and returns which grant-based flow applies and its ordered steps.

Inputs: credential_offer (required). Returns: object

get_credential_issuer_metadataA

Fetch and validate a Credential Issuer's metadata from its well-known endpoint.

Returns the issuer's credential endpoint, authorization servers, and the credential configurations it supports.

Inputs: credential_issuer (required). Returns: object

get_issuance_statusB

Return the current state of a previously started issuance session.

Inputs: session_id (required). Returns: object

initiate_issuanceA

Start an issuance session for a Credential Offer.

For the pre-authorized code grant, completes the token exchange immediately and the session ends ready_for_credential_request or failed. For the authorization code grant, the session is left waiting_for_user_authorization, since completing it requires a wallet-driven redirect not yet implemented. tx_code is the transaction code obtained from the user out-of-band, if the offer requires one.

Inputs: credential_offer (required), tx_code. Returns: object

inspect_credential_offerA

Parse and validate an OIDC4VCI Credential Offer URI.

Resolves the offer (by value or by reference) and returns its Credential Issuer, requested credential configuration IDs, and available grants.

Inputs: credential_offer (required). Returns: object

request_credentialA

Complete the Credential Request for a session that has an access token.

Generates a key proof of possession through the wallet adapter — this server never signs anything itself — and hands the issued credential to the wallet for safekeeping. Its contents are never returned to the agent.

Inputs: session_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool targets a distinct phase of the OIDC4VCI flow, but inspect_credential_offer and describe_issuance_flow both resolve an offer and could be confused by an agent deciding whether to inspect contents or get next steps. The remaining tools have clearly separate boundaries.

    Naming Consistency5/5

    All six tools use a consistent snake_case verb_noun pattern, e.g. get_, inspect_, describe_, initiate_, and request_. There is no casing or verb-style mixing, making the set highly predictable.

    Tool Count5/5

    Six tools is well-scoped for an OIDC4VCI issuance server, covering offer inspection, metadata, flow analysis, initiation, status, and credential request. Each tool earns its place with no redundant or superfluous additions.

    Completeness3/5

    The toolset covers the pre-authorized code issuance path well, but the authorization-code grant is left in waiting_for_user_authorization with no tool to complete the user-authorization redirect or exchange the authorization code. This is a notable dead end for standard OIDC4VCI authorization-code flows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to securely use Open Agent ID credentials for signing requests, looking up agent data, and exchanging encrypted messages. It performs all cryptographic operations within the server process to ensure private keys are never exposed to the AI agent.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to securely manage decentralized identities, verifiable credentials, and trust registries on the Cheqd network via the Model Context Protocol.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI agents with a DID-based identity, secure wallet, and cloud KMS-backed signing keys, enabling trusted interactions with persons, companies, and other agents via standards like OIDC4VCI, OIDC4VP, and SD-JWT.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to create and verify tamper-evident cryptographic evidence, manage key-bound Agent Passports, and support verifiable handoffs, approvals, and audit trails through MCP, REST, and A2A.
      MIT