Zetrix VC MCP Server

A Model Context Protocol (MCP) server for the Zetrix BaaS Verifiable Credentials API. Provides 20 tools across 6 categories — VC issuance (apply / issue / download), Verifiable Presentations, revocation, DID generation & resolution, and on-chain template lookup. Supports both stdio and HTTP transport modes.

Wraps the myeg-ms-credential service exposed through the Zetrix BaaS gateway under /cred/v1/*.

Quick Start

npx zetrix-vc-mcp-server

Or install globally:

npm install -g zetrix-vc-mcp-server

Minimum configuration — add to your MCP client's config (see Claude Desktop / Claude Code below):

{
  "mcpServers": {
    "zetrix-vc": {
      "command": "npx",
      "args": ["-y", "zetrix-vc-mcp-server"],
      "env": {
        "ZETRIX_VC_NETWORK": "uat",
        "AWS_GATEWAY_API_KEY": "<your AWS API Gateway key>",
        "BAAS_API_KEY": "<your Zetrix BaaS key>",
        "ISSUER_PRIVATE_KEY": "<issuer ed25519 private key>",
        "HOLDER_PRIVATE_KEY": "<holder ed25519 private key>",
        "DEFAULT_TEMPLATE_ID": "did:zid:…"
      }
    }
  }
}

Features (20 tools)

General (1 tool)

DID Utilities (2 tools)

Template Lookup (1 tool)

VC Issuance (8 tools)

The preferred entrypoint is zetrix_vc_request_credential — it orchestrates apply → issue → download in one call and writes the final VC to a JSON file on disk. The other tools expose individual steps for advanced integrations.

VC Revocation (4 tools)

Verifiable Presentations (5 tools)

Supported Networks

Official Addresses & Template IDs

Use these when filling in TDS_CONTRACT_ADDRESS, RCL_CONTRACT_ADDRESS, and DEFAULT_TEMPLATE_ID environment variables.

Contract addresses

Official templates

Each template id below links to its raw record on-chain (via the node's getAccountMetaData endpoint), which contains the template's applyFormat, issuerZid, and metadata.

Full template ids — each block below has a copy button on github.com (hover the block on desktop, tap on mobile). Paste the value into DEFAULT_TEMPLATE_ID.

MyKAD — UAT

did:zid:f1d675934d353394fa90d6132a3f8393b670a326632d936d1174df7307fadba4

MyKAD — Prod

did:zid:2139cb5dc5c2080ff4f85a85f6ae49322d109992a921d5f8d50e1af5eadf01d5

Email — UAT

did:zid:9833ccc5238cfe4c61ccad652487c8b05f8c6f20e60073efe051fbbd1ea395aa

Email — Prod

did:zid:9d0b9a925c66dab30a682446ea0bc75245e93eec6c0bb3a425b50795ebbb1a2e

Driving License — UAT

did:zid:313dc2cf2a9950a688f6b759dfbbbc8cd69e1fb6db1d15d877970119748c0a7c

Driving License — Prod

did:zid:89b37ba3ab25c02d96f3acfd948c68aa7b86c5c313b421522db06b86fc831d6e

Passport — UAT

did:zid:4820fdbc080dda72335a436bba02252d341302382a58d7bb2ae8fe845579993e

Passport — Prod

did:zid:24cbe3286714b8dde39cdd04094f6b2c8d2c1803882d5762d06eb883971385f1

Or use zetrix_vc_get_template_detail at runtime to fetch + parse the record programmatically.

Configuration

Environment Variables

Secure Credentials (Recommended)

By setting keys as environment variables, the LLM never needs to see or handle the raw secrets. The server uses them silently; users can refer to the holder/issuer as "me" without mentioning keys.

{
  "mcpServers": {
    "zetrix-vc": {
      "command": "npx",
      "args": ["-y", "zetrix-vc-mcp-server"],
      "env": {
        "ZETRIX_VC_NETWORK": "uat",
        "AWS_GATEWAY_API_KEY": "…",
        "BAAS_API_KEY": "…",
        "ISSUER_PRIVATE_KEY": "…",
        "HOLDER_PRIVATE_KEY": "…",
        "DEFAULT_TEMPLATE_ID": "did:zid:…",
        "TDS_CONTRACT_ADDRESS": "ZTX3…"
      }
    }
  }
}

Note: Every credential can also be passed per-call via tool arguments (issuerPrivateKey, holderPublicKey, etc.). Explicit arguments always override env values. Addresses like ZTX3… cannot be used as DIDs — the tool will reject them and ask for the DID / public key / private key instead.

Claude Code (CLI)

Add the MCP server directly from the command line:

UAT (sandbox):

claude mcp add zetrix-vc-uat -s user -- npx -y zetrix-vc-mcp-server \
  -e ZETRIX_VC_NETWORK=uat \
  -e AWS_GATEWAY_API_KEY=<aws-key> \
  -e BAAS_API_KEY=<baas-key> \
  -e ISSUER_PRIVATE_KEY=<issuer-priv> \
  -e HOLDER_PRIVATE_KEY=<holder-priv> \
  -e DEFAULT_TEMPLATE_ID=<did:zid:…> \
  -e TDS_CONTRACT_ADDRESS=<ZTX3…>

Prod:

claude mcp add zetrix-vc -s user -- npx -y zetrix-vc-mcp-server \
  -e ZETRIX_VC_NETWORK=prod \
  -e AWS_GATEWAY_API_KEY=<aws-key> \
  -e BAAS_API_KEY=<baas-key> \
  -e ISSUER_PRIVATE_KEY=<issuer-priv> \
  -e HOLDER_PRIVATE_KEY=<holder-priv>

Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

UAT (sandbox):

{
  "mcpServers": {
    "zetrix-vc-uat": {
      "command": "npx",
      "args": ["-y", "zetrix-vc-mcp-server"],
      "env": {
        "ZETRIX_VC_NETWORK": "uat",
        "AWS_GATEWAY_API_KEY": "<aws-key>",
        "BAAS_API_KEY": "<baas-key>",
        "ISSUER_PRIVATE_KEY": "<issuer-priv>",
        "HOLDER_PRIVATE_KEY": "<holder-priv>",
        "DEFAULT_TEMPLATE_ID": "did:zid:…",
        "TDS_CONTRACT_ADDRESS": "ZTX3…"
      }
    }
  }
}

Prod:

{
  "mcpServers": {
    "zetrix-vc": {
      "command": "npx",
      "args": ["-y", "zetrix-vc-mcp-server"],
      "env": {
        "ZETRIX_VC_NETWORK": "prod",
        "AWS_GATEWAY_API_KEY": "<aws-key>",
        "BAAS_API_KEY": "<baas-key>",
        "ISSUER_PRIVATE_KEY": "<issuer-priv>",
        "HOLDER_PRIVATE_KEY": "<holder-priv>"
      }
    }
  }
}

Both networks:

{
  "mcpServers": {
    "zetrix-vc-uat":  { "command": "npx", "args": ["-y", "zetrix-vc-mcp-server"], "env": { "ZETRIX_VC_NETWORK": "uat",  "…": "…" } },
    "zetrix-vc-prod": { "command": "npx", "args": ["-y", "zetrix-vc-mcp-server"], "env": { "ZETRIX_VC_NETWORK": "prod", "…": "…" } }
  }
}

After saving, restart Claude Desktop for changes to take effect. See ready-made templates in configs/.

HTTP Transport (API Server)

Run the MCP server as an HTTP API using the Streamable HTTP transport — useful for remote MCP clients or shared team deployments.

Start the server:

ZETRIX_VC_TRANSPORT=http ZETRIX_VC_PORT=3000 \
  ZETRIX_VC_NETWORK=uat \
  AWS_GATEWAY_API_KEY=<aws-key> \
  BAAS_API_KEY=<baas-key> \
  ISSUER_PRIVATE_KEY=<issuer-priv> \
  HOLDER_PRIVATE_KEY=<holder-priv> \
  npx zetrix-vc-mcp-server

Endpoints:

Connect from an MCP client:

{
  "mcpServers": {
    "zetrix-vc": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

⚠️ The /mcp endpoint has no built-in authentication. Do not expose it on the public internet without a reverse proxy (nginx/Caddy) terminating TLS and enforcing auth. The BaaS / AWS keys in env are used for outbound calls only.

Server logs: go to stderr. Run foreground to watch, or redirect:

# Foreground
ZETRIX_VC_TRANSPORT=http ZETRIX_VC_PORT=3000 npx zetrix-vc-mcp-server

# Background with logs
ZETRIX_VC_TRANSPORT=http ZETRIX_VC_PORT=3000 npx zetrix-vc-mcp-server 2> server.log &
tail -f server.log

Examples

Once configured, simply ask the LLM to do what you want — the agent discovers required fields via the tool itself and asks only for what it needs.

You:    please issue VC to ZTX3MyCKa7k9Vx5HRR9xju1NKNZyqqQB8Nh6f

Agent:  I can't use a Zetrix address directly — could you give me their
        DID, public key, or private key?

You:    here is the public key: a1b2c3d4e5f6…

Agent:  I also need the holder's Full Name, IC Number, and Expiry Date.

You:    Ali Hassan, 880201-01-5678, 2030-06-15

Agent:  Done! The MyKAD credential has been issued.
        VC ID: did:zid:5c8e2f91…  •  Valid until: 2027-04-15

You:    please create VP from the VC, reveal only the name

Agent:  Done! Disclosed only: Name.
        Share token: v2-c3f91cab-…
        IC Number and Expiry are cryptographically hidden.

You:    please verify this VP: v2-c3f91cab-b635-4b50-aaef-dae986b7532d

Agent:  The presentation is valid ✓
        Disclosed: name = "Ali Hassan"

See docs/EXAMPLES.md for 11 complete conversation examples covering:

• Issue VC (to yourself / by address / by pubkey / by DID / by private key)
• Create VP with selective disclosure
• Verify VP by share token or by VP file
• Revoke a VC
• Check revocation status
• Look up template requirements
• Generate / resolve a DID

Development

Project Structure

zetrix-vc-mcp-server/
├── src/
│   ├── index.ts                # MCP server (20 tool definitions + handlers)
│   ├── zetrix-vc-client.ts     # BaaS HTTP client (/cred/v1/*)
│   ├── zetrix-vc-signer.ts     # Ed25519 signing (sign / signHex / DID derivation)
│   ├── zetrix-node-client.ts   # Zetrix public node RPC (template lookup)
│   └── zetrix-zid-resolver.ts  # DID document resolver
├── configs/
│   ├── mcp-config-uat.json     # Claude Desktop template for UAT
│   └── mcp-config-prod.json    # Claude Desktop template for prod
├── docs/
│   └── TEST_SUITE.md           # Live UAT test suite (31 test cases)
└── dist/                       # Compiled output (gitignored)

Build

npm install
npm run build

Run from source

npm start                 # stdio transport
npm run start:http        # HTTP transport on port 3000

Test

See docs/TEST_SUITE.md for the full test suite and live-verified results against the UAT BaaS.

License

MIT