# Decoy for AI agents

> Decoy gives consumer AI agents user-approved passwords, email codes, passkey assertions and personal details through MCP or HTTP. Users choose which accounts and information an agent can access and for how long. Decoy records every data access. The server stores ciphertext and never sees plaintext.

## Start here
- [Decoy for AI agents](https://www.decoys.me/agents): the product, permission model, security boundaries and MCP quickstart.
- [Interactive API reference](https://www.decoys.me/documentation)
- [OpenAPI spec (JSON)](https://www.decoys.me/openapi.json)

## What Decoy for AI agents is
Decoy is for developers building consumer AI agents that act through a user's real accounts. It combines a password manager, service-specific email, 2FA and autofill in one integration. An agent can sign in with an approved password or passkey, retrieve an approved email code or TOTP, and use approved personal details such as a name, address or card. Agents connect through the `decoy-mcp-server` package or the HTTP API.

## Security boundaries
- **Stored in Decoy:** Only the accounts and information the user adds or imports.
- **Allowed for the agent:** Only the accounts, information and duration the user approves.
- **Received by the agent:** Only information requested within the approved access. An approved password reaches the agent as plaintext. A passkey private key never leaves the user's phone.
- **Visible to Decoy's server:** Ciphertext and request metadata, never decrypted passwords, messages or personal information.
- **Recorded for the user:** Every Decoy data access, including which connected agent accessed it.
- **Not controlled by Decoy:** After an agent receives a password or other information, its runtime controls how that information is used, logged and passed to other tools.

## Reference
- [Interactive API reference](https://www.decoys.me/documentation)
- [OpenAPI spec (JSON)](https://www.decoys.me/openapi.json)
- [Full reference for LLMs](https://www.decoys.me/llms-full.txt)

## Resources
- **Accounts** — **Top-level entity** — a stored login for one service.
- **Autofill** — **Top-level entity** — the autofill vault: reusable personal data (cards, addresses, emails, phones, names, birthdays), independent of any account or decoy.
- **Profile** — **Read-only summary — not an entity.** A roll-up of your activity across all accounts and decoys (active logins, disabled logins, total messages). Useful for dashboards or UI counters. Nothing is saved or read back here — to Save or Read credentials use **Accounts**.
- **Decoys** — **The disposable email alias you Send an email from.** Create a decoy (e.g. "Acme signup") to get a unique address like `swift.harbor93@decoys.me`, then send from it. Replies land in the inbox (see **Messages**).
- **Messages** — **Where you Send an email and Read an email.** Each decoy has an inbox. Send new mail or reply to received mail; read a message's body by approving it on your phone.
- **Forwarding** — **Where received emails go.** Point a decoy's inbox at a real email address you own; when someone replies to the alias, it forwards to that address. One verified address can serve many decoys.
- **Rules** — **Sub-resource of a decoy** — _deprecated; the app no longer surfaces rules._ A per-decoy notification rule (label + match pattern, enable/push flags, trigger count); requires `decoy_id` on every operation.
- **Subdomain** — **A decoy variant, not a distinct entity.** The personal catch-all domain (`*@you.decoys.me`) is one decoy row with `is_subdomain = true`.
- **Alerts** — **Sub-resource correlated to a decoy** — _deprecated._ A security / money / hygiene alert, optionally referencing a decoy via a nullable `alerts.decoy_id` (can also be user-level).
- **Unlock** — **Mechanism, not an entity** — the unified single-use E2EE bridge.
- **Approvals** — **Mechanism, not an entity** — step-up consent for sensitive *writes* (distinct from Unlock, which reads plaintext).
- **Policies** — **Mechanism, not an entity** — the standing RFC 9396 consent ledger on an agent token.
- **Content** — **Legacy mechanism — superseded by Unlock** _(deprecated)._ The original message-only E2EE bridge (`/api/agent/content`).
- **Pairing** — **Bootstrap flow, not an entity.** A short-lived (10-min) session that mints an agent token.
- **OAuth** — **Standards surface over the same pairing flow.** OAuth 2.1 + RFC 9126 PAR + RFC 9396 RAR + RFC 8628 Device Grant.
- **Tokens** — **The auth subject for every call** — the long-lived agent credential.
- **Webhooks** — **Delivery machinery owned by an agent token.** Agent-registered HTTPS callbacks for metadata-only lifecycle events (signed HMAC-SHA256 in `X-Decoy-Signature`), max 10 active per user.
- **Events** — **Delivery machinery, not an entity** — the pull counterpart of Webhooks.

The Decoy MCP server exposes every agent operation as an LLM-callable tool. The catalog below is generated from the running bridge — it is exactly what your client will see.

<!-- AUTOGEN:tools:start -->
## MCP tools by namespace (52 total)

### Decoy identities (9)
- decoy_burn — Permanently delete a decoy and its message history
- decoy_burn_batch — Permanently delete multiple decoys in one call
- decoy_create — Create a new decoy email identity for a service
- decoy_disable — Disable a decoy email so it stops receiving mail
- decoy_enable — Re-enable a previously disabled decoy so it starts receiving mail again.
- decoy_get — Get a single decoy identity by ID
- decoy_list — List decoy email identities with filtering, sorting, and pagination
- decoy_pause_batch — Disable email forwarding on multiple decoy identities in one call
- decoy_update — Update a decoy's avatar, service name, or label

### Decoy insights (3)
- decoy_notifications_get — Get notification settings for a decoy identity
- decoy_notifications_update — Update notification settings for a decoy identity
- decoy_stats — Get per-decoy message statistics: total/unread counts, activity timestamps, and outbound metrics.

### Inbox (6)
- inbox_get — Get metadata for a single message
- inbox_list — List messages with filtering, sorting, and pagination
- message_delete — Permanently delete a message
- message_reply — Reply to an existing inbound message
- message_send — Send a new email from a decoy identity (not a reply — starts a new conversation)
- message_toggle_read — Mark a message as read or unread

### Unlock (E2EE bridge) (3)
- account_unlock — Unlock stored account secrets via the E2EE bridge
- message_unlock — Unlock decrypted content for one or more messages via the E2EE bridge
- personal_unlock — Unlock a personal-info field (email, phone, card, address) via the E2EE bridge

### Forwarding (3)
- forwarding_disable — Disable email forwarding for a decoy identity
- forwarding_enable — Enable email forwarding for a decoy identity to a configured forwarding address
- forwarding_get — Get the current email forwarding state for a decoy identity

### Forwarding addresses (3)
- forwarding_email_add — Add a new forwarding email address
- forwarding_email_delete — Remove a forwarding email address
- forwarding_email_list — List all forwarding email addresses configured for the user

### Webhooks (3)
- webhook_delete — Remove a webhook registration by ID
- webhook_list — List webhook registrations with optional filtering.
- webhook_register — Register a webhook to receive events instead of polling

### Accounts (6)
- account_burn_decoy — Permanently delete (burn) the decoy email attached to an account
- account_create — Create an account record for a service
- account_get — Get a single account by ID, including its linked decoy email hash if protected
- account_list — List accounts with filtering, sorting, and pagination
- account_protect — Attach a decoy email to an account as a privacy protection layer
- account_update — Update account metadata

### Credentials (3)
- account_credential_status — Check whether a stored credential exists for an account, and when it was last updated
- account_set_credential — Store a password for an account using end-to-end encryption
- password_generate — Generate a strong random password in MCP server memory

### Personal info (3)
- personal_info_add — Add a reusable personal-info entry (email, phone, card, address, name, or date of birth)
- personal_info_delete — Delete a personal info entry by ID and type
- personal_info_list — List personal info entries (emails, phones, cards, addresses)

### Personal aliases (7)
- alias_disable — Disable (block) a personal alias so it no longer receives emails
- alias_enable — Restore a previously disabled alias so it receives emails again.
- alias_list_disabled — List all disabled (blocked) aliases for the personal subdomain
- alias_stats — Get first-seen dates for personal aliases (when each alias first received an email)
- subdomain_claim — Claim a personal alias subdomain (e.g
- subdomain_status — Get the user's personal alias (subdomain) status — whether claimed, enabled, and disabled alias count.
- subdomain_toggle — Enable or disable the personal alias catch-all

### Profile & approvals (3)
- passkey_assert — Log in to a site with a stored passkey — the browser-relay WebAuthn flow
- request_approval — Request user approval via push notification before taking a sensitive action
- resolve — Resolve a secret by reference — the fast path for "read this account's password"
<!-- AUTOGEN:tools:end -->