MCP Install Recipes — Per-Client Setup Workflows

Copy-pasteable install workflows for connecting Palinode's MCP server to each supported AI coding assistant. Pick your client and follow the steps; each recipe is self-contained.

Already using Claude Code or Claude Desktop? See INSTALL-CLAUDE-CODE.md and the Claude Desktop section of MCP-SETUP.md — those clients are covered there.

Not sure which config file your client actually reads? Run palinode mcp-config --diagnose — it walks every known canonical path and reports which ones contain a palinode entry. See MCP-CONFIG-HOMES.md for the full reference.

Which transport should I use?

Transport	Config field	Use when
stdio	`"command": "palinode-mcp"`	Palinode is installed on the same machine as the IDE
Streamable HTTP	`"url": "http://host:6341/mcp/"`	Palinode runs on a remote server (homelab, VPS, dev box), or when multiple IDEs or team members share one instance

Use stdio if:

You ran pip install palinode on your laptop and want a single-user local setup.
which palinode-mcp prints a path.

Use HTTP if:

Palinode lives on a separate machine and you connect over a network.
Multiple IDEs or team members should share the same memory store.
You want to switch IDEs without re-configuring the server.

For HTTP setups, start palinode-mcp-sse on the server first (despite the name, it serves Streamable HTTP at /mcp/). Always include the trailing slash in the URL. Confirm the server is reachable before editing the IDE config:

curl http://your-server:6341/mcp/

1. Cursor

Docs verified: cursor.com/docs/context/mcp

Cursor reads MCP config from two locations — project-level takes precedence when both exist:

Scope	Path
Global (all projects)	`~/.cursor/mcp.json`
Project (this repo only)	`.cursor/mcp.json` in project root

Create the file if it does not exist. If it already exists, merge the "palinode" entry into the existing "mcpServers" object.

stdio (local install)

{
  "mcpServers": {
    "palinode": {
      "command": "palinode-mcp",
      "env": {
        "PALINODE_API_HOST": "127.0.0.1",
        "PALINODE_API_PORT": "6340"
      }
    }
  }
}

HTTP (remote server)

{
  "mcpServers": {
    "palinode": {
      "type": "http",
      "url": "http://your-server:6341/mcp/"
    }
  }
}

Replace your-server with your server's hostname or IP (for example localhost:6341 for a local HTTP server or a stable hostname for remote). palinode-mcp-sse serves streamable-HTTP at /mcp/ (name is historical). Always include the trailing slash in the URL.

Restart sequence

Save the file.
Open Cursor Settings (Cmd+Shift+J on macOS / Ctrl+Shift+J on Windows/Linux) → Features → Model Context Protocol.
If the palinode entry shows a red indicator, click the toggle to disable then re-enable it. Cursor does not fully hot-reload config changes; a full quit and relaunch is the safest path when first adding an entry.

Verification

palinode mcp-config --diagnose

Confirm the palinode entry appears in the Cursor config path your instance reads. Then in Cursor chat (Agent mode):

Use palinode_status to check memory health

Troubleshooting

Symptom	Fix
Tools do not appear in agent tool list	Settings → MCP — check for an error badge. Usually a PATH problem: run `which palinode-mcp` in a terminal to confirm it is on PATH, then set the full path in `"command"`
`palinode mcp-config --diagnose` shows no entry for Cursor	You edited the wrong scope file. Check both `~/.cursor/mcp.json` and `.cursor/mcp.json`
Entry shows green in Settings but tools return errors	Palinode API is not running. Run `curl http://127.0.0.1:6340/status`
Transport mismatch / server not found	HTTP setups: verify `palinode-mcp-sse` is running on the server (`curl http://your-server:6341/mcp/`)

2. Windsurf

Docs verified: docs.windsurf.com/windsurf/cascade/mcp

Windsurf stores all MCP config in a single global file:

