MCP Wallet Verification for AI Agents — Complete Developer Guide & API Reference

Connect EUDI‑compliant data wallets (e.g., Talao) to AI agents using the Model Context Protocol (MCP) and OIDC4VP (pull model).
This service bridges decentralized identity wallets with AI systems such as ChatGPT, VS Code, or custom agents.

Base URL: https://wallet-connectors.com
MCP RPC endpoint: POST https://wallet-connectors.com/mcp
Spec version: MCP 2025‑06‑18 (params.arguments, result.content[], result.structuredContent)
Protocol model: OIDC4VP (pull) — no webhooks required

This guide covers: authentication, test profiles, tool reference, examples, integrations, and best practices.

🔐 1. Authentication

Preferred: Authorization: Bearer <token>
Also accepted: X-API-KEY: <token>

For public test profiles, token = verifier_id (0000, 0001, 0002, 0003).

No cookies or OAuth are used. Each MCP call must include the header.

🧠 2. Test Verifier Profiles (ready to use)

`verifier_id`	OIDC4VP Draft	Verifier identity	Default scope	Returned data (typical fields)	X-API-KEY
`0000`	Draft 20	Redirect-URI	`wallet_identifier`	`wallet_identifier` (DID or JWK thumbprint)	`0000`
`0001`	Draft 20	DID	`email`	`email_address` (`email`)	`0001`
`0002`	Draft 20	DID	`over18`	`over_18` (boolean)	`0002`
`0003`	Draft 28	DID	`profile`	`family_name`, `given_name`, `birth_date`	`0003`

Use these IDs and keys for sandbox testing.
To register your own verifier or Presentation Definition (custom claims), see Section 11.

🧩 3. Available Tools (MCP methods)

`start_wallet_verification`

Starts a new OIDC4VP flow and returns a QR + deeplink for user authentication.

Arguments: - verifier_id (required) — one of your registered verifier profiles (demo: 0000–0003) - session_id (optional) — custom session (else generated)

The scope is implicit based on the chosen verifier_id (see table above).

Returns:
content[] (QR image, helper text) + structuredContent JSON with:**
content[] (QR image, helper text) + structuredContent JSON with:

{
  "session_id": "...",
  "deeplink_url": "openid4vp://...?request_uri=...",
  "pull_url": "https://wallet-connectors.com/verifier/wallet/pull/...",
  "public_base_url": "https://wallet-connectors.com"
}

`poll_wallet_verification`

Poll verification status for a session_id.

Returns:

{
  "status": "pending | verified | denied",
  "session_id": "...",
  "claims": {...}
}

Tokens (vp_token, id_token) are redacted; only derived claims are returned.

`revoke_wallet_flow`

Acknowledge cleanup after completion. Useful for front‑ends; the backend TTL handles expiry.

🎯 4. Default Scopes & Returned Claims (demo profiles)

The demo verifier_ids bind to a single scope each:

Verifier	Scope	Returned claims (flattened)	Notes
`0000`	`wallet_identifier`	`wallet_identifier`	Often DID or JWK thumbprint derived from ID token
`0001`	`email`	`email_address` (aka `email`)	PID/eIDAS‑style
`0002`	`over18`	`over_18` (boolean)	True/false age gate
`0003`	`profile`	`family_name`, `given_name`, `birth_date`	OIDF standard profile subset

For custom scopes/claims, register your verifier with a Presentation Definition.

---|---|---| | profile | family_name, given_name, birth_date | OIDF standard | | email | email_address, email | eIDAS v2 PID | | phone | mobile_phone_number, phone | eIDAS v2 PID | | wallet_identifier | Wallet DID or JWK thumbprint | ID‑token only flow | | over18 | over_18 (boolean) | Wallet‑dependent format | | custom | As defined in your Presentation Definition | Requires registration |

⚡ 5. Quick Start (curl)

List tools

curl -s https://wallet-connectors.com/mcp   -H 'Content-Type: application/json'   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

Start (Demo 0000 — default scope: wallet_identifier)

curl -s https://wallet-connectors.com/mcp   -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'X-API-KEY: 0000'   -d '{
    "jsonrpc":"2.0",
    "id":"start",
    "method":"tools/call",
    "params":{
      "name":"start_wallet_verification",
      "arguments":{"verifier_id":"0000"}
    }
  }' | jq

Poll

curl -s https://wallet-connectors.com/mcp   -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'X-API-KEY: 0000'   -d '{
    "jsonrpc":"2.0",
    "id":"poll",
    "method":"tools/call",
    "params":{
      "name":"poll_wallet_verification",
      "arguments":{"session_id":"<SESSION_ID>"}
    }
  }' | jq

💻 6. Minimal Client Snippets

JavaScript (browser or Node)

const MCP = "https://wallet-connectors.com/mcp";
const KEY = "0000";

const rpc = async (method, params, id="1") => {
  const res = await fetch(MCP, {
    method: "POST",
    headers: { "Content-Type": "application/json", "Accept": "application/json", "X-API-KEY": KEY },
    body: JSON.stringify({ jsonrpc: "2.0", id, method, params })
  });
  return res.json();
};

const start = await rpc("tools/call", { name: "start_wallet_verification", arguments: { verifier_id: "0000" } });
console.log(start.result.structuredContent.deeplink_url);

