Symbol Bridge

Do I Need This?Copy Anchor Link

Most users don't need Symbol Bridge. The standard Symbol MCP handles everything: saving capsules, loading context, searching, and more.

You need Symbol Bridge if you want either of these:

• Local file attachments: attach files stored on your computer to a capsule (logs, screenshots, config files, etc.)
• End-to-end encrypted capsules: read and decrypt encrypted capsules locally, so plaintext never leaves your machine

If you're saving text-based context and don't use encryption, skip this page.

What is Symbol Bridge?Copy Anchor Link

Symbol Bridge is a small companion tool that runs locally on your computer. It runs alongside the main Symbol MCP; you keep both connected at the same time.

It adds these tools to your AI assistant:

File attachments (its reason to exist):

• Create a capsule with attachments: save a capsule and attach files from your computer in one step
• Update a capsule with attachments: add files to an existing capsule

Reading, in every encryption setting:

• Read a capsule by id or by ref, and list your capsules, Types, workspaces, projects, and collections
• Search, load a project's or a Type's context, and open a shared capsule
• Each read returns the same information the hosted Symbol MCP would
• Capsule and listing reads answer from the local copy, including listings filtered by field value, so they keep working while you're offline and each tells you whether it came from that copy or the server; search, context loads, and shared-capsule reads go to the server for a fresh answer

End-to-end encryption (E2EE), when you turn it on:

• Encrypted capsules are decrypted locally using your keys; plaintext is never sent to Symbol's servers or your AI provider
• A read only asks you to link keys when the capsule it's reading is actually encrypted; unencrypted capsules read without any key setup

The full per-mode tool list is in What Symbol Bridge serves below.

What Symbol Bridge servesCopy Anchor Link

These tools are added whatever your encryption setting.

Create / update a capsule with attachments: save a new capsule, or update an existing one, attaching files from your computer in the same step. This is the one thing only the Bridge can do: hosted Symbol servers cannot read files off your disk.

Bridge status: report what the Bridge resolved: whether an API key is held and where it came from, the config file's location and state, the folders it may read files from, the server it talks to, and whether a local copy is present and how fresh it is. It also shows whether the background refresh is running: while the Bridge is open it keeps the refresh alive, restarting it if it stops, so your local copy does not quietly go stale, and if it has to give up (for example a refresh that keeps failing) it says so and why. Read this first when something looks wrong; it needs no shell.

The reads below return the same information the hosted Symbol MCP returns. They are available with encryption off, on with keys, and on without keys. An encrypted capsule asks for keys, while everything else reads normally. (These tool names are shared with the hosted Symbol MCP, which is why they are documented on the main tools page.)

• Get a capsule by id or by @type/ref, and list your capsules, Types, workspaces, projects, and collections. The Bridge answers these from its local copy when it can, so they work offline, and each tells you whether it came from that copy or the server. A Type or capsule the copy hasn't caught up with, or a Type name that lives only in another workspace, is fetched from or confirmed with the server, so a read of something just created is correct rather than a stale "not found".
• Open a shared capsule from a share link, search your capsules, and load a project's or a Type's context as ready-to-use background. These go to the server for a fresh answer.

With encryption onCopy Anchor Link

Turning on encryption (see Turning on encryption) adds local decryption plus these tools.

Encryption status: check whether encryption is on and whether your keys are loaded, start the device-link flow to load them, finish it, or clear cached keys.

Get an encrypted capsule: a compatibility alias of get a capsule, kept for existing setups and saved prompts. Prefer get a capsule, which already decrypts locally when your keys are loaded.

Get an encrypted capsule by ref: the by-@type/ref alias of the same read.

List encrypted capsules: the alias of the capsule listing. Encrypted rows show a placeholder; open one with get an encrypted capsule to decrypt it locally.

Search encrypted capsules: the alias of search. Encrypted matches show a placeholder rather than decrypted snippets, since their content is not searchable on the server.

Load an encrypted Type's context: load every capsule in a Type as background, decrypting rows locally with your keys.

Load an encrypted project's context: the project-scoped alias of the same context load.

Open an encrypted shared capsule: the alias of open a shared capsule, decrypting it locally with your keys.

When both servers are connectedCopy Anchor Link

If you connect both Symbol Bridge and the hosted Symbol connector in the same assistant, the assistant reads through the Bridge on its own, so reads are fast and work offline, while writes and anything the Bridge does not offer still go to the hosted server. You do not have to tell it which server to use.

A few things make this work well:

