Decoy lets your agent act as a user's password manager and email client — signing in to sites, filling out forms, and sending and reading mail from disposable addresses — while their secrets stay encrypted. Decoy's servers only ever hold encrypted data and can't read a password or a message; the keys live in the user's Decoy app, where they approve what your agent may do.

Connect

With the MCP server, connecting is automatic: the first call opens an approval screen the person scans in the Decoy app, and every endpoint here becomes a tool — credential_get, email_send, and so on.

Over raw HTTP, use the OAuth 2.0 Device Grant:

# 1. Start the connection. The response includes `verification_uri_complete` —
#    open THAT branded Decoy page for the user (https://decoys.me/connect?code=…).
#    It shows the QR and the in-app approval. NEVER render the QR yourself; always
#    drive the user to the Decoy page so they approve on a surface they can trust.
curl -X POST https://decoy-api.vercel.app/oauth/device \
  -d 'client_id=my-agent&scope=account.read account.unlock message.read message.unlock'

# 2. Once they approve, exchange the code for a token.
curl -X POST https://decoy-api.vercel.app/oauth/token \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=…&client_id=my-agent'
# Then send:  Authorization: Bearer <token>

Ask only for what the task needs — the user can narrow it when they approve, and your agent can request more later.

Once granted, it just works

After the user approves access, your agent uses it until the grant expires or they revoke it — read a saved password or new mail instantly, no further interaction. To reach something the user hasn't granted yet, ask for it (they approve once); everything already granted needs nothing more.

Every request stays inside what the user granted: the kind of access, and the specific accounts and inboxes they chose. When something falls outside it, the response tells your agent exactly what to request next.

The tools

Plus password_generate. An account is a saved login; a decoy is a disposable email address you can attach to one.

Examples

Connect Your agent pairs the first time it's used: it shows the user a link to approve in the Decoy app. After that, check what you can do.

my_permissions()   // your live grant: scopes, accounts and inboxes, and for how long

Read a saved password

credential_get({ domain: "github.com" })   // → { username, password }

Send an email Sending needs access to the inbox. If it isn't in your grant, ask for it — the user approves on their phone — then send from a decoy address.

request_access({ kind: "message", action: "write", resource_id: "<decoy_id>" })
email_send({ from: "<decoy_id>", to: "[email protected]", subject: "Hi", body_text: "Sent from a decoy." })

Create a new account Save a new login. The password is encrypted before it leaves your agent.

credential_set({ domain: "acme.com", username: "[email protected]", password: password_generate() })