先看清边界，再连接 AgentSee the boundary before you connect an agent
MCP 通道是纯本地的：NovaraMCP.exe 不把数据发往任何地方。但接入云端托管的 AI 客户端时，客户端可能把读取结果发给你选择的模型服务商——那是 AI 客户端的责任边界，Novara 侧的脱敏与审计始终生效。
The MCP channel is purely local: NovaraMCP.exe never sends data anywhere. But when a cloud-hosted AI client is connected, that client may forward what the assistant reads to the model provider you chose — that is the AI client's responsibility boundary; redaction and audit on the Novara side always apply.
开始之前需要三件事：Novara 正在运行且数据库已解锁；设置页的 MCP 接口已开启；你已从 MCP 卡片拿到访问令牌。
Three things are needed before starting: Novara is running with the database unlocked; the MCP interface is enabled in settings; and you have the access token from the MCP card.
| AI 助手能做 | AI 助手不能做 |
|---|---|
| 在授权范围内新建、更新、读取条目 | 绕过隐私锁读取锁定内容 |
| 跨区搜索（敏感字段自动脱敏） | 读取密码、密钥等敏感字段明文 |
| 删除条目（双层闸放行后） | 未经批准的任何连接 |
| 被完整审计（含被拒绝的尝试） | 由 Novara 通道把数据发往网络 |
| An agent can | An agent cannot |
|---|---|
| Create, update and read entries within granted scope | Bypass the privacy lock to read locked content |
| Search across areas (sensitive fields auto-redacted) | Read plaintext of passwords, keys or other sensitive fields |
| Delete entries (once the double gate allows) | Connect without your approval |
| Be fully audited (denied attempts included) | Send data to the network through the Novara channel |
怎么用这篇
How to read this guide
- First time connecting an agent → start with Enable and authorize a client.
- Wondering what an agent can touch → see the permission matrix and the 14 tools.
- Something misbehaves after connecting → jump straight to MCP troubleshooting.
MCP 是什么，不是什么What MCP is — and is not
一句话定位
In one sentence
MCP（Model Context Protocol）是给 AI 助手用的标准接口。Novara 的实现是纯本地的：NovaraMCP.exe 以 stdio JSON-RPC 与 Agent 通信，经命名管道转发给运行中的 Novara 主进程——本机进程操作本机数据，零云、零外发。
MCP (Model Context Protocol) is a standard interface for AI assistants. Novara's implementation is purely local: NovaraMCP.exe speaks stdio JSON-RPC with the agent and forwards to the running Novara process over a named pipe — a local process operating on local data, zero cloud, zero outbound.
它不是"Novara 内置云模型"，也不接任何在线 AI 服务。模型跑在哪里是 Agent 自己的事；Novara 只负责在本地门禁之后交出（或拒交）数据。
It is not a "built-in Novara cloud model" and connects to no online AI service. Where the model runs is the agent's own business; Novara only hands over (or refuses) data behind its local gate.
它能帮 Agent 做什么
What it lets an agent do
- 记东西：新建/修改备忘、待办、便签、日记与路径条目，直达对应数据区。
- 找东西：跨五个数据区的列表与全文搜索，结果带掩码。
- 读全文：单条内容完整读取，敏感字段自动脱敏为
****。 - 整理：在授权范围内删除条目（需删除双层闸），软删除进回收站。
- Capture: create and edit memos, to-dos, notes, journals and path entries, straight into their data areas.
- Find: list and full-text search across the five data areas, results masked.
- Read in full: one entry at a time, with sensitive fields redacted to
****. - Organize: delete entries within granted scope (the delete double gate); soft-deleted items go to the trash.
| AI 助手能做 | AI 助手不能做 |
|---|---|
| 在授权范围内新建、更新、读取条目 | 绕过隐私锁读取锁定内容 |
| 跨区搜索（敏感字段自动脱敏） | 读取密码、密钥等敏感字段明文 |
| 删除条目（客户端权限位 + 全局总闸同时放行） | 未经批准的任何连接 |
| 被完整审计（含被拒绝的尝试） | 由 Novara 通道把数据发往网络 |
| An agent can | An agent cannot |
|---|---|
| Create, update and read entries within granted scope | Bypass the privacy lock to read locked content |
| Search across areas (sensitive fields auto-redacted) | Read plaintext of passwords, keys or other sensitive fields |
| Delete entries (client permission bit + global master switch) | Connect without your approval |
| Be fully audited (denied attempts included) | Send data to the network through the Novara channel |
数据边界
The data boundary
NovaraMCP.exe 绝不把数据发往任何地方。若你接入的是云端托管的 AI 客户端，助手读到的数据可能由该 AI 客户端发往你所选的 AI 服务商——这由 AI 客户端控制，而非 Novara。介意的话，选本地模型客户端。
NovaraMCP.exe never transmits data anywhere. If you connect a cloud-hosted AI client, the data the assistant reads may be sent by that client to the AI provider you chose — controlled by the AI client, not by Novara. If that concerns you, use a local-model client.
MCP 和互联同步是什么关系
MCP and encrypted sync
两条互不相干的通道：MCP 是本机 Agent 的读写通道（不联网、不经任何服务器）；互联同步是跨设备的密文同步（需要你自己部署服务端）。只在本机用 Novara + AI 助手，完全不需要部署同步服务端；反过来，部署了服务端也不等于开启了 MCP。
Two unrelated channels: MCP is the local agent's read/write channel (no network, no server involved); encrypted sync is cross-device ciphertext sync (needs a server you deploy). Running Novara with a local AI assistant requires no sync server at all — and deploying a server says nothing about whether MCP is on.
开启与客户端授权Enable and authorize a client
开启总开关
Turn on the master switch
- 打开 MCP 卡片设置 → MCP 接口 → 展开。
- 开启并拿令牌开启时自动生成访问 token（Base64Url，32 字节），从卡片复制。
- 授权 Agent 进程把要授权的 Agent 可执行文件路径加入白名单。身份以操作系统解析的进程映像路径为准——自己报的名字只作交叉核对，防伪造。
- 按需调整权限矩阵新授权的客户端默认只给非备忘四分区的只读；备忘读取默认拒绝，因为密码库是头号外泄目标。
- Open the MCP cardSettings → MCP interface → expand.
- Enable and take the tokenEnabling generates an access token automatically (Base64Url, 32 bytes); copy it from the card.
- Authorize the agent processAdd the agent executable's path to the whitelist. Identity is based on the process image path resolved by the operating system — a self-reported name is only cross-checked, to prevent spoofing.
- Adjust the permission matrix as neededA newly authorized client gets read-only on the four non-memo areas by default; memo reads are denied by default — the password vault is the number-one exfiltration target.
隐私锁锁定时，Agent 无法绕过解锁读到任何内容——库加密着、会话不存在，MCP 只会得到拒绝。这是设计底线，不是可选行为。
While the privacy lock is engaged, an agent cannot bypass the lock to read anything — the vault is encrypted, no session exists, and MCP simply receives refusals. A design baseline, not an optional behavior.
把 NovaraMCP.exe 接入客户端
Wire NovaraMCP.exe into your client
任何支持 MCP 的客户端（如桌面 AI 助手）都可以通过 mcpServers 配置启动 NovaraMCP.exe。令牌可通过参数或环境变量传入：
Any MCP-capable client (such as a desktop AI assistant) can launch NovaraMCP.exe through its mcpServers configuration. The token can be passed as an argument or through an environment variable:
{
"mcpServers": {
"novara": {
"command": "NovaraMCP.exe",
"args": ["--token", "YOUR_TOKEN_HERE"]
}
}
}或通过环境变量：
Or through an environment variable:
{
"mcpServers": {
"novara": {
"command": "NovaraMCP.exe",
"env": {
"NOVARA_MCP_TOKEN": "YOUR_TOKEN_HERE"
}
}
}
}首次连接与批准
First connection and approval
任何客户端进程首次连接时，Novara 会弹出授权提示。批准后即进入该客户端的权限矩阵——读 / 建 / 改 / 删 × 五类数据共 20 位权限格。新客户端除备忘外默认只读；此后你可以随时按客户端放权（删除列还需全局总闸放行）。
On first connection, any client process triggers an approval prompt in Novara. Once approved, it enters that client's permission matrix — read / create / update / delete × five data areas, 20 bits total. A new client is read-only everywhere except memo by default; you can grant more per client at any time (the delete column also needs the global master switch).
令牌校验走固定时间比较；客户端的每次调用（含被拒绝的尝试）都写入本机审计日志。
Token verification uses constant-time comparison; every call the client makes (denied attempts included) lands in the local audit log.
权限矩阵The permission matrix
每个客户端一张独立的矩阵
One independent matrix per client
每个被授权的客户端拥有独立的 20 位权限：5 个数据区 × 读 / 建 / 改 / 删。
Each authorized client holds an independent 20-bit permission set: 5 data areas × read / create / update / delete.
| 数据区 | 读 | 建 | 改 | 删 |
|---|---|---|---|---|
| 备忘（账号 / 密钥） | 默认拒绝 | 可给 | 可给 | 双层闸 |
| 文件路径 | 默认允许 | 可给 | 可给 | 双层闸 |
| 待办 | 默认允许 | 可给 | 可给 | 双层闸 |
| 便签 | 默认允许 | 可给 | 可给 | 双层闸 |
| 日记 / 文档 | 默认允许 | 可给 | 可给 | 双层闸 |
| Data area | Read | Create | Update | Delete |
|---|---|---|---|---|
| Memo (accounts / keys) | Denied by default | Grantable | Grantable | Double gate |
| File paths | Allowed by default | Grantable | Grantable | Double gate |
| To-dos | Allowed by default | Grantable | Grantable | Double gate |
| Notes | Allowed by default | Grantable | Grantable | Double gate |
| Journal / documents | Allowed by default | Grantable | Grantable | Double gate |
- 删除是双层闸：客户端的删除权限位 且 全局"删除总开关"必须同时打开，缺一个都删不了。
- 跨区搜索要求全部五区可读：
list/search不指定类型时需要五区全读权限，避免混合结果泄露无权分区。 - 越权尝试会被拒绝并写入审计日志。
- Delete is a double gate: the client's delete permission bit and the global "deletion master switch" must both be on; either missing, nothing is deleted.
- Cross-area search requires all five areas readable:
list/searchwithout a type filter needs read on all five, so mixed results cannot leak an unauthorized area. - Overreach attempts are refused and written to the audit log.
14 个工具The 14 tools
工具参考
Tool reference
| 工具 | 做什么 |
|---|---|
create_memo / update_memo | 新建 / 修改备忘条目（不能篡改已有敏感字段，可新增） |
create_todo / update_todo | 新建 / 修改待办卡片（改子待办列表会整体重建，勾选状态重置） |
create_note / update_note | 新建 / 修改便签卡片 |
create_diary / update_diary | 新建 / 修改日记与文档（HTML 会经白名单净化；格式不可改） |
create_path / update_path | 新建 / 修改路径备份条目 |
list_items | 列出条目摘要（不含正文、不含回收站） |
read_item | 读取单条全文（敏感字段已脱敏） |
search_items | 全类型全文搜索（排除回收站） |
delete_item | 软删除进回收站（需删除权限双层闸开启） |
| Tool | What it does |
|---|---|
create_memo / update_memo | Create / edit memo entries (existing sensitive fields cannot be altered; new ones can be added) |
create_todo / update_todo | Create / edit to-do cards (editing the sub-task list rebuilds it as a whole; check states reset) |
create_note / update_note | Create / edit note cards |
create_diary / update_diary | Create / edit journals and documents (HTML passes an allowlist sanitizer; the format cannot be changed) |
create_path / update_path | Create / edit path entries |
list_items | List entry summaries (no bodies, no trash) |
read_item | Read one entry in full (sensitive fields redacted) |
search_items | Full-text search across all types (trash excluded) |
delete_item | Soft delete into the trash (requires the delete double gate) |
调用长什么样
What a call looks like
Agent 侧的调用形如：
On the agent side, calls look like:
# 新建一个备忘
create_memo { "name": "OpenAI", "type": "API Key", "keyInfo": "https://api.openai.com/v1", "fields": [{ "label": "API Key", "value": "sk-...", "canCopy": true }] }
# 列出所有待办
list_items { "type": "todo" }
# 搜索 "project"
search_items { "query": "project" }脱敏与审计Redaction and audit
敏感字段怎么脱敏
How sensitive fields are redacted
- 密码、CVV、API Key、卡号、证件号等敏感字段对 Agent 一律返回
****，不因任何参数关闭。 - 脱敏按标签匹配：
密码、password、密钥、secret、token、key、api key、apikey、api_key、passwd，并防止改名绕过脱敏。 - 搜索不读取敏感字段值——拿卡号片段当关键词搜不出东西，这是设计不是搜索质量差。
- Sensitive fields — passwords, CVV, API keys, card and ID numbers — always return
****to the agent, never disabled by any parameter. - Redaction matches by label:
密码,password,密钥,secret,token,key,api key,apikey,api_key,passwd— with protection against relabeling-based extraction. - Search never reads sensitive field values — searching a card-number fragment finds nothing; that is design, not weak search.
审计记什么
What the audit records
- 每次调用写入审计：谁（进程）、何时、什么工具、什么对象、结果（允许 / 脱敏 / 拒绝）——包括被拒绝的尝试。入口在设置页 MCP 卡片的授权面板下。
- 字段限长，凭据形态的值一律掩码；令牌与密钥明文永远不进审计。
- 日志落在本机
logs\目录，不外发。
- Every call is audited: who (process), when, which tool, which object, the result (allowed / redacted / denied) — denied attempts included. The log sits in the authorization panel under the MCP card in settings.
- Fields are length-capped and credential-shaped values are masked; token and key plaintext never enter the audit.
- Logs stay in the local
logs\directory and never leave the machine.
MCP 症状速查MCP troubleshooting
用之前
Before you start
- 先分清症状在哪一层：客户端连不上（握手失败），还是连上了但请求被拒（权限/门控）。
- 所有拒绝都会写进审计日志——设置 → MCP 卡片 → 授权面板下方，先看最近一条被拒记录再对症。
- First locate the layer: the client cannot connect (handshake fails), or it connects but requests are refused (permissions / gating).
- Every denial lands in the audit log — Settings → MCP card → below the authorization panel. Read the latest denied record before anything else.
症状表
Symptom table
| 症状 | 原因 | 处理 |
|---|---|---|
| 客户端连不上 / 调用全部失败 | MCP 总开关没开，或令牌不对，或进程不在白名单 | 设置 → MCP 卡片：确认总开关、复制令牌、把客户端可执行文件加入白名单 |
| 一切请求都被拒绝 | 数据库未解锁（隐私锁锁定中） | 解锁 Novara 后重试——锁定时拒绝一切是设计底线 |
| 读不到备忘数据 | 备忘读取默认拒绝 | 在权限矩阵里对该客户端显式放行备忘读取 |
| 删除总是不生效 | 删除双层闸没有同时打开 | 打开该客户端的删除权限位 且 全局删除总开关 |
| 搜索找不到含密码的条目 | 敏感字段不参与搜索 | 按条目名称、账号或备注搜索——这是设计不是故障 |
| 想断开某个 Agent | — | 重置 Key（所有 Agent 失效，需重新分发令牌）或在授权面板移除该客户端 |
| Symptom | Cause | Fix |
|---|---|---|
| Client cannot connect / every call fails | The MCP master switch is off, the token is wrong, or the process is not whitelisted | Settings → MCP card: confirm the switch, copy the token, add the client executable to the whitelist |
| Every request is refused | The database is not unlocked (privacy lock engaged) | Unlock Novara and retry — refusing everything while locked is by design |
| Memo data cannot be read | Memo reads are denied by default | Explicitly grant memo reads to that client in the permission matrix |
| Deletes never take effect | The delete double gate is not fully open | Enable the client's delete bit and the global deletion master switch |
| Search finds nothing with a password field | Sensitive fields are excluded from search | Search by entry name, account or notes — design, not a malfunction |
| I want to disconnect an agent | — | Reset the key (every agent is invalidated; re-issue tokens) or remove the client in the authorization panel |
常见问题FAQ
Agent 能把我的密码读走吗？
拿不到明文。敏感字段按标签规则脱敏为 ****；备忘区读取默认拒绝、需显式授权；还有全程审计。防线可以叠，但没有一条是"信任 Agent"式的。
云端 AI 客户端会把我的数据发给模型服务商吗？
NovaraMCP.exe 本身零外发；但云端托管的 AI 客户端可能把助手读到的内容发给其模型服务商——由该客户端决定，Novara 无法替外部服务改变其隐私行为。介意就用本地模型客户端。
关掉 MCP 总开关会怎样？
所有调用立即被拒；已授权的进程列表与权限矩阵保留，重新打开即恢复。重置 Key 则会让所有已配置的 Agent 失效，需要重新分发 token。
MCP 和互联同步要一起用吗？
不需要，两者完全独立：MCP 是本机 Agent 的读写通道，互联同步是跨设备的密文同步。只在本机用 Novara + AI 助手，完全不需要部署服务端。
Can an agent read my passwords?
Not the plaintext. Sensitive fields are redacted to **** by label rules; memo reads are denied by default and need explicit authorization; everything is audited. The defenses stack — none of them is "trust the agent".
Will a cloud AI client send my data to a model provider?
NovaraMCP.exe itself sends nothing; but a cloud-hosted AI client may forward what the assistant read to its model provider — that is decided by the client, and Novara cannot change an external service's privacy behavior. If it concerns you, use a local-model client.
What happens when I turn the MCP master switch off?
All calls are refused immediately; the authorized process list and permission matrix are kept and return when you switch it back on. Resetting the key invalidates every configured agent until tokens are re-issued.
Do MCP and encrypted sync need each other?
No — they are entirely independent: MCP is the local agent's read/write channel, encrypted sync is cross-device ciphertext sync. Using Novara with a local AI assistant needs no sync server at all.
继续阅读Keep reading
- Want to inspect the agent's overall security boundary → security boundaries (inside the sync guide)
- Do not have Novara yet → the daily usage guide
- Want your data on the phone → the encrypted sync guide or the secure snapshot guide