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, search your sources, and discover other people's public and paid brains without leaving your assistant.

Set up by client#

Step-by-step instructions for each supported AI client:

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.

Use brains you don't own#

ounie_explore_brains searches the public Explore feed — other people's public brains, including paid marketplace listings. Filter by free / paid / forkable, sort by new / popular / price. Every result's brainId works with the ask and search tools:

• Free public brains answer on your normal question allowance — exactly like asking your own brain.
• Paid brains first return a payment_required quote (price in credits, your balance, free previews). Your assistant confirms with you, then retries with payWithCredits: true to charge your prepaid credits. Free previews never need the flag; a non-answer is never charged. Details in Paid brains.

Try it in your client:

"Find popular public Ounie brains about marketing,
then ask the best one how to structure a launch email."

Use a public brain as an advisor on YOUR brain#

A brain setblends your primary brain (authoritative facts) with up to 4 advisor brains (expert guidance) into one answer where every citation is tagged by source brain. Advisors can be public brains you don't own. The whole flow works from your assistant:

1. ounie_explore_brains — find the advisor (e.g. { q: "sales", filter: "free", sort: "popular" }).
2. ounie_create_brain_set — { primaryBrainId: <yours>, advisorBrainIds: [<public brain>] } returns a set_… id.
3. ounie_ask_brain_set — { setId, question } for one blended, dual-cited answer. Costs one normal question; free public advisors add nothing.

Or just say it in one go:

"Find a popular public brain about B2B sales, make a brain set
with my Startup brain as primary and it as advisor, then ask the
set how we should price our enterprise tier."

Sets you create here also appear in Brain Lab, and vice versa — Lab-made sets work with ounie_ask_brain_set too.

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#

Some public brains are paid listings: their owner charges a per-question price for grounded, cited answers. Discover them with ounie_explore_brains (filter paid). There are two ways to pay.

Signed-in users: pay with Ounie credits#

Calling ounie_ask_brain (or ounie_search) on a paid brain returns a payment_required quote first — the price in credits, your balance, and any free previews. Retry the same call with payWithCredits: true to charge your prepaid credits; the owner earns them. Free previews (when the seller offers them) never need the flag, and a non-answer is never charged. Over plain REST, asking a paid brain at /api/brains/<id>/ask returns 402 with a pointer to /api/listing/<id>/ask, the credits-metered endpoint.

Agents: pay per call with x402#

Agents without an Ounie balance pay per call in stablecoin over x402 — no account, no API key. When a call carries an X-Payment header on an x402-enabled listing, that rail wins.

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, ounie_search, and ounie_get_context return a payment-required result until the call carries an X-Payment header or sets payWithCredits: true. 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_…" }
      }
    }
  }