Windsurf

Windsurf’s Cascade agent reads MCP servers from a single user-level config file. Drop Engram in, hit Refresh in the MCP panel, and OAuth runs in your browser the first time Cascade reaches for it. Protocol background lives at MCP.

Prerequisites

Before you start, confirm:

• You have an Engram account at app.engram.page.
• At least one vault is synced. Open the Obsidian plugin or the web app and confirm notes have synced within the last day.
• You can sign in via browser. The MCP auth flow opens a browser window.

Endpoint

https://mcp.engram.page/api/mcp

Setup

1. Open the config. In Cascade, click the MCPs icon (top-right of the panel), then View raw config. That opens ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows).

2. Add the engram entry. Cascade uses serverUrl for the HTTP transport, not url:

{
  "mcpServers": {
    "engram": {
      "serverUrl": "https://mcp.engram.page/api/mcp"
    }
  }
}

3. Refresh. Save the file, then click Refresh in the MCPs panel. A full Windsurf restart isn’t required unless the panel stays stuck.

First-run auth

The first time Cascade invokes an Engram tool, your browser opens to sign in to Engram and approve the connection. Cascade stores the token and reuses it from there on. The grant is the full mcp scope. Granular per-action scopes are on the roadmap.

To skip OAuth, swap in an API key via a headers block:

{
  "mcpServers": {
    "engram": {
      "serverUrl": "https://mcp.engram.page/api/mcp",
      "headers": { "Authorization": "Bearer ${env:ENGRAM_API_KEY}" }
    }
  }
}

Get a key at app.engram.page/settings/api-keys.

Cascade rules

Add the snippet below to your Windsurf Workspace AI Rules (the Cascade Rules pane) for project-level guidance, or to ~/.codeium/windsurf/memories/global_rules.md for user-wide rules.

Engram holds my personal notes — treat it as your long-term memory of me. Search it when a question depends on context I might have shared before. Before saving or updating a note, ask first.

Try it

In Cascade, ask:

• Search my vault for notes about the engineering interview process and summarize the top three.
• Find anything I wrote about embeddings in the last month.

Cascade calls Engram’s search (or get_note, write_note, etc.) tool, pulls back results, and answers in-context. If the tool fires, you’re set.

Troubleshooting (Windsurf specific)

• “Tool count exceeded 100” warning. Cascade has a hard cap on active MCP tools. Toggle off unused servers or tools in the MCPs panel.
• New engram entry doesn’t show up after saving. Hit Refresh in the MCPs panel rather than just saving the file. If it still doesn’t appear, open Developer: Show Logs → Windsurf and check for a JSON parse error.
• HTTP 401 loop on enterprise builds. Your org’s MCP allowlist may block third-party servers. Ask an admin to add engram to the allowed server registry.

For cross-client failures, see Troubleshooting.

Revocation

To disconnect Windsurf from Engram:

1. In Windsurf, find the connector or MCP server entry and remove it.
2. In Engram, open your account → API Keys & Sessions and revoke the matching session.
3. The OAuth token is invalidated server-side. Windsurf will need to re-authenticate to reconnect.

To drop it client-side, delete the engram entry from mcp_config.json and click Refresh in the MCPs panel.

Next steps

MCP Protocol overview.

Scopes What the grant covers.

All integrations Pick a different client.