Symbol Bridge

Do I Need This?

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?

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 the following tools to your AI assistant:

File attachments:

• 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

End-to-end encryption (E2EE):

• Read and decrypt encrypted capsules locally using your encryption keys
• Plaintext is never sent to Symbol's servers or your AI provider

Installation

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

Also use Claude Code?

Claude Desktop and Claude Code are separate apps with separate settings, so an extension installed in one doesn't show up in the other. Adding it to Claude Code is a single command:

unzip ~/Downloads/symbol-desktop.mcpb -d ~/symbol-bridge
claude mcp add symbol-bridge -s user -- node ~/symbol-bridge/server/server.mjs

-s user makes it available in every project rather than just the current one. Your sign-in carries over — Bridge stores credentials per machine, not per app, so there's nothing to authorize again.

The same applies to Cursor, Windsurf, and anything else that speaks MCP; see Manual Install below.

Manual Install (Cursor, Windsurf, Claude Code, and others)

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 hand

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 encryption

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 exposes the encrypted read tools. 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 Attachments

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"] }

Troubleshooting

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 directory is listed in attachmentDirs (~/.symbol/config.json) or SYMBOL_ATTACHMENT_DIRS — file access is deny-by-default, so with none configured every read is refused. 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.

I only see the attachment tools, not the main Symbol tools

Symbol Bridge doesn't include the full set of Symbol tools — it only adds file attachments and local decryption. Connect the hosted Symbol MCP alongside it.

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.