Wink MCP

What is Wink MCP

Wink MCP is a hosted MCP server that wraps the Wink Core API as a set of agent-callable tools. You connect once with a bearer token; your agent then has access to face / voice recognition, wallet operations, biometric authentication, age verification, and checkout — all as ordinary tool calls in whatever MCP host you use.

Two things distinguish it from calling the Core API directly:

• Server-side credentials. Your Wink merchant clientId / clientSecret never leave Wink's infrastructure. The MCP server holds them and signs every call to Wink on your behalf, so the agent (and the model running it) can't see your secrets even if a prompt injection tries.
• Agent-shaped tool surface. Tools encapsulate the multi-call flows the Core API needs — for example, recognize_face handles session-mint-then-multipart-recognise as a single call, returns just the fields an agent cares about, and masks PII by default so a chat transcript doesn't accidentally store full names.

Get an API key

Wink MCP keys are provisioned per-merchant. Reach out to your Wink contact (or use the Get keys link in the top-right of this site) and you'll receive a 64-character hex token tied to your merchant account.

Treat the token like a password:

• Don't paste it into a Git repo or share it in a chat.
• Each developer on your team gets their own token — revoke individually when someone leaves.
• If a token leaks, ask Wink to rotate it and your agents will need the new one.

Connect a client

Three of the most common MCP hosts cover most cases. The pattern is identical: point the host at https://mcp.wink.bio/api/mcp with an Authorization: Bearer <token> header.

Claude Code

One CLI invocation:

claude mcp add --transport http wink \
  https://mcp.wink.bio/api/mcp \
  --header "Authorization: Bearer <your-token>"

Then in any Claude Code session, ask the agent to call a Wink tool — it'll appear in /mcp alongside your other servers.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "wink": {
      "url": "https://mcp.wink.bio/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Restart Claude Desktop. The Wink tools appear in the tool picker.

Cursor

Settings → Cursor Settings → MCP → Add new MCP server:

{
  "mcpServers": {
    "wink": {
      "url": "https://mcp.wink.bio/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Sanity check

Before you wire it into an agent, confirm the server answers a raw tools/list:

curl -i -X POST https://mcp.wink.bio/api/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

You should see all 25 tools enumerated. A 401 means the token is wrong; a 502 means Wink is upstream-failing (rare on stage).

Tool reference

Tools are grouped by purpose. Each one is a single MCP tools/call on the server side; on the agent side it just looks like a tool the model can invoke. Argument and return shapes are advertised via JSON schema in the tools/list response — your MCP host pulls them automatically.

Example flows

"Identify the person in this photo"

The simplest possible flow — agent gets a JPEG, returns who it is.

1. Agent receives an image (e.g. user uploads a photo to Claude Desktop).
2. Agent calls recognize_face with the base64-encoded image.
3. Server returns { match: true, winktag: ";stage-…", first_name: "A****x", confidence: 0.99 }.
4. Agent narrates the masked result back to the user.

Names are masked by default. Full PII is reserved for a future scoped token; the pii_mode: "full" argument is accepted for forward-compat but currently falls back to masked.

"Charge this person for $20"

Recognition + wallet + checkout, three tools, one user-visible step (biometric auth on their device).

1. recognize_face_wallet on a captured photo to identify the user and load their cards.
2. request_biometric_auth for confirmation — the user gets a URL on their phone.
3. wait_for_biometric_auth blocks until they consent.
4. prepare_checkout with the chosen card token + amount.
5. wait_for_checkout blocks until the authorization clears.

"Is this user old enough to buy alcohol?"

For age-gated commerce — no DoB ever leaves Wink.

1. recognize_face identifies the user.
2. check_age_verified with their winktag returns { verified: true } or false.
3. If false, agent points the user at request_enrollment to add ID-document verification, then loops back.

Self-host

If your data-residency or compliance posture rules out a hosted MCP server, the implementation is open. Clone wink-mcp-server, configure your own Wink merchant credentials and Turso DB, and deploy to your own Vercel project (or any Node 22 host that supports streaming HTTP).

git clone https://github.com/wink/wink-mcp-server.git
cd wink-mcp-server
pnpm install
cp .env.example .env.local
# fill in WINK_*, MCP_API_KEYS, TURSO_*
pnpm db:push
pnpm dev   # http://localhost:3030/api/mcp

The server is intentionally framework-light — Next.js 15 App Router + @vercel/mcp-adapter + Drizzle + libsql. Roughly 4k LoC; review-friendly.

Notes & gotchas

Bearer tokens, not OAuth (yet)

The current scheme is a shared bearer per developer. We'll add OAuth 2.1 client credentials when the use case appears — for instance, when an agent platform wants to mint per-end-user tokens. Until then: keep your bearer where you keep API keys.

PII is masked by default

Names come back as A****x K****m (first + last char visible). This is so a chat transcript can't reconstruct identifying detail by accident. Tools that read profile fields (get_user_profile, show_wallet) honour the same default. To opt into full PII, you'd ask Wink for a scoped token — that mechanism doesn't exist yet but the wire format already accepts pii_mode: "full".

No biometric data ever leaves Wink

The MCP server only ever proxies recognition results. Face images, voice clips, and the embeddings Wink computes from them stay on Wink's infrastructure. The audit log on the MCP side captures tool name, latency, and Wink's response status code — never the inputs.

Single-use sessions are handled for you

Wink Core sessions are single-use; the MCP server mints fresh sessions per call and self-heals on stale-session 401s. You don't need to think about session lifecycle when using MCP — it's the same model as calling REST through the playground console.

Function timeout is 60 s on Vercel Pro

Most tools complete in under a second. The exceptions are the blocking polls — wait_for_biometric_auth and wait_for_checkout — which honour their own TTL but cap at the function deadline. If you need longer waits, use request_* + check_* (non-blocking) and poll from your agent's loop instead.