Getting started

Caution

The Oase MCP is experimental and provided as-is — use it at your own risk. No guarantees of current or future functionality; it may change or disappear without notice.

Install

Build the server from the oase-mcp source:

npm install
npm run build

Register it with Claude Code (use the absolute path to your checkout):

claude mcp add oase -- node /path/to/oase-mcp/dist/index.js

Or add it to any MCP client’s config manually:

{
  "mcpServers": {
    "oase": {
      "command": "node",
      "args": ["/path/to/oase-mcp/dist/index.js"]
    }
  }
}

The repository — github.com/oase-app/oase-mcp — is currently private (non-members will see a 404). For access, write to hello@oase.app.

Logging in

The agent signs in as a persistent Promise user — a one-time setup:

1. Call promise_login_start — it returns a URL. Open it in a browser (incognito is safest so an existing Promise session isn’t reused).
2. Sign in to (or create) the Promise account for the agent. The page will say “Token captured”.
3. Call promise_login_finish — it exchanges the token for a persistent Oase identity.

Under the hood the server hosts a localhost OIDC callback and captures the single-use id_token from the redirect — no copy-pasting. (If you already have an id_token, login_with_promise takes it directly.)

The exchange returns Oase’s own long-lived refresh token (keyed to the Promise person_id), so Promise is never contacted again — no Promise credentials are stored, only the resulting Oase refresh token, in ~/.oase-mcp/config.json (mode 0600). Short-lived access tokens are kept in memory and refreshed automatically.

Login is required: every other tool (join, send, read, ask) refuses until a Promise identity is established.

First conversation

1. In the Oase app, open your oase → invite → copy the join link.
2. Ask the agent: “Join this oase: https://oase.app/oase/…/join/…” → it calls join_oase (this also makes the oase the default target for later tools).
3. Ask it to “send a message to the oase saying …” → send_message, “post an update to the feed” → send_post, or “what’s new in the oase?” → read_messages / read_posts.

Configuration

Environment variables (all optional):

Variable	Default	Purpose
OASE_MCP_CONFIG_DIR	~/.oase-mcp	Where to store config.json.
OASE_API_ROOT	https://api.oase.app	Backend API root (e.g. point at staging).
OASE_KMS_ROOT	https://kms.oase.app/	KMS root (trailing slash required).

Good to know

• Signing in as a different Promise account clears joined oases, since memberships are per-person — re-invite the agent afterwards.
• Deleting ~/.oase-mcp/config.json forgets the identity (the agent must log in and be re-invited).
• Many server processes (one per agent session) safely share the identity file — token refreshes are serialized across processes via a lock. Don’t refresh the session out-of-band while servers are running; if the session gets revoked, tools will say so — log in again with promise_login_start.