ounie
Get started

MCP setup

Use Ounie in Windsurf

Connect your Ounie brain to Cascade in Windsurf.

What you get#

Once connected, Windsurf can use these Ounie tools directly in your conversations:

  • ounie_list_brains — list your brains by name.
  • ounie_get_context — retrieve the matching wiki pages so Windsurf writes the answer (faster, no extra model call).
  • ounie_ask_brain — ask a grounded question; Ounie's own model writes the answer with citations.
  • ounie_add_to_brain — save a chat result or text into a brain (synthesized into the wiki+graph).
  • ounie_add_note — save a verbatim note as a new source.
  • ounie_add_link — save a web link; Ounie fetches and ingests it.
  • ounie_search — retrieve and summarize relevant saved sources.

See the full tool reference for all available tools and their arguments.

1. Connect with sign-in (no API key needed)#

Windsurf supports the MCP OAuth flow — it registers with Ounie automatically and redirects you to sign in. No API key is required for this option.

Hosted (HTTP + OAuth — no API key needed)

{
  "mcpServers": {
    "ounie": {
      "serverUrl": "https://ounie.com/api/mcp"
    }
  }
}

Config file: ~/.codeium/windsurf/mcp_config.json

2. Stdio fallback (API key required)#

If you prefer to run the server locally, or if the OAuth flow is unavailable, use the stdio transport with a personal API key.

Generate a key (ounie_live_…) at Settings → API keys. You'll see the full key exactly once — paste it into the OUNIE_API_KEY field below.

{
  "mcpServers": {
    "ounie": {
      "command": "npx",
      "args": ["-y", "@ounie/mcp"],
      "env": { "OUNIE_API_KEY": "ounie_live_…" }
    }
  }
}

Notes#

  • —The config file lives at ~/.codeium/windsurf/mcp_config.json. Create it if it does not exist.
  • —For the HTTP entry, Windsurf will detect the OAuth endpoint via RFC 9728 resource metadata and prompt you to sign in. No API key is needed.
  • —Windsurf supports stdio, Streamable HTTP, and SSE transports. The "serverUrl" key selects Streamable HTTP.
  • —You can also open Windsurf Settings → MCP Servers to manage servers through the UI.
  • —Reload the Windsurf window (Cmd/Ctrl+Shift+P → "Reload Window") after editing the config for changes to take effect.

Verify it works#

Open a new Cascade chat and ask "list my Ounie brains." The ounie_list_brains tool should run and return your brains.

You can also check the REST API directly from your terminal:

curl -s https://ounie.com/api/brains \
  -H "Authorization: Bearer ounie_live_…"

Troubleshooting#

  • 401 Unauthorized: For the OAuth flow, disconnect and reconnect to trigger a fresh sign-in. For the stdio/API-key option, the key may be wrong or revoked — generate a new one in Settings → API keys.
  • Tools labeled read-only: tools such as ounie_list_brains, ounie_get_context, and ounie_search carry a read-only hint in the MCP tool descriptor. Some hosts display this as a lock icon or a "read-only" badge — this is expected and correct. Write tools (ounie_add_to_brain, ounie_add_note, ounie_add_link) do not carry that hint.
  • No tools appear: confirm the server URL is exactly https://ounie.com/api/mcp with no trailing slash, and that the config has been saved and the client reloaded.
  • npx not found: the stdio option requires Node.js 18 or later on your PATH. Install it from nodejs.org.
  • Self-hosting or local dev: set OUNIE_BASE_URL in the env block to point at your local server (defaults to https://ounie.com).

Back to MCP overview · Manage connected apps in Settings → API keys.