Developers

Connect Ounie to your AI client

The Ounie MCP server lets AI clients — Claude, ChatGPT, Cursor, and more — read from and write to your second brain. Ask grounded questions, save notes and links, and search your sources without leaving your assistant.

What you get#

The server exposes these tools backed by your Ounie account:

Two ways to answer from a brain#

ounie_ask_brainruns Ounie's own LLM to write the answer. ounie_get_context instead returns just the retrieved wiki pages so your assistant (Claude, ChatGPT) writes the answer — faster, and it avoids a redundant second model call. When your client is already a capable model, prefer ounie_get_context.

Clients pick tools by description, so add a standing instruction (e.g. in your Claude.ai project instructions, or a ChatGPT custom instruction) so it routes there by default:

When answering from my Ounie brains, prefer ounie_get_context over
ounie_ask_brain: call ounie_get_context, read the returned pages, and
write the answer yourself, citing pages inline as [[slug]]. Only use
ounie_ask_brain if I explicitly ask Ounie to answer.

1. Create an API key#

Every request authenticates with a personal API key. Generate one in Settings → API keys. You'll see the full key (ounie_live_…) exactly once — copy it into your client config below. Keys carry your full account access; revoke a key anytime from the same page.

2. Local clients (stdio)#

Desktop and editor clients run the server locally over stdio via npx — no install step. Paste your key into the OUNIE_API_KEY field. The server is published as @ounie/mcp on npm.

Claude Desktop#

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows, then restart Claude:

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

Claude Code#

From your terminal:

claude mcp add ounie \
  --env OUNIE_API_KEY=ounie_live_… \
  -- npx -y @ounie/mcp

Cursor & Windsurf#

Add the same block to ~/.cursor/mcp.json (Cursor) or your Windsurf MCP config:

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

VS Code#

Create .vscode/mcp.json in your workspace (note the servers key):

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

3. Remote clients (HTTP)#

Web-based clients connect to the hosted endpoint instead of running anything locally:

URL:     https://ounie.com/api/mcp
Header:  Authorization: Bearer ounie_live_…

Cursor (remote)#

Point Cursor at the hosted URL with your key as a header:

{
  "mcpServers": {
    "ounie": {
      "url": "https://ounie.com/api/mcp",
      "headers": { "Authorization": "Bearer ounie_live_…" }
    }
  }
}

Claude.ai (custom connector — no API key needed)#

Claude.ai connects with a one-click sign-in (OAuth) — you don't paste a key. In Claude.ai go to Settings → Connectors → Add custom connector, enter the URL below, and click Connect. You'll be sent to Ounie to sign in and approve; after that, Claude can list your brains, ask questions, and save chat results back to a brain.

https://ounie.com/api/mcp

Manage or revoke connected apps anytime in Settings → API keys → Connected apps.

ChatGPT connectors#

Add https://ounie.com/api/mcp as a custom connector in Settings → Connectors(developer mode; availability depends on your plan). It uses the same sign-in flow as Claude.ai.

4. Verify it works#

Once configured, ask your client to “list my Ounie brains.” You can also sanity-check the REST API directly:

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

Paid brains (agents pay per call with x402)#

Some public brains are paid listings: their owner charges for grounded, cited answers. Agents pay per call in stablecoin over x402 — no account, no API key. Two surfaces:

REST (any agent)#

POST a question to the brain's paid endpoint. Without payment you get 402 Payment Required plus machine-readable requirements; your wallet signs and retries with an X-Payment header. A non-answer is never charged.

# 1) discover paid brains
curl -s https://ounie.com/api/x402/bazaar

# 2) ask (402 without payment → sign → retry with X-Payment)
curl -s -X POST https://ounie.com/api/x402/<brainId>/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"…"}'

MCP (paid tools)#

For a paid brain, ounie_ask_brain and ounie_get_context return a payment-required result until the call carries an X-Payment header. Free brains and your own brains are unaffected.

Troubleshooting#

• 401 Unauthorized: the key is wrong or revoked. Generate a fresh one in Settings → API keys.
• Self-hosting or local dev: set OUNIE_BASE_URL in the env block (defaults to https://ounie.com).
• No npx? Build the package from source and point your client at the file directly:
  Copy

  {
    "mcpServers": {
      "ounie": {
        "command": "node",
        "args": ["/absolute/path/to/ounie/mcp/dist/index.js"],
        "env": { "OUNIE_API_KEY": "ounie_live_…" }
      }
    }
  }