• Pair them by deployment. Each tool names the Symbol deployment it serves (for example https://symbol.chat). The Bridge and the hosted connector pair up when they name the same one. A Bridge pointed at a different deployment (a development server, say) is a different account of data, so the assistant keeps the two apart rather than mixing them.
• Sign both in to the same account. The Bridge answers reads from a copy of whichever account it is signed in to. If the two are signed in to different accounts on the same deployment, reads come from the Bridge's account: its own rows, never anyone else's, but perhaps not the account you meant.
• Check where an answer came from. Every read the Bridge answers reports its source and the deployment it belongs to, so you can confirm a read came from the local copy and how fresh that copy is.
• The copy stays trustworthy. While the local copy is recent (synced within the last 30 minutes) it answers reads directly. Once it is older than that, a read checks the server first and uses the current answer when the server is reachable, falling back to the copy only when the server is down, overloaded or unreachable, so a copy whose sync has been failing for days is never silently served as current. When the machine is plainly offline, reads stay on the copy at once.

InstallationCopy Anchor Link

Symbol Bridge ships as a Claude Desktop extension bundle (.mcpb). There is no API key to paste. You approve the connection with your existing Symbol sign-in.

https://symbol.chat/download/symbol-desktop.mcpb

The Bridge console: sign in and choose foldersCopy Anchor Link

However you installed the Bridge, it runs a small management console on your own machine (a loopback address only you can reach). Open it to sign in, choose which folders the Bridge may attach files from, and add the Bridge to other AI tools, all from screens with no terminal or hand-edited file.

• Signing in. When the Bridge is not signed in, the first tool call opens the console sign-in screen in your browser. Approve the connection there with your existing Symbol sign-in, and the Bridge starts serving your account right away, with no API key and no restart. Every Bridge on your computer for the same Symbol server picks up that sign-in on its next tool call. Signing in again the same way is how you renew an expired or revoked sign-in.
• The screen opens once. The Bridge opens the sign-in screen by itself once, however many assistants or Bridges are running, and not again until you sign in. Later tool calls tell you it is already open instead of opening another tab. If you closed that tab, or no tab appeared, open the console link your assistant gives you in your browser and choose Open the sign-in screen, or choose Open Bridge console in the Symbol app.
• More than one Symbol server. The sign-in screen signs in to one Symbol server, which it names. A Bridge set up for a different server never opens it: its message tells you to sign in with symbol-bridge-login --server <server> or through the Symbol app instead.
• Choosing folders. The Folders screen lists the folders the Bridge may read from, lets you add or remove one by browsing your directories, and takes effect on the next attachment. File access stays off until you choose a folder.
• Adding other tools. The Add to your tools screen sets up Cursor, VS Code, Claude Code, Windsurf and Codex to use the Bridge, reusing this machine's sign-in with no API key written anywhere.

The Symbol app can open this console for you (Settings → Symbol Bridge). When the Bridge refuses a file because no folder is chosen, or needs you to sign in, it opens the right screen in your browser itself. Console links are private to your machine and are never shown to your AI assistant, so a plain console address opened by hand shows a button, such as Open the sign-in screen, that has the Bridge open that screen for you in a new tab.

Also use Claude Code, Cursor, Windsurf, or Codex?Copy Anchor Link

Each of these is a separate app with its own settings, so an extension installed in one doesn't show up in the others. The easiest way to add the Bridge to them is the console's Add to your tools screen: it points each tool at a shared local copy of the Bridge and reuses this machine's sign-in, with no terminal, no hand-edited config, no separate Node.js install, and no API key. Your sign-in carries over because the Bridge stores credentials per machine, not per app.

If you would rather wire it up by hand, see Manual Install below.

Manual Install (Cursor, Windsurf, Claude Code, and others)Copy Anchor Link

This is the by-hand path. Most people should use the console's Add to your tools screen instead (see The Bridge console above), which does all of this for you and writes no API key. Use the steps here only when you want to wire a client up yourself or pin a specific Node version.

The .mcpb above is Claude Desktop's extension format. Every other MCP client starts a local server itself, so you point it at the Bridge with a normal stdio config instead.

The .mcpb is a zip. Unpack it and you have a self-contained server file that any MCP client can run.

curl -L -o symbol-bridge.mcpb https://symbol.chat/download/symbol-desktop.mcpb
unzip symbol-bridge.mcpb -d ~/symbol-bridge

{
  "mcpServers": {
    "symbol-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/symbol-bridge/server/server.mjs"],
      "env": {
        "SYMBOL_API_KEY": "sym_your_key_here"
      }
    }
  }
}

Claude Desktop by handCopy Anchor Link

If you would rather edit JSON than open the .mcpb, Claude Desktop uses the same format. Settings → Developer → Edit Config opens the file, or edit it directly:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Turning on encryptionCopy Anchor Link

