MCP-OIDC4VCI

MCP를 활용한 AI 지원 검증 가능 자격 증명 발급

이 프로젝트는 **Model Context Protocol(MCP)**을 사용하여 OpenID for Verifiable Credential Issuance(OIDC4VCI) 생태계의 기능을 AI 에이전트에 노출하는 방법을 탐구합니다. OIDC4VCI 1.0(최종 명세)을 대상으로 합니다.

목표는 지갑을 대체하거나, LLM에게 개인 키 또는 무제한 자격 증명에 대한 접근 권한을 부여하는 것이 아닙니다. 대신, 이 프로젝트는 보다 제한된 아키텍처를 조사합니다.

MCP 서버는 OIDC4VCI 자격 증명 발급 흐름을 이해하고 진행하기 위한 에이전트 대면 오케스트레이션 계층으로 작동하며, 보안에 민감한 작업은 지갑 또는 자격 증명 보유자와 같은 전용 컴포넌트의 통제 하에 유지됩니다.

프로젝트는 구체적인 시나리오에서 출발합니다.

사용자가 OIDC4VCI 자격 증명 제안(Credential Offer)을 받았고, AI 에이전트가 무엇이 제안되었는지 이해하고 발급 프로세스를 안내하거나 오케스트레이션하도록 돕기를 원합니다.

동기

OIDC4VCI는 지갑 또는 자격 증명 보유자에게 검증 가능한 자격 증명을 발급하기 위한 프로토콜을 정의합니다. 일반적인 흐름에는 자격 증명 제안, 자격 증명 발급자와 그 메타데이터, 인증 서버, 인가 또는 사전 인가 흐름, 자격 증명 요청, 증명 및 암호화 키 바인딩, 자격 증명 전달 및 저장이 포함됩니다. 이는 사용자가 스스로 파악하기에 상당히 많은 양의 구조화된 정보입니다.

AI 에이전트는 자격 증명 제안을 이해하고, 무엇이 제공되는지 설명하고, 지원되는 자격 증명 구성을 발견하고, 필요한 발급 흐름을 결정하고, 다음에 필요한 것이 무엇인지 식별하며, 민감하지 않은 프로토콜 상호 작용을 오케스트레이션함으로써 잠재적으로 도움을 줄 수 있습니다.

이 프로젝트가 탐구하는 핵심 질문은 다음과 같습니다.

지갑과 암호화 키 자료의 보안 경계를 훼손하지 않으면서 OIDC4VCI 기능을 MCP를 통해 AI 에이전트에 어떻게 노출할 수 있을까?

전체 시스템 설계는 Architecture를 참조하세요. 계획된 구축 범위와 현재 범위는 Roadmap을 참조하세요.

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 및 승인(grant)을 반환합니다. 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를 얻고, 지갑에 서명된 증명(실제 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

문서

• Architecture — 컴포넌트, 설계 원칙, 지갑 경계, 데이터 흐름, MCP 도구 계약, 보안 요구 사항.

• Roadmap — MVP 범위, 개발 단계, 비목표, 성공 기준, 향후 확장.