ounie
Get started

MCP setup

Use Ounie in Raycast

Connect your Ounie brain to Raycast AI.

What you get#

Once connected, Raycast 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 Raycast 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)#

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

Open "Install MCP Server" in Raycast and fill in:

Name:      Ounie
Transport: HTTP
URL:       https://ounie.com/api/mcp

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#

  • —Raycast uses a UI-based install flow, not a hand-edited config file. Open Raycast, search for "Install MCP Server", choose HTTP transport, and paste https://ounie.com/api/mcp as the URL.
  • —Raycast supports Dynamic OAuth with PKCE: when you click "Sign In", Raycast registers itself as an OAuth client automatically (RFC 7591 dynamic client registration). You do not need an API key for the HTTP entry.
  • —After filling in the form, press Cmd+Enter to save, connect, and load tools.
  • —Search "Manage MCP Servers" to see connection status and the full list of loaded tools.
  • —The stdio fallback requires Node.js and npx. Use it only if the HTTP option is unavailable.

Verify it works#

Search "Manage MCP Servers" in Raycast. The Ounie server should show a green connected indicator with all tools listed. Ask Raycast AI to "list my Ounie brains" to confirm.

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.