Ossian MCP server

ossian-mcp

MCP server for Ossian — ask your organisation's own documents and get the passages the answer came from, plus a memory for your agent that outlives the conversation.

Ossian is the server; this is the adapter that puts it in front of an agent. You need a running Ossian to point it at — see its README for a docker compose up.

What it gives an agent

Tools are gated by access mode (see Safe by default) — the server starts read-only, exposing only the four read tools until you raise the mode.

Install

npm install -g ossian-mcp

You need a running Ossian and an API key. Issue one from the console (Console → API keys) or:

curl -X POST "$OSSIAN_URL/api/admin/api-keys" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"mcp","roles":["ossian-user"],"namespace":"handbooks"}'

Give the key the narrowest scope that works. namespace confines it to one slice, so a key that leaks reads only what that agent was for.

Configure

{
  "mcpServers": {
    "ossian": {
      "command": "ossian-mcp",
      "env": {
        "OSSIAN_URL": "http://localhost:8081",
        "OSSIAN_API_KEY": "osk_...",
        "OSSIAN_AGENT_ID": "support-bot",
        "OSSIAN_MODE": "read-only"
      }
    }
  }
}

OSSIANAGENTID separates one agent's memories from another's; two agents sharing an id share their recollections, which is occasionally what you want and usually not.

See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf snippets, and .env.example for every supported variable.

Safe by default

The server enforces an access model on top of the Ossian API key — defence in depth over the key's own roles and namespace confinement. It reads its policy from the environment (.env.example) and enforces it in src/security.ts:

the mode allows its capability. Read-only exposes four tools; ingest and remember need read-write; forget needs admin.

• OSSIANMODE** — read-only (default) → read-write → admin. A tool is registered only if

mode it also requires this flag.

• OSSIANALLOWFORGET — forget_session erases memory irreversibly, so on top of admin

touched, and mark slices that may be read but never ingested into.

• OSSIANNAMESPACEALLOWLIST / OSSIANPROTECTEDNAMESPACES — confine which slices can be

• OSSIANDRYRUN — validate and log writes (ingest / remember / forget) without executing.
• OSSIANAUDITLOG — a JSON audit line per guarded operation, on stderr (default on).
• Interactive confirmation — when the client supports MCP elicitation, forgetsession prompts the human to approve before erasing a session's memory; clients that can't elicit fall back to the OSSIANALLOW_FORGET gate.

The primary control remains the API key: issue the narrowest one that works. See SECURITY.md.

Two things worth knowing

Shortened. The full README is on GitHub.