Decoy

decoy-mcp-server

Your Decoy vault is what your agents should know about you, shared by every agent you connect: your memories, accounts (logins, codes, passkeys), personal info (emails, phones, cards, addresses) and Decoy addresses. Your memories, accounts and personal info are end-to-end encrypted: Decoy's servers can't read them. Mail to your Decoy addresses is encrypted as it arrives. You choose exactly what each agent can read or change. This package is the local MCP bridge to your vault, for Claude Desktop, Claude Code or any MCP client.

Agents and the vault: read before, write after. Check the vault before asking the person. Save lasting facts as new memories, sensitive ones too; if you can't save, ask once for Save. Update a memory when its fact changes, instead of adding another. Ask for only what the task needs.

End-to-end encrypted. Memories, secrets and mail are decrypted on your machine; Decoy's servers store ciphertext. Some things are plaintext to the server by design:

• routing metadata, authorship and timestamps;
• optional label and agent_label values;
• the domain given to request_access;
• account_unlock with domain sends the domain only from a connection without your vault key; one that holds it finds the account on your machine and reads it by id, and so do credential_get and resolve;
• reason text shown in approval prompts, as the agent wrote it (a reason the bridge writes itself says "this account" and names no site);
• request_approval description and metadata;
• inbox_list sender_domain and decoy_list search, which are sent as filters;
• mail sent through a decoy, forwarding addresses, and webhook URLs and secrets;
• which category, topic or account each memory is shared through.

A connection without your vault key (for example "Create accounts" alone) seals an account's service name and site on your machine when it creates the account: once to your own key, and once to that connection's key, so it can read the name back. The banner on mail forwarded from that account's address is titled with the account's label. Sealing keeps the name and site from being stored readable: Decoy stores the two sealed copies as sent. For your copy the bridge seals to the public key Decoy serves for you, and it trusts that key. They leave your machine sealed or not at all: when they cannot be sealed (the connection has no key of its own, or your public key is not on file), or Decoy does not take them sealed, the account is not created and the tool says why. A rename is sealed on your machine to your own key, and your Decoy app applies it. A label is plain text to the server: never put a name you want kept private, or a secret, in a label.

Every request the bridge sends to the Decoy API it is set to carries one header that names this package and its version: X-Decoy-Client: decoy-mcp-server/1.3.1 (decoy-mcp-server/1.3.1; mode=context from a --context run). It says nothing about your machine, your client or you, and it is sent to no other host.

Quick start

npx decoy-mcp-server

On first run it prints "Tap to connect Decoy:" and a link to https://decoys.me/connect; you approve it in the Decoy iOS app, and it prints "Connected to Decoy." An agent that meets an unconnected bridge says exactly that to you: "Tap to connect Decoy:" with the link on its own line, then "Connected to Decoy." once you approve, and nothing else about connecting. The connection is saved under ~/.decoy/ and reused on every later run; see Staying connected.

The bridge serves MCP over HTTP at http://localhost:3001/mcp. Then make Decoy the first step of every task.

Connect your MCP client

Point a Streamable HTTP-capable MCP client at the local bridge. For clients using the mcpServers HTTP configuration format:

