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_…" }
      }
    }
  }