decentralgabe/world-id-mcp

World ID MCP

Minimal MCP HTTP server that gates tools behind World ID proofs. Baseline verification defaults to device; privileged operations (demo) skip step-up for simplicity. Includes a tiny IDKit web page to fetch a proof and swap it for a JWT.

Flow

flowchart TD
    A[User opens web demo] --> B[IDKit shows QR]
    B --> C[User approves in World App]
    C --> D[session endpoint world-id.verify]
    D --> E[JWT issued token scopes exp]
    E --> F[Client calls tools with token]
    F --> G[Tool verifies JWT scopes enforced]
    G --> H[Audit log and response]

Setup

• Node 18+, pnpm.
• Install deps: pnpm install -r
• Env: cp server/.env.example server/.env and set WORLD_APP_ID, WORLD_ACTION_ID, WORLD_VERIFICATION_LEVEL (default device), SESSION_JWT_SECRET (and PORT if desired). The server will exit if app/action IDs are missing. The web demo reads these from the server via /config, so you only set them once in server/.env.
• Run server: pnpm start (serves /health, /mcp, /session on port 3000).
• Build all (optional): pnpm build
• Tests (server): pnpm test

MCP tools

• world-id.verify → validates proof, returns {token, scopes, expiresAt}
• echo → requires scope tools.echo (send JWT)
• advanced-operation → requires scope tools.advanced (send JWT); step-up disabled in demo

REST helper

• POST /session with a World ID proof mirrors world-id.verify (handy for the web demo or custom clients).
• POST /demo/echo and POST /demo/advanced are simple REST shortcuts used by the web demo.

IDKit Web Demo

cd demo/idkit-web
cp .env.example .env   # set app/action/verification + server URL
pnpm install
pnpm dev               # http://localhost:5173

Click “Verify with World ID”; it posts the proof to /session and shows the JWT to paste into your agent.

Using with Claude

1. Start server: pnpm start (set PORT if 3000 is busy).
2. Add MCP server to Claude:
   • CLI: claude mcp add --transport http world-id http://localhost:3000/mcp
   • Config: "world-id": { "type": "http", "url": "http://localhost:3000/mcp" }
3. Get a token (human proof):
   • Run the web demo (pnpm dev or pnpm dev:web) at http://localhost:5173
   • Scan the QR, approve in World App, copy the token.
4. Call tools from Claude:
   • echo: { "token": "<jwt>", "message": "hi" }
   • advanced-operation: { "token": "<jwt>", "operation": "something" }
5. If you see errors:
   • Token invalid/expired → get a fresh proof.
   • “Missing required scope: tools.advanced” → request that scope when verifying.
   • (If step-up is re-enabled later) advanced will ask for a fresh proof; provide stepUpProof.

File map

• server/src/mcp-server.ts – MCP server + tools + /session
• server/src/auth/ – World ID verification, JWT minting, policies
• demo/test-client.ts – sample MCP client
• demo/idkit-web/ – Vite + IDKit proof collector