Windsurf Integration

Windsurf’s Cascade assistant connects to MCP servers defined in ~/.codeium/windsurf/mcp_config.json. The Agent Receipts proxy wraps any MCP server transparently — Windsurf doesn’t know or care that the proxy is there.

Prerequisites

mcp-proxy installed
agent-receipts-daemon installed, initialised, and running — it holds the signing key and writes every receipt
Windsurf installed
The MCP server you want to audit. The examples below wrap GitHub’s official MCP server:
Terminal window
```
brew install github-mcp-server
```
This puts a github-mcp-server binary on your $PATH. Verify with which github-mcp-server.

Start the daemon

The proxy holds no signing key of its own — agent-receipts-daemon owns the key and writes every receipt (ADR-0010). Initialise the key once and start the daemon before launching Windsurf:

agent-receipts-daemon --init   # one-time: generates the Ed25519 signing key pair
agent-receipts-daemon          # start the daemon (listens on a Unix socket)

The proxy reaches the daemon over its default platform socket automatically. See Daemon Setup for install options and socket paths.

Configure mcp_config.json

In the Cascade panel, open the MCP/plugins controls and choose View raw config to open ~/.codeium/windsurf/mcp_config.json (you can also edit the file directly). The format uses a top-level mcpServers key.

Windsurf launches MCP servers without your shell’s PATH, so use absolute paths. Print them first:

echo "op:     $(which op)"
echo "proxy:  $(which mcp-proxy)"
echo "server: $(which github-mcp-server)"

Recommended: secret manager (`op run`, `aws-vault exec`, …)

Install the 1Password CLI (brew install 1password-cli), sign in (op signin), and create a referenced env file:

# ~/.local/share/agent-receipts/mcp.env  (chmod 600)
GITHUB_PERSONAL_ACCESS_TOKEN=op://Personal/GitHub/token

Point Windsurf at op run — it resolves the op:// reference at exec time and injects the value into mcp-proxy’s env without writing it to mcp_config.json:

{
  "mcpServers": {
    "github-audited": {
      "command": "/opt/homebrew/bin/op",
      "args": [
        "run",
        "--env-file=/Users/YOU/.local/share/agent-receipts/mcp.env",
        "--",
        "/Users/YOU/go/bin/mcp-proxy",
        "-name", "github",
        "-issuer-name", "Windsurf",
        "-operator-id", "did:web:windsurf.com",
        "-operator-name", "Windsurf",
        "/opt/homebrew/bin/github-mcp-server", "stdio"
      ]
    }
  }
}

aws-vault exec, chamber exec (AWS Parameter Store), and direnv with op:// references all follow the same wrapping pattern.

Fallback: OS keychain launcher script

If you don’t have a secret manager, reuse the launcher script from Claude Desktop’s keychain fallback (one script works across clients). Point command at the launcher and drop the env block — the script sets GITHUB_PERSONAL_ACCESS_TOKEN from the keychain:

{
  "mcpServers": {
    "github-audited": {
      "command": "/Users/YOU/.local/share/agent-receipts/run-mcp-proxy-github.sh",
      "args": [
        "-name", "github",
        "-issuer-name", "Windsurf",
        "-operator-id", "did:web:windsurf.com",
        "-operator-name", "Windsurf",
        "/opt/homebrew/bin/github-mcp-server", "stdio"
      ]
    }
  }
}

-issuer-name, -operator-id, and -operator-name stamp each signed receipt so you can tell which client made a given call when reviewing a shared store — setting -issuer-name to Windsurf here (and to Claude Code, Codex, etc. in the other guides) is what distinguishes them at audit time.

Back in the Cascade MCP panel, click Refresh so Windsurf re-reads the config. The github-audited server should appear with the tools the proxied server exposes; use it from Cascade.

Verifying receipts

The daemon signs and stores every tool call. After making calls through Windsurf, query and verify the store with the agent-receipts CLI (installed alongside the daemon). It opens the database read-only, so it is safe to run while the daemon is writing:

# List recent receipts (newest first)
agent-receipts list

# Verify the chain's signatures and hash links
agent-receipts verify \
  --public-key ~/.local/share/agent-receipts/signing.key.pub

$ agent-receipts list
SEQ  TIMESTAMP             CHAIN    TOOL / ACTION TYPE
4    2026-04-24T02:05:19Z  default  get_file_contents
3    2026-04-24T01:58:45Z  default  create_or_update_file
2    2026-04-24T01:56:12Z  default  search_issues
1    2026-04-24T01:45:07Z  default  list_issues

agent-receipts verify prints Chain default: VALID (4 receipts) when signatures and hash links are intact. Inspect a single receipt — including its action type, risk level, and parameters hash — with agent-receipts show <seq>. See the CLI reference for all subcommands.

Gotchas

Absolute paths required. Windsurf launches MCP servers with a clean PATH. Use the full path to op/mcp-proxy (find each with which) and the full path to the wrapped server binary.

Refresh after editing. Windsurf reads mcp_config.json on demand — after editing the file, click Refresh in the Cascade MCP panel rather than expecting a live reload.

Keep the toolset focused. Windsurf exposes a bounded number of MCP tools to Cascade at once; wrapping a server through the proxy doesn’t change its tool count, but if you proxy several large servers, disable the ones you aren’t using so Cascade sees the tools that matter.

No receipts appearing? The daemon must be running before Windsurf starts the proxied server, or emits fail. Confirm with pgrep agent-receipts-daemon, and see the daemon troubleshooting guide. If you run the daemon on a non-default socket, set AGENTRECEIPTS_SOCKET for both the daemon and the proxy.

Want human-in-the-loop approvals? Opt in with -http. The approval listener is off by default. Add -http 127.0.0.1:<port> to args and run an approver — see Approval Server. Without it, a paused call fails immediately with -32003.