ounie
Get started

MCP setup

Use Ounie in VS Code

Connect your Ounie brain to GitHub Copilot chat in VS Code.

What you get#

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

VS Code 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 — no API key needed, .vscode/mcp.json)

{
  "servers": {
    "ounie": {
      "type": "http",
      "url": "https://ounie.com/api/mcp"
    }
  }
}

Config file: .vscode/mcp.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.

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

Notes#

  • —Create or edit .vscode/mcp.json at the root of any workspace. The file is committed alongside your project so teammates share the same server.
  • —For the HTTP entry, VS Code drives the OAuth flow automatically — it redirects you to ounie.com to sign in, then stores the token in VS Code's secret storage. You do not paste a key.
  • —Requires VS Code 1.99 or later with GitHub Copilot Chat enabled.
  • —You can also open the user-level config with the command "MCP: Open User Configuration" (applies across all workspaces).
  • —The stdio fallback requires Node.js and npx on your PATH.

Verify it works#

Open GitHub Copilot Chat (Cmd/Ctrl+Shift+I), switch to Agent mode, and type "list my Ounie brains". You should see the ounie server listed in the MCP tools panel.

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.