{

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

Keep the bridge current

Keeping the bridge on its latest release is part of setup: the owner approved it when they connected Decoy, so an agent updates it without asking. When a newer release is published, the bridge says so in its --context output and after one tool result per session, with the version and the command: npx -y decoy-mcp-server@latest (or your install's own update), then a restart of the bridge. The saved connection is kept. A bridge more than two minor versions behind the latest release (with latest 1.3.x, below 1.1.0) is refused with UPDATE_REQUIRED and the same command.

Run it so it updates with nobody stepping in:

• Started by npx: start it with npx -y decoy-mcp-server@latest. Each start runs the latest release.
• A long-running service on a server (systemd): the service starts the latest release, and a timer restarts it once a day so a new release is picked up within a day.

# /etc/systemd/system/decoy-mcp.service

[Unit] Description=Decoy MCP bridge After=network-online.target Wants=network-online.target

[Service]

The user whose home holds the saved connection (~/.decoy)

User=agent Environment=DECOY_AGENT_NAME=Your agent's name Environment=DECOY_NO_BROWSER=true ExecStart=/usr/bin/env npx -y decoy-mcp-server@latest Restart=on-failure RestartSec=10

[Install] WantedBy=multi-user.target

# /etc/systemd/system/decoy-mcp-update.service

[Unit] Description=Restart the Decoy MCP bridge on its latest release

[Service] Type=oneshot ExecStart=/usr/bin/systemctl try-restart decoy-mcp.service

# /etc/systemd/system/decoy-mcp-update.timer

[Unit] Description=Restart the Decoy MCP bridge daily

[Timer] OnCalendar=daily RandomizedDelaySec=1h Persistent=true

[Install] WantedBy=timers.target

sudo systemctl daemon-reload

sudo systemctl enable --now decoy-mcp.service decoy-mcp-update.timer

@latest runs each release as it is published. To check each release yourself before it runs, pin a version instead (npx -y decoy-mcp-server@1.3.1) and move the pin when the bridge says a newer one is out.

Memory with the MCP bridge

The memory tools ship in the bridge. Start it as in Quick start, approve the connection in the Decoy app, then connect a Streamable HTTP MCP client to http://localhost:3001/mcp. A hosted agent cannot reach the user's localhost; run the bridge inside its trusted integration environment.

Memory search uses mem0's engine locally (optional dependencies, installed with the package). Its embedding model (Qdrant's bge-small-en-v1.5) is downloaded once from a pinned Hugging Face commit, checked against its SHA-256, and cached under ~/.decoy/models. Search and embeddings run on your machine. Memory text is never sent to Decoy, which stores ciphertext and which category, topic or account each memory is shared through, or to the model host. Your MCP client's model sees the memories it reads, and tags new ones through MCP sampling. Set DECOY_MEMORY_ENGINE=basic to skip the engine and the download. The engine's optional dependencies add about 300 MB and run native install scripts (better-sqlite3, onnxruntime-node); to install without them, run with npm_config_omit=optional (memory search then uses word overlap).

The default memory tools are add_memory, search_memories, get_memories, get_memory, update_memory, delete_memory, and the topic tools list_topics, read_topic, list_duplicate_topics, connect_topics, disconnect_topics, set_topic_parent and move_memories. Check the actual tools/list schema. The bridge handles encryption and keeps one user-owned store. There is no account named Memories to create and no place to pick. Saving takes memory.save (Save new memories), which the bridge asks for when it connects, together with memory.read (Read all memories) and account.create (Add accounts to Decoy). While a connection holds memory.save it reads and edits what it saved; deleting a memory takes memory.delete. Without memory.save a save answers 403 INSUFFICIENT_GRANT; ask once with request_access({"permissions":["memory.save"]}) and retry. Other memories follow memory.read / memory.edit (all, or by category or topic) and, for the memories about an account, acctmem.*.

How an agent is told to use memory:

• Read before you start. Before a new task it searches memory for the subject and lists the relevant topics. Memory is the store of what is known about you, your accounts, preferences and past decisions.
• Write as you go. It saves what is worth keeping during a task (a decision, a fact about an account, where things stand; not raw attempts or working notes), not only at the end. Sessions end abruptly.
• One memory, one fact. A memory is readable on its own and carries what makes it useful later: who said or decided it and when (the date it was said, not when it was saved), the reason, the status, in as many sentences as it needs.
• Always organise. Every memory gets every category that fits (misc only when no other category fits), and one place, chosen in this order:

1. A fact about a service you have an account for is linked to that account (app_id: the account's name exactly as list_topics shows it under accounts, or its ID): order status, the plan, a renewal date, support history, how you like to use it.
2. A fact about a subject (a project, a trip, a person, an organisation) goes under a topic.
3. Only a fact about you yourself takes neither.

A memory is about an account or a topic, not both. Every save answers with where the memory landed (filed).

• Topics make a web. Before creating a topic the agent reads the existing ones and reuses one that fits. When two or more topics share a subject, the agent creates the broader topic first, then each of the others under it, and can move a topic later. A topic gets a relation that is true and specific for you and that subject; for health, money, legal or relationship subjects the relation says no more than the topic's name.
• Keep it correct. A changed fact updates the original memory (same ID); a wrong one is deleted.
• Secrets are never saved as memories.

A worked example: an account, a topic with a sub-topic, a personal fact

Sam Sample is renovating a kitchen and has an account named "Example Cabinets" with the cabinet supplier. Each fact is saved where it belongs. In the calls the memory text says "the user": that is how an agent is told to write it. These are MCP tool calls:

1. A fact about a service Sam has an account for is linked to that account. app_id is the account's name exactly as list_topics shows it under accounts, or its ID:

add_memory({"text":"Cabinet order placed with Example Cabinets on 2026-03-02.","app_id":"Example Cabinets","categories":["milestones"]})

The result says where it landed, before anything else about its place: "filed": {"under":"account","id":" ","name":"Example Cabinets"}.

1. One memory, one fact: the delivery week is a second memory, linked to the same account:

add_memory({"text":"Example Cabinets delivery is booked for the week of 2026-03-23.","app_id":"Example Cabinets","categories":["milestones"]})

1. What Sam asked of that supplier is a third:

add_memory({"text":"For Example Cabinets deliveries, the user asked on 2026-03-02 for a slot after 10am.","app_id":"Example Cabinets","categories":["user_preferences"]})

1. A fact about the project goes under a topic. The topic is new, so the call says how it connects to Sam:

add_memory({"text":"On 2026-02-20 the user decided to keep the current kitchen layout, so no pipes are moved.","topic":"Kitchen renovation","topic_type":"project","topic_link":{"relation":"is renovating"},"categories":["milestones"]})

1. A fact abou