Windsurf

Config file location

macOS / Linux
Windows

~/.codeium/windsurf/mcp_config.json

%USERPROFILE%\.codeium\windsurf\mcp_config.json

Minimal configuration

{
  "mcpServers": {
    "isthmus": {
      "command": "isthmus",
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/mydb"
      }
    }
  }
}

Full configuration

{
  "mcpServers": {
    "isthmus": {
      "command": "isthmus",
      "args": ["--audit-log", "/tmp/isthmus-audit.ndjson"],
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/mydb",
        "SCHEMAS": "public,analytics",
        "POLICY_FILE": "/path/to/policy.yaml",
        "MAX_ROWS": "500"
      }
    }
  }
}

Verify

Save the config file
Restart Windsurf
Open the Cascade AI panel
Ask: “What tables are in my database?”

Troubleshooting

Binary not found

Use the full path to the binary. The location depends on how you installed:

Install script / prebuilt binary: /usr/local/bin/isthmus
go install: ~/go/bin/isthmus

"command": "/usr/local/bin/isthmus"

Find the path with which isthmus.

Config not picked up

Ensure the file is at exactly ~/.codeium/windsurf/mcp_config.json. Create the directory structure if it doesn’t exist. Restart Windsurf after changes.

Database unreachable

Test connectivity first:

DATABASE_URL="postgres://user:password@localhost:5432/mydb" isthmus --dry-run

Getting Started

Client Setup

Features

Security

Architecture

Config file location

Minimal configuration

Full configuration

Verify

Troubleshooting

​Config file location

​Minimal configuration

​Full configuration

​Verify

​Troubleshooting

Config file location

Minimal configuration

Full configuration

Verify

Troubleshooting