Platform	Path
macOS / Linux	`~/.codeium/windsurf/mcp_config.json`
Windows	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`

Create the file and its parent directories if they do not exist:

mkdir -p ~/.codeium/windsurf
touch ~/.codeium/windsurf/mcp_config.json

stdio (local install)

{
  "mcpServers": {
    "palinode": {
      "command": "palinode-mcp",
      "env": {
        "PALINODE_API_HOST": "127.0.0.1",
        "PALINODE_API_PORT": "6340"
      }
    }
  }
}

HTTP (remote server)

Windsurf uses serverUrl for the HTTP endpoint (both serverUrl and url are accepted; prefer serverUrl as that is what the official docs show):

{
  "mcpServers": {
    "palinode": {
      "serverUrl": "http://your-server:6341/mcp/"
    }
  }
}

Restart sequence

Windsurf does not hot-reload mcp_config.json. After saving the file:

Fully quit Windsurf (Cmd+Q / Alt+F4).
Relaunch Windsurf.
Open the Cascade panel — MCP servers initialise on first Cascade conversation.

Verification

palinode mcp-config --diagnose

Then in a Windsurf Cascade conversation:

Use palinode_status to check memory health

Troubleshooting

Symptom	Fix
No tools visible in Cascade	Confirm full quit and relaunch; Cascade lazy-loads tools on first use
`mcp_config.json` not found	Create the file at the exact path above; the directory is not created on first launch
Tools visible but all fail	API not running. `curl http://127.0.0.1:6340/status` should return JSON
HTTP: cannot connect	Check `serverUrl` spelling — it is `serverUrl`, not `url`. Confirm the remote MCP server is reachable: `curl http://your-server:6341/mcp/`
Cascade tool limit hit	Windsurf caps total tools at 100 across all MCP servers. If other servers are registered, the tool list may be truncated

3. Continue (VS Code)

Docs verified: docs.continue.dev/customize/deep-dives/mcp

Continue migrated from config.json (deprecated) to config.yaml in 2025. The instructions below use the current YAML format. The global config lives at ~/.continue/config.yaml; project-scoped config uses the same filename under .continue/config.yaml in the project root.

Important: MCP tools are only available in Continue's Agent mode, not Chat mode.

stdio (local install)

Add an mcpServers section to ~/.continue/config.yaml:

mcpServers:
  - name: palinode
    type: stdio
    command: palinode-mcp
    env:
      PALINODE_API_HOST: "127.0.0.1"
      PALINODE_API_PORT: "6340"

HTTP (remote server)

mcpServers:
  - name: palinode
    type: streamable-http
    url: http://your-server:6341/mcp/

Restart sequence

Continue hot-reloads config changes when the YAML file is saved — no VS Code restart needed in most cases. If tools do not appear after saving:

Open the VS Code Command Palette (Cmd+Shift+P / Ctrl+Shift+P).
Run Continue: Reload Config.
Switch to Agent mode in the Continue sidebar.

Verification

In the Continue Agent sidebar, open the tool list. palinode_search, palinode_save, and the other 15+ tools should appear. Then run:

Use palinode_status to check memory health

Also:

palinode mcp-config --diagnose

Troubleshooting

Symptom	Fix
Tools not visible	Ensure you are in Agent mode, not Chat mode
YAML parse error	Use 2-space indentation; YAML does not accept tabs
Config not picked up	Check whether a project-level `.continue/config.yaml` is overriding the global one
`command not found: palinode-mcp`	Continue inherits PATH from the VS Code shell. Run `which palinode-mcp` in your project terminal; if it prints nothing, the venv is not activated. Set `command` to the absolute path returned by `which palinode-mcp` after activating the venv
HTTP server errors	`type: streamable-http` (not `sse`) — confirm spelling

4. Cline / Roo Cline (VS Code)

Cline docs: docs.cline.bot/mcp/configuring-mcp-servers

Both Cline and its fork Roo Cline use the same mcpServers JSON shape. They differ only in extension ID, config file path, and filename — pick the table row that matches the extension you have installed.

Which extension do you have? In VS Code, open the Extensions sidebar (Cmd+Shift+X / Ctrl+Shift+X) and search "cline". The publisher field confirms the fork: saoudrizwan = Cline, RooVeterinaryInc = Roo Cline.

Config file paths

Cline (saoudrizwan.claude-dev) — file: cline_mcp_settings.json

Platform	Path
macOS	`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Linux	`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Windows	`%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`

Roo Cline (rooveterinaryinc.roo-cline) — file: mcp_settings.json

Platform	Path
macOS	`~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`
Linux	`~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`
Windows	`%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json`

The easiest way to open the file without navigating manually:

Click the extension's icon in the VS Code Activity Bar to open its sidebar.
Click the MCP Servers icon (plug icon) in the top navigation bar.
Select the Installed tab.
Click Configure MCP Servers — this opens the correct settings file directly in the editor.

Note: the settings file does not exist until you open the MCP settings panel at least once. Use the UI path above to let the extension create it before editing.

stdio (local install)

Use this when Palinode is installed on the same machine as VS Code.