const poll = await rpc("tools/call", { name: "poll_wallet_verification", arguments: { session_id: start.result.structuredContent.session_id } });
console.log(poll.result.structuredContent.status);

Python (requests)

import requests, time

MCP = "https://wallet-connectors.com/mcp"
HDR = {"Content-Type":"application/json","Accept":"application/json","X-API-KEY":"0000"}

def rpc(method, params, id="1"):
    return requests.post(MCP, headers=HDR, json={"jsonrpc":"2.0","id":id,"method":method,"params":params}).json()

start = rpc("tools/call", {"name":"start_wallet_verification","arguments":{"verifier_id":"0000"}})
sid = start["result"]["structuredContent"]["session_id"]

while True:
    poll = rpc("tools/call", {"name":"poll_wallet_verification","arguments":{"session_id":sid}})
    status = poll["result"]["structuredContent"]["status"]
    print(status)
    if status != "pending": break
    time.sleep(2)

🧠 7. Integration with ChatGPT or VS Code

ChatGPT Desktop

Add to ~/.config/openai/mcp/servers.json:

{
  "wallet-connectors": {
    "command": "bash",
    "args": ["-lc", "echo ready"],
    "env": { "X_API_KEY": "0000" },
    "transport": {
      "type": "http",
      "url": "https://wallet-connectors.com/mcp",
      "headers": {
        "X-API-KEY": "0000",
        "Accept": "application/json"
      }
    }
  }
}

Restart ChatGPT → check Settings → MCP Servers.

VS Code

Create .vscode/mcp.json:

{
  "servers": {
    "wallet-connectors": {
      "transport": {
        "type": "http",
        "url": "https://wallet-connectors.com/mcp",
        "headers": { "X-API-KEY": "0000" }
      }
    }
  }
}

Reload and open the MCP panel.

🧩 8. Response Anatomy

Generic shape

{
  "result": {
    "content": [ /* image/text blocks */ ],
    "structuredContent": { /* JSON */ }
  }
}

Example — `start_wallet_verification`

{
  "result": {
    "content": [
      { "type": "image", "data": "<base64‑PNG>", "mimeType": "image/png" },
      { "type": "text", "text": "Scan or open deeplink: openid4vp://..." }
    ],
    "structuredContent": {
      "session_id": "3e02ac7e‑...",
      "deeplink_url": "openid4vp://...?request_uri=...",
      "pull_url": "https://wallet-connectors.com/verifier/wallet/pull/..."
    }
  }
}

Example — `poll_wallet_verification`

{
  "result": {
    "structuredContent": {
      "status": "verified",
      "session_id": "3e02‑...",
      "wallet_identifier": "did:jwk:ey987875978987ED",
    }
  }
}
```json
{
  "result": {
    "structuredContent": {
      "status": "verified",
      "session_id": "3e02‑...",
      "wallet_identifier": "did:jwk:...",
      "first_name": "John",
      "last_name": "DOE"
    }
  }
}

⚙️ 9. Error Handling

Type	Location	Example
JSON‑RPC error	Top‑level `error`	`{"error":{"code":401,"message":"Missing or invalid X-API-KEY"}}`
Tool‑level error	Inside `result`	`"result":{"isError":true,"structuredContent":{"error":"invalid_arguments"}}`

Common causes - 401 — invalid/missing API key
- 400 — malformed arguments
- upstream_error — verifier returned 4xx/5xx
- network_error — unreachable wallet service

🧩 10. Best Practices

Poll every 1–2 s until status != "pending"
Use minimal scopes — use the appropriate demo verifier for minimal claims
Handle both flattened and nested claim structures
Redacted tokens: vp_token / id_token are never exposed
Enable CORS with proper headers for browser clients

🧩 11. Register Your Own Verifier

Public profiles (0000–0002) are shared sandbox verifiers.
Register to obtain a dedicated verifier_id and API key for: - Private deployments - Custom drafts (OIDC4VP 20, 25, 26) - Unique verifier identities (DID, JWKS, etc.) - Custom Presentation Definitions (PEX/DCQL)

Visit wallet‑connectors.com for registration.

🧰 12. Developer & Metadata Endpoints

Endpoint	Description
`GET /mcp/info`	Returns `{ name, version, protocolVersion, endpoints, auth }`
`GET /mcp/healthz`	Returns `{ ok: true }`

💡 13. Troubleshooting

Missing API key (401) → Include X-API-KEY or Authorization header
Pending forever → Ensure wallet supports selected draft/scope
Invalid session → Use latest session_id from start_wallet_verification
Browser CORS error → Include Content-Type, Accept, and X-API-KEY headers
Tool error ≠ RPC error → inspect both layers (error vs result.isError)

📘 14. Privacy & Security

No cookies or persistent storage.
API keys are per verifier; rotate periodically.
Tokens (id_token, vp_token) never leave the verifier backend.
Redacted responses ensure no personally identifiable raw data exposure.

🧾 15. Versioning & Changelog

1.4.0 — Scope parameter removed from start_wallet_verification; default scope now bound to each verifier_id (added demo 0003 → profile).
1.3.0 — Comprehensive unified developer documentation; test profiles; best practices.
1.2.0 — Added ChatGPT / VS Code setup; sample clients.
1.1.0 — Structured MCP 2025‑06‑18 compliance.
1.0.0 — Initial release.

Maintainer: Talao DAO • MIT License