Encrypted-capsule reading is off unless you ask for it. Add to the same env block:

"env": {
  "SYMBOL_API_KEY": "sym_your_key_here",
  "SYMBOL_ENCRYPTION": "true",
  "SYMBOL_RECOVERY_KEY": "your-recovery-key"
}

SYMBOL_ENCRYPTION turns on local decryption of encrypted capsules (and adds the get_encrypted_* alias tools). It does not decide whether reads are offered: the Bridge reads capsules and listings in every mode, so with encryption off you still read your unencrypted capsules normally. An encrypted one tells you it needs keys. SYMBOL_RECOVERY_KEY (Settings → Encryption → Recovery Key in the Symbol app) is a break-glass path that lets the Bridge decrypt without the device-link flow. It derives your E2EE master key directly, so the Bridge warns loudly at startup when it is set and it is not part of the extension's default configuration. Prefer leaving it out and linking a device instead (you'll be prompted). See End-to-End Encryption.

Using File AttachmentsCopy Anchor Link

Once connected, you can ask your AI:

"Save this as a Solution and attach the file at /Users/me/logs/error.log"

The AI will use Symbol Bridge to read the file from your computer and attach it to the new capsule.

{ "attachmentDirs": ["/Users/me/Downloads", "/Users/me/Desktop"] }

TroubleshootingCopy Anchor Link

The extension installed but no attachment tools appear

Restart Claude Desktop, then check that you approved the connection prompt. If you dismissed it, remove the extension and open the .mcpb again.

The tool appears but can't read my files

First check that the file's folder is chosen on the console Folders screen (or listed in attachmentDirs in ~/.symbol/config.json, or SYMBOL_ATTACHMENT_DIRS). File access is deny-by-default, so with none chosen every read is refused and the Bridge opens the Folders screen in your browser. Then check the path is correct and the file exists. On Mac, right-click a file and choose Copy as Pathname to get the exact path.

Which Symbol tools should I see?

Symbol Bridge is a companion, not a full replacement for the hosted Symbol MCP. It adds the two attachment tools, the reads listed in What Symbol Bridge serves, and (with encryption on) local decryption plus the get_encrypted_* aliases. It does not add the write and management tools (creating Types, deleting, moving, sharing, stats), so keep the hosted Symbol MCP connected alongside it for those.

A read says it needs encryption keys

That capsule is end-to-end encrypted. With encryption on, follow the device-link prompt (Settings → Encryption → Link Symbol Bridge in the Symbol app), then retry. With encryption off, the message tells you to enable it first. Either way, only encrypted capsules ask for keys; unencrypted ones read without any of this.

The Bridge says it could not read the system keychain

The Bridge keeps your sign-in in your computer's keychain. If the keychain refused or could not answer, the Bridge does not ask it again until you restart your assistant or sign in again. Restart your assistant, and if your keychain asks for permission when the Bridge starts, allow it.

If this computer has no working keychain (for example a Linux machine with no keyring service running), keep the sign-in in a file instead. Add "tokenBackend": "file" under auth.oauth in ~/.symbol/config.json, keeping everything else already in the file:

{
  "auth": {
    "oauth": { "tokenBackend": "file" }
  }
}

Then restart your assistant and sign in again. The file must stay valid JSON, or the setting is ignored. The setting applies to every Symbol Bridge on this computer, which then keeps its sign-in in an owner-only file in ~/.symbol/. Every Symbol Bridge on the computer must be on this release or later for the setting to take effect. Where the keychain works, prefer it: it is the more secure place for your sign-in.

Manual install: the server never starts

Almost always the path. MCP clients require an absolute path to server/server.mjs. ~ and relative paths are not expanded. Check it runs on its own first:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | node /absolute/path/to/server/server.mjs

You should get a JSON list of tools. On Claude Desktop, the server's own error output is logged to ~/Library/Logs/Claude/mcp-server-symbol-bridge.log (macOS) or %APPDATA%\Claude\logs\ (Windows).

Manual install: my API key seems to be ignored

Run the bridge_status tool first. It reports whether a key is held, its source, and the config-file state, so you don't have to guess.

If you just added SYMBOL_API_KEY to your client config and the next call still fails with MISSING_KEY, the running server hasn't picked it up: environment variables are read once at startup, so reconnect/restart the Bridge (or add the key to ~/.symbol/config.json instead, which is re-read on the next call without a restart).

If the key is set but still ignored, check ~/.symbol/config.json. If auth.method is oauth, that wins over SYMBOL_API_KEY and the Bridge will look for OAuth tokens instead. Set it to apikey, or remove the field.