{
  "mcpServers": {
    "palinode": {
      "command": "palinode-mcp",
      "env": {
        "PALINODE_API_HOST": "127.0.0.1",
        "PALINODE_API_PORT": "6340"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

HTTP (remote server)

Use this when Palinode runs on a separate machine. Both forks use "url" for the HTTP endpoint. palinode-mcp-sse serves streamable-HTTP at /mcp/ (the binary name is historical). Always include the trailing slash:

{
  "mcpServers": {
    "palinode": {
      "url": "http://your-server:6341/mcp/",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Replace your-server with your server's hostname or IP (localhost for a local HTTP server, or a stable hostname / IP for remote). Confirm the MCP server is reachable before configuring the client:

curl http://your-server:6341/mcp/

Restart sequence

Both forks pick up config changes without a VS Code restart:

Save the settings file.
Return to the extension sidebar → MCP Servers tab.
The palinode entry should appear. If it shows an error badge, click Restart Server.
No full VS Code restart is needed.

Verification

palinode mcp-config --diagnose

The diagnose command knows both Cline and Roo Cline paths — it will report whichever file is present. Also verify in the sidebar: the server should show as connected (green) and the tool list should expand to show all palinode tools.

Then in a conversation with the extension:

Use palinode_status to check memory health

Reducing approval prompts

Both forks prompt for approval on every MCP tool call by default. To pre-approve the tools you use most often, add their names to alwaysAllow:

{
  "mcpServers": {
    "palinode": {
      "url": "http://your-server:6341/mcp/",
      "disabled": false,
      "alwaysAllow": [
        "palinode_search",
        "palinode_save",
        "palinode_status",
        "palinode_read",
        "palinode_list",
        "palinode_history"
      ]
    }
  }
}

See MCP-SETUP.md for the full tool list.

Troubleshooting

Symptom	Fix
Server shows error badge immediately	`palinode-mcp` not found on PATH. Open a VS Code terminal, activate your palinode venv, run `which palinode-mcp` — use that absolute path as `"command"`
Settings file not found	Open the MCP settings panel from the extension UI (step 4 above) to let the extension create it, then edit
Tools appear but all fail	Palinode API not running. `curl http://127.0.0.1:6340/status` should return JSON
HTTP: `url` field ignored	Confirm the key is lowercase `"url"` — neither fork accepts `serverUrl`
HTTP: cannot connect to remote	Confirm `palinode-mcp-sse` is running on the server: `curl http://your-server:6341/mcp/`
Wrong file edited — change had no effect	Run `palinode mcp-config --diagnose` to see which file your installed extension reads

5. Zed

Docs verified: zed.dev/docs/ai/mcp

Zed stores MCP config inside the main settings.json under a "context_servers" key (not "mcpServers" — this differs from every other client):

Platform	Path
macOS / Linux	`~/.config/zed/settings.json`

Open it from Zed: Zed menu → Settings → Open Settings (Cmd+,).

Note: "source": "custom" is required for all manually added entries. Without it, Zed silently ignores the entry.

stdio (local install)

{
  "context_servers": {
    "palinode": {
      "source": "custom",
      "command": "palinode-mcp",
      "args": [],
      "env": {
        "PALINODE_API_HOST": "127.0.0.1",
        "PALINODE_API_PORT": "6340"
      }
    }
  }
}

HTTP (remote server)

Zed does not support a direct "url" field for Streamable HTTP. Use mcp-remote as a local bridge:

{
  "context_servers": {
    "palinode": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://your-server:6341/mcp/"],
      "env": {}
    }
  }
}

mcp-remote is an npm package (npm install -g mcp-remote or let npx fetch it on first run). It bridges Zed's stdio transport to the remote HTTP endpoint.

Restart sequence

Zed hot-reloads context server settings — no editor restart needed. After saving settings.json, Zed automatically restarts the context server process within a few seconds. You can verify in Zed's Assistant panel: open it and check that palinode appears in the tool list.

Verification

palinode mcp-config --diagnose

Zed's settings.json path is not currently in palinode's diagnose list (it uses context_servers, not mcpServers). Verify directly in Zed's Assistant panel — the server should appear in the available tools list.

Then in a Zed assistant conversation:

Use palinode_status to check memory health

Troubleshooting

Symptom	Fix
Server not appearing in Assistant panel	Missing `"source": "custom"` — add it; Zed silently skips entries without it
`command not found` error in Zed's logs	Zed may not inherit your shell PATH. Set `"command"` to the absolute path of `palinode-mcp`
HTTP via mcp-remote hangs	Confirm `npx` is available: `which npx`. If not, install Node.js. Alternatively, `npm install -g mcp-remote` and use `"command": "mcp-remote"` with the URL in `"args"`
Tools appear but calls fail	Palinode API not running: `curl http://127.0.0.1:6340/status`
Zed prompts for tool permission every call	Set `"agent.always_allow_tool_actions": true` in `settings.json` to auto-approve, or click Always Allow in the prompt

6. JetBrains IDEs (AI Assistant)

Docs: jetbrains.com/help/ai-assistant/configure-an-mcp-server.html

The MCP client is built into the AI Assistant plugin, available in IntelliJ IDEA, PyCharm, WebStorm, GoLand, Rider, CLion, DataGrip, and RubyMine. It is bundled in 2025.2+; for 2025.1 install the AI Assistant plugin from the marketplace.

JetBrains is UI-first. MCP servers are configured via the IDE settings panel, not a hand-edited file. The underlying config directory varies by product and version — use the UI path below rather than editing files directly.

Add via settings UI

Open Settings (Cmd+, on macOS / Ctrl+Alt+S on Windows/Linux).
Navigate to Tools → AI Assistant → Model Context Protocol (MCP).
Click + (Add) and choose As JSON.
Paste the appropriate snippet below.
Click Apply — this starts the server immediately. No restart needed.

Settings Sync: If you use JetBrains Settings Sync, the MCP config propagates automatically to all your other JetBrains IDEs.

stdio (local install)

{
  "mcpServers": {
    "palinode": {
      "command": "palinode-mcp",
      "args": [],
      "env": {
        "PALINODE_API_HOST": "127.0.0.1",
        "PALINODE_API_PORT": "6340"
      }
    }
  }
}

HTTP (remote server)

{
  "mcpServers": {
    "palinode": {
      "url": "http://your-server:6341/mcp/"
    }
  }
}

Verification

After clicking Apply, open the AI Assistant chat panel. In Agent mode, the tool list should include all palinode tools. Then run:

Use palinode_status to check memory health

Troubleshooting

Symptom	Fix
Server entry saves but tools never appear	Re-open Settings → Tools → AI Assistant → MCP and confirm the entry is enabled
stdio server fails immediately	Replace `"command": "palinode-mcp"` with the absolute path returned by `which palinode-mcp` in the same shell environment the IDE inherits
HTTP server fails immediately	Confirm the server is reachable first: `curl http://your-server:6341/mcp/`
Config seems to disappear across IDEs	Check whether JetBrains Settings Sync is enabled and overwriting the MCP entry from another machine
Unsure where the config lives on disk	Use the settings UI; the path is product- and version-specific, which is why `palinode mcp-config --diagnose` does not try to manage it

Environment variable reference

All six clients above can pass env vars to the stdio palinode-mcp process. The full variable set:

Variable	Default	Purpose
`PALINODE_DIR`	`~/.palinode`	Memory file directory (override if non-default)
`PALINODE_API_HOST`	`127.0.0.1`	Host where `palinode-api` listens
`PALINODE_API_PORT`	`6340`	Port for `palinode-api`
`PALINODE_PROJECT`	(auto from CWD)	Project context for ambient search

For HTTP transport the env vars are set on the server side, not the client.

Related docs

MCP-SETUP.md — transport overview, SSH fallback, and available tools list
MCP-CONFIG-HOMES.md — canonical config file paths and palinode mcp-config --diagnose reference
INSTALL-CLAUDE-CODE.md — full Claude Code install guide (LaunchAgent, session skill)

Uh oh!

Uh oh!

FilesExpand file tree

MCP-INSTALL-RECIPES.md

Latest commit

History

MCP-INSTALL-RECIPES.md

File metadata and controls

MCP Install Recipes — Per-Client Setup Workflows

Which transport should I use?

1. Cursor

stdio (local install)

HTTP (remote server)

Restart sequence

Verification

Troubleshooting

2. Windsurf

stdio (local install)

HTTP (remote server)

Restart sequence

Verification

Troubleshooting

3. Continue (VS Code)

stdio (local install)

HTTP (remote server)

Restart sequence

Verification

Troubleshooting

4. Cline / Roo Cline (VS Code)

Config file paths

stdio (local install)

HTTP (remote server)

Restart sequence

Verification

Reducing approval prompts

Troubleshooting

5. Zed

stdio (local install)

HTTP (remote server)

Restart sequence

Verification

Troubleshooting

6. JetBrains IDEs (AI Assistant)

Add via settings UI

stdio (local install)

HTTP (remote server)

Verification

Troubleshooting

Environment variable reference

Related docs