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 email addresses. Your memories, accounts and personal info
are end-to-end encrypted: Decoy's servers can't read them. Mail to your Decoy emails 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
labelandagent_labelvalues; - the
domaingiven torequest_access; account_unlockwithdomainsends 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_getandresolve;reasontext shown in approval prompts, as the agent wrote it (a reason the bridge writes
itself says "this account" and names no site);request_approvaldescriptionandmetadata;inbox_listsender_domainanddecoy_listsearch, 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.7.0 (decoy-mcp-server/1.7.0;
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```bash
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://127.0.0.1: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:```json
{
"mcpServers": {
"decoy": { "type": "http", "url": "http://127.0.0.1:3001/mcp" }
}
}
For a client that starts its MCP servers as a child process and speaks over standard input and
output, start the bridge with --stdio:```json
{
"mcpServers": {
"decoy": { "command": "npx", "args": ["-y", "decoy-mcp-server@latest", "--stdio"] }
}
}
It lists every tool from the start. The first tool call answers with the link to connect Decoy;
once the owner approves in the Decoy app, the next call runs on the new connection. If the owner
revokes the connection, or it is continued on another machine, the call says so and the next one
answers with the link to connect again.
The bridge answers only programs running as the computer account that started it. On macOS and
Linux it checks, for each connection, which account's program holds the other end, and a program
of another account on the same computer (a CI runner's user, another person signed in) gets `403`.
MCP clients need no setting for this. It listens on both `127.0.0.1` and `::1` (where the system
has IPv6), so `localhost` reaches it too, and it does not start when another program already
listens on `127.0.0.1` or `::1` at its port.
An MCP client reaches whatever program listens on that port. While the bridge is not running
(before it starts, while it restarts), a program of another account can take the port, and the
client's requests, the tool calls and what they carry, go to that program. On a computer shared
with other accounts, use `--stdio`: the client starts the bridge and talks to it over a pipe, so no
other program can stand in for it.
A proxy or tunnel in front of the bridge must run as that same account, and every program that
can reach the proxy can use the bridge as you. On Windows, and in WSL (where programs on Windows
arrive through a relay), the bridge cannot tell which account a connection comes from: it says so
when it starts, and any program on the computer that reaches the port can use it. Under `--stdio`,
only the client that started the bridge talks to it.
### Keep the bridge current
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`. If the
person's setup text asks the agent to keep the bridge on its latest release, the agent updates it;
otherwise the agent tells the person a newer release is out. A bridge started with `npx -y decoy-mcp-server@latest` takes the new release when it
restarts, so the update is a restart; running that command beside the running bridge starts a
second one. An install with its own update uses that. The saved connection is kept. A bridge more
than two minor versions behind the latest release (with latest 1.4.x, below 1.2.0) is refused with
`UPDATE_REQUIRED`: it must be updated to keep working, and the refusal says the same.
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.```ini
# /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
``````ini
# /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
``````ini
# /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
``````bash
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.7.0) and move the pin when the bridge says a
newer one is out, once npx -y decoy-mcp-server@ --version answers it.
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://127.0.0.1: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), account.create (Add accounts to Decoy), acctmail.read and alias.read. 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. - A title and neat Markdown. Every memory has a short title (its own
titlefield, not a first
heading) and clean Markdown text: a short fact is a clear paragraph or two; longer text gets
lists, bold labels,codefor paths and commands, and sections. A title goes with a call that
saves one fact fromtext; a memory moved to its account keeps its title. - Always organise. Every memory gets every category that fits (
misconly 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 aslist_topicsshows it underaccounts, 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:
- A fact about a service Sam has an account for is linked to that account.
app_idis the
account's name exactly aslist_topicsshows it underaccounts, 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"}.
2. 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"]})
3. 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"]})
4. 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"]})
5. A fact about one part of the project goes under a sub-topic that hangs under it. The broader
topic was created first. Under a parent, the relation reads from the parent to the part:
add_memory({"text":"Choosing between oak and painted cabinet doors. On 2026-02-25 the user leaned towards oak because it hides wear; not decided.","topic":"Kitchen cabinets","topic_type":"product","topic_link":{"to":"Kitchen renovation","relation":"includes"},"categories":["user_preferences"]})
Its result has "filed": {"under":"topic","id":"topic:","name":"Kitchen cabinets","parent":"Kitchen renovation"}.
6. A fact about Sam takes neither an account nor a topic ("filed": {"under":"user"}):
add_memory({"text":"Prefers messages in the morning.","categories":["user_preferences"]})
list_topics({}) then shows the web, and the accounts a memory can be linked to:json
{"topics":[
{"id":"topic:<id>","name":"Kitchen renovation","type":"project","memories":1,"mine":true,
"link":{"from":"you","relation":"is renovating"},"sub_topics":1},
{"id":"topic:<id>","name":"Kitchen cabinets","type":"product","memories":1,"mine":true,
"link":{"from":"Kitchen renovation","from_id":"topic:<id>","relation":"includes"}}
],
"accounts":[
{"id":"22222222","name":"Example Cabinets","site":"cabinets.example"}
]}
When the delivery moves, the memory about the delivery is corrected in place (same ID), not
saved again:
update_memory({"memory_id":"","text":"Example Cabinets delivery moved to the week of 2026-03-30 (the supplier said so on 2026-03-18).","expected_rev":1})
Memory habits the bridge keeps for the agent
The tools keep part of these habits themselves. Everything below is per session: one connected
MCP client, whose session is kept in memory only, or one sequence of call commands, whose
counts are kept in a small file (see Use it without a running server).
- The summary comes without being asked. The first tool result of a session, whatever the
tool, is followed by the summary of what is known about you (at most 10 lines and 1,100
characters of memories, one line per memory, each cut at 200 characters), when the connection
can read memories. A line for a memory another agent saved starts with[agent_id: another agent]. Once per session. Not when the
agent's first call was itself a memory read. If the summary is not ready within one second, the
result says it is loading and the next result carries it. - A save that would contradict does not go by unnoticed.
add_memorylooks before it
writes, among the memories the connection can read. It catches many contradicting saves, not
all. - Held. An existing memory about the same subject (the same topic, the same account, or
both about you with no topic) that differs only in one detail (a number or date, a
negation, or a small word that changes the meaning, such as "to" and "from"), or that the
search model scores 0.95 or more and that differs in only two or three words. The fact is
not saved.
The result lists the candidates underneeds_decision(id, text, date; and
"agent_id":"another agent"before the text when another agent saved it) and counts them in
held; when nothing at all was saved it is an error. The agent calls again with exactly
one ofsupersedes: ""(that candidate is corrected in place and keeps its id) or
confirm_new: true(it is a separate fact). - Saved and flagged. Anything else that is close: similar by score (0.80 or more; half or
more of their words in common with the basic engine), a word or two apart, only an
article apart, one saying the same as the other and more, or any of the above filed under
another subject. For Chinese, Japanese, Korean and Thai text the score only ever flags. Up to three similar
memories are shown, each cut at 200 characters (get_memoryreturns the whole). The fact is saved and the result starts withreview:
what was saved and the similar memories. If it replaces one of them, one more call with the
same text andsupersedescorrects the older memory and removes the copy. - Only the same text is skipped as a duplicate (case, spacing and a final full stop aside).
supersedesonly replaces a memory the save is close to, at the revision it was shown at;
any other edit isupdate_memory. Candidates are only ever memories the connection can
already read: a connection that may only save sees none. - One line when it matters. After 3 tool calls that are not memory tools with no memory read
(6 when the summary was sent in this session), a result is followed by one line saying so:
what not reading risks, and the one call to make. After 8 tool calls with nothing saved, a
session that may save gets one line reminding it to. Each once per session, never on an error. - How to set up the first step. While no
--contextrun is recorded on this machine, the
summary sent with the first result, or elsemy_permissions, ends with one line giving the
command (see Make Decoy the first step of every task).
The command matches how the bridge was started:npx -y decoy-mcp-server@ --context
when npx started it. When the bridge is installed on the machine it is the full path of the
command that was run (ornodeand the full path of the bridge's file), followed by
--context.
Once per session; gone once a run is recorded. A connection that cannot read memories is not
told, and neither is a connected client whose connection is supplied by environment variables
or a credentials file, which keeps no such record. A sequence ofcallcommands is told until
a--contextrun is recorded, on this machine or in its own session. - Search results stay short.
search_memoriesreturns a memory longer than 600 characters as
an excerpt cut on a word, withtruncated: true;get_memoryreturns it whole. - The numbers.
my_permissionsends with a line counting this session's tool calls, memory
reads and saves, so "did you check and save?" has a factual answer.
These notes are separate text blocks after a tool's JSON; the JSON itself is unchanged.
Try it: save, recall, correct, forget
These are MCP tool calls:
add_memory({"text":"Prefers short answers.","categories":["user_preferences"]})returns the memory's ID (or the existing one for a duplicate).get_memory({"memory_id":""})reads it back from the store.- Restart the bridge with the same credentials, connect a new client and call
get_memoryagain: memories persist across sessions. update_memory({"memory_id":"","text":"Prefers short answers with examples.","expected_rev":1})corrects it in place (same ID, topic and categories).expected_revis therevfrom your read; if the memory changed since, nothing is written.delete_memory({"memory_id":""})removes it.
Topics
A topic groups the memories about one subject, and the user sees it under Topics and on the Map in the Decoy app.
list_topics({"query":"kitchen"})lists the topics this connection can read, in the shape shown in the worked example. When the connection can read accounts it also lists them underaccounts, so an agent finds an account's name without calling a tool that reads secrets: the first 8 characters of the account'sid, itsnameasapp_idtakes it, and itssite.nameis the account's service name, or else its label; an account with neither is named by its site, or asAccountand the first 8 characters of its id.siteis a host name and nothing more (no path, no port), and it is there only when the address saved on the account (its site, or else its login address) is a web address or a bare host whose host has a dot, only the letters a-z, digits and hyphens, and a last part that is 2 to 24 letters (or punycode,xn--…); any other saved value, an IP address included, is left out. No address, user name or secret of an account is in the list, and nothing else about it. At most 50 accounts are listed, by name;accounts_morecounts the rest, andquerynarrows topics and accounts alike. A name is shown on one line, cut at 200 characters;typeis one of the known types,""(none) ornull. A topic is readable when its own row is, or any memory filed under it is.linksays how the topic is connected: from"you", or from a parent topic ("from":"Kitchen renovation","from_id":"topic:"), with the relation as it was written. It is there only when this connection can read that relation (it always can for a topic it created); otherwise it is left out, never guessed. A relation another agent wrote carries"by":"another agent"before it. A topic that other listed topics hang under also carriessub_topics(how many).add_memorywithtopicreuses a readable topic with that name (case, spacing and surrounding quotes are ignored; the oldest wins) or creates it, linked from the user unlesstopic_linksays otherwise:relationis what is true and specific for this person and subject, andtonames the existing topic the new one is part of.topic_linkapplies when the topic is created (set_topic_parent moves it later); left out, the relation is "is interested in" from the user ("includes" under a parent topic). When a topic is created from the user with norelation, the result'stopiccarriesrelation_defaulted: trueandnextsays to name the relation when creating a topic;update_memorysays the same when it creates the topic. The topic, its link and the memory are saved in one request. The result addstopic: {id, name, created}and, for each memory,filed(where it landed),categoriesandrev.update_memory({"memory_id":"","topic":"Kitchen renovation"})files an existing memory under a topic (same ID);"topic": nullfiles it back under the user;categoriesreplaces its categories. A memory has one topic. Its result carriesfiledtoo.filedsays where a memory is, in everyadd_memoryandupdate_memoryresult, beforetopic:{"under":"account","id","name"}(linked to that account),{"under":"topic","id","name"}withparentwhen that topic hangs under another, or{"under":"user"}(a fact about you, under neither). A memory linked to an account has"topic": null;filedis what says it is linked.search_memoriesandget_memoriestaketopic(a name ortopic:), and every memory they return carriestopic: {id, name, type}(or null) andrev.list_topicsalso carriessuggested_relations: the relation words already used between the topics this connection can read, most used first (at most 10, the two default relations left out). Reuse one when it is true.read_topic({"topic":"Kitchen renovation","depth":1})reads one topic and what is around it:topic(id, name, type, memories, mine),parent(thelinklist_topics shows),children(the topics under it, each with its relation),connections(every other link, withdirectioninoroutread from this topic, and the other end: a topic, or"you") andsuggested_relations.depth2 or 3 addsnearby: the topics that many steps away, each once, withdistance,via(the topic it was reached through) and the relation (at most 50;nearby_morecounts the rest). Names and counts only, never a memory's text; only topics this connection can read are named.list_duplicate_topics({})lists pairs of readable topics whose names look like the same subject, the older one asa:same_name(the same words once case, spacing, punctuation, accents and plurals are set aside) orword_overlap(every word of the shorter name is in the longer one, at least two). A topic hung under the other is not its duplicate. At most 25 pairs;cappedsays when there are more. It changes nothing and never merges: read each side withread_topic, and ask the person before reorganising.- A save that creates a topic whose name looks like one this connection can read carries
similar_topics(id, name, reason). The memory is saved all the same. - Changing the web takes
memory.editon every topic a new link touches (memory.saveis enough for topics the connection saved), andmemory.deleteon every topic a removed link touches; reading a topic is not enough. A refusal writes nothing and names the onerequest_accesscall; an agent asks for it only when the change is part of what the person asked for. Each change answers withnow: the topics it touched, asread_topicshows them (withchildrencounted). connect_topics({"from":"Sam Sample","to":"Garden shed project","relation":"is helping with"})adds one link between two topics, or between"you"and a topic. The same link (same direction, same words, case and spacing aside) is never written twice. It needsmemory.savetoo, and at most 30 are added in one session. Withcall, each run checks the count the session had when it started, so runs of one session made at the same time can each add one link past it.disconnect_topics({"from":"Sam Sample","to":"Garden shed project"})removes one. When several links go fromfromtotoit removes none and lists them (matches): call again withrelation. A topic's parent link is never removed here.set_topic_parent({"topic":"Shed roof","parent":"Sam Sample","relation":"is looking after"})moves a topic under another topic, or under"you". It needsmemory.saveandmemory.editon the topic and the parent it goes to. The new link is written first and marked as the parent; then the old one is removed (old_link: "removed"), which takesmemory.deleteon the topic and the parent it leaves. Without that, or when Decoy does not remove it, the old link stays as a plain connection ("kept_as_connection", with anotenaming the ask and thedisconnect_topicscall). Never under itself or a topic below it.move_memories({"memories":[{"memory_id":"","expected_rev":3}],"topic":"Kitchen renovation"})files up to 50 existing memories under an existing topic, in place, each asupdate_memorywould (same rules,expected_revfrom your read). One refused does not stop the others:moved,unchanged(already there) andrefused(each with its reason). Nothing moved is an error. It never creates a topic.
Memories linked to an account
app_id links a memory to an account. It takes the account's name exactly as list_topics shows it under accounts, or the account's ID (the start of the ID as shown there is enough when only one account's ID starts that way). The result's filed then has "under":"account". Who reads a memory linked to an account:
- agents granted the memories about that account (
acctmem.readon it, or on every account); the account's details (account.read) do not bring them; - agents granted all memories, or one of the memory's categories (
memory.read); - you.
…(正文过长,页面只展示前面部分,完整内容见仓库)
