@oka-core/reason

@oka-core/reason is an MCP server you run as a subprocess from any MCP-compatible client. It exposes Reason’s tools for capturing and querying organizational intelligence.

Install / run

# Ad-hoc (no install needed)
npx -y @oka-core/reason

# Pinned
pnpm add @oka-core/reason

{
  "mcpServers": {
    "oka": {
      "command": "npx",
      "args": ["-y", "@oka-core/reason"]
    }
  }
}

Requires Node.js ≥ 20.

Authentication

@oka-core/reason resolves credentials automatically using a credential chain (checked in order):

OKA_API_KEY environment variable — highest priority. Use for CI/CD, headless servers, or when you prefer static keys.
~/.oka/credentials.json — stored by the login tool after browser authentication. Tokens auto-refresh in the background.
Unauthenticated — API calls return 401. The error message tells the agent to run login.

The simplest way to authenticate is the login tool. When called, it:

Opens your browser to id.oka.so
You sign in (or create an account)
The token is stored to ~/.oka/credentials.json (mode 0600)
Subsequent requests use this token automatically

No config changes needed — just call login from your MCP client.

The whoami tool checks your current authentication status at any time.

API key (headless)

For environments without a browser, set OKA_API_KEY:

{
  "mcpServers": {
    "oka": {
      "command": "npx",
      "args": ["-y", "@oka-core/reason"],
      "env": { "OKA_API_KEY": "sk_..." }
    }
  }
}

Get your API key from app.oka.so → Settings → API keys.

Token refresh

When using browser login, @oka-core/reason automatically refreshes tokens 5 minutes before expiry. You don’t need to re-authenticate unless your refresh token itself expires.

Tools exposed

Auth (2)

login(auth_server_url?, client_id?) — authenticate via browser
whoami() — check current authentication status

Write (7)

observe(content, tags?, workspace?)
decision(content, rationale, workspace?)
explore(content, area?, workspace?)
deviation(content, expected, actual, workspace?)
done(task, outcome?, workspace?)
learning(content, tags?, workspace?)
feedback(learning_id, useful, comment?)

Read (10)

context(topic?, workspace?, min_confidence?)
learnings(workspace?, category?, status?)
decisions(workspace?, since?)
patterns(workspace?, since?)
semantic_search(query, limit?)
suggest(workspace?)
backlog(workspace?, status?)
priorities(workspace?)
consolidate(workspace?)
entities(type?, workspace?)

Environment

Var	Default	Purpose
`OKA_API_KEY`	—	API key (overrides stored credentials)
`OKA_REASON_URL`	`https://reason.oka.so`	Override the Reason API endpoint
`OKA_WORKSPACE`	project dir	Default workspace attribution