decoy-mcp-server

A local MCP bridge for Decoy. It lets an AI agent (Claude Desktop, Claude Code, or any MCP client) manage your Decoy identities — create decoy email aliases, list and create accounts, and fill credentials — on your behalf.

End-to-end encrypted. The bridge unwraps your vault-key grant and decrypts account data on your machine. Decoy's servers only ever see sealed blobs — they stay blind to your service↔identity graph.

Quick start

npx decoy-mcp-server

On first run it prints a pairing code and a link to https://decoys.me/connect — approve it in the Decoy iOS app. The approved agent token is saved to ~/.decoy/mcp-token and reused on subsequent runs.

The bridge serves MCP over HTTP at http://localhost:3001/mcp.

Connect your MCP client

Point your client at the local bridge. For example, Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "decoy": { "url": "http://localhost:3001/mcp" }
  }
}

Configuration

| Env var | Default | Purpose | |---|---|---| | DECOY_AGENT_TOKEN | — | Explicit agent token (skips interactive pairing) | | PORT | 3001 | Local HTTP port for the MCP endpoint | | DECOY_AGENT_API_URL | https://api.decoys.me/api/agent | Decoy agent API base | | DECOY_AGENT_NAME | MCP Server | Display name shown in the iOS approval prompt + Connected Apps | | DECOY_AGENT_FOR | mcp | URL slug (?for=) so the pairing page shows the right agent (e.g. claude-code, cursor) | | DECOY_CONNECT_URL | https://decoys.me/connect | Branded pairing page the bridge opens | | DEV_MODE | — | true → use dev-api.decoys.me | | DECOY_NO_BROWSER | — | true → don't open a browser; print pairing info as JSON (same as --no-browser) |

Token and agent key live under ~/.decoy/.

CLI flags

npx decoy-mcp-server --no-browser   # headless: print pairing URL/code as JSON on stdout
npx decoy-mcp-server --logout       # revoke this bridge's token + delete ~/.decoy credentials

In headless/CI environments the bridge can't open a desktop browser. With --no-browser it emits one machine-readable line on stdout so a wrapper can surface the QR to a human:

{"decoy_pairing":{"url":"https://decoys.me/connect?code=ABC123&for=mcp","code":"ABC123","expires_at":"..."}}

How it works (read this before integrating)

An account is the whole identity; a decoy is its disposable email layer. They're linked (account.decoy_email_id ⇄ decoy.account_id). The human-readable service name (e.g. "ForeUp") lives on the account, not the decoy.

• To find "the identity for X", use account_list / account_get — they return the decrypted service_name, username, etc. decoy_list only carries the alias address, hash, and an optional plaintext agent_label.
• Reads are metadata-only. inbox_list returns ids, flags, timestamps, smtp_message_id, and a parsed sender_domain (so you can find "the email from foreup.com" without decrypting). The full sender, subject, and body are E2EE.
• Secrets & content require an unlock. account_unlock, message_unlock, and personal_unlock send an approval push to your iPhone (or auto-approve if you've granted a standing policy with a time window). The plaintext is decrypted in this bridge process with your agent key — Decoy's servers never see it.
• Field-level unlock. account_unlock takes an optional datatypes array (RFC 9396, CXF type names: basic-auth, address, credit-card, custom-fields, totp, note, passkey) to request only specific fields. Omit it to get the login credential.

Permissions

At pairing the bridge requests scopes for every tool family it exposes, including the unlock verbs. In the iOS app you can narrow what's granted (you can only narrow, never add). If a call returns Insufficient scope, the error lists what the token holds and how to grant the missing capability — usually: re-pair and approve it.

Docs

Full tool catalog and guides: https://decoys.me/documentation

Changelog: CHANGELOG.md

License

MIT