Skip to main content
Glama
oase-mcp

oase-mcp

Official
by oase-app

oase-mcp

An MCP server that lets Claude chat inside an Oase. Give Claude an invite link and it can post into that oase's group chat, publish posts (opslag) to the oase's feed, read the conversation, and react — handy for status updates, "I finished X", or dropping a note where you'll see it.

It's a REST client: every tool is a plain request/response HTTP call.

šŸ“– Documentation: https://dev.oase.app/mcp/

Status / disclaimer

This is experimental and provided as-is. It builds on Oase's internal API, which can change without notice — so it may break, change, or be discontinued at any time, and there's no guarantee it works today or will keep working tomorrow. There's no support commitment: issues are welcome (see SUPPORT.md) but may go unanswered. If you need a supported integration path, use the identity & SCIM integration instead.

Talks to the production Oase backend (api.oase.app) exactly like the app does: sign in → join via invite link → fetch the oase key from KMS → AES-256-GCM encrypt → POST .../messaging/messages. Messages are encrypted client-side with the oase's symmetric AES-256-GCM key (fetched from the KMS via a mainframe-signed proof), so they render normally in the app.

Related MCP server: OpenClaw MCP Server

Architecture

The codebase is a passive REST client with an MCP server on top:

  • Passive REST client — src/client/. Everything that knows how to talk to Oase over HTTP: Promise login/auth (promiseLogin.ts), token refresh and the shared config file (config.ts), and the full REST client (oaseClient.ts) — joining via invite link, KMS key fetching, AES-256-GCM encrypt/decrypt, and sending/reading messages and feed posts, reactions, and media. No agent behavior, no MCP dependency: it does something only when called. Importable by other consumers via the package root or oase-mcp/client (import { OaseClient, loadConfig } from "oase-mcp"), without pulling in the MCP layer.

  • MCP server — src/mcp/. The MCP tool surface over the REST client (server.ts). Every tool is an on-demand request/response wrapper. Entry point: dist/index.js (claude mcp add oase -- node /path/to/dist/index.js).

How it works

  • Identity. Claude signs in as a persistent Promise user (the identity provider the Oase app uses) via a one-time browser login — see Logging in. The resulting long-lived Oase refresh token is stored in ~/.oase-mcp/config.json (mode 0600); short-lived access tokens are kept in memory and refreshed automatically.

  • Encryption. Oase encrypts message content with a per-oase symmetric AES-256-GCM key held in escrow by the backend. Any participant can fetch the raw oase key from the KMS via a mainframe-signed proof, so encrypting/decrypting is straightforward — no device keypairs or enrollment. We produce the exact cipher-bundle shape the app expects.

  • No message is sent in plaintext — the send endpoint requires a cipher bundle.

Setup

npm install
npm run build

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

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

Or add to your MCP client config manually:

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

Logging in

Claude 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 Claude. 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.

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

Tools

Tool

Args

What it does

promise_login_start

—

Start the one-time browser login for a persistent Promise identity; returns a URL to open.

promise_login_finish

—

Complete the Promise login after signing in in the browser.

login_with_promise

id_token

Exchange a Promise id_token you already have.

join_oase

invite_link, display_name?

Join an oase from an invite link (https://oase.app/oase/<id>/join/<phrase>). Sets the display name (default Claude) and makes this oase the default target.

send_message

message, attachments?, oase_id?, thread_id?

Post a markdown message (text may be empty when attaching). attachments = up to 10 {path, name?, mime?} local files, encrypted client-side (see "Sending attachments"). With thread_id it posts inside that message's reply thread; otherwise the main chat.

update_message

message_id, message, oase_id?

Edit the text of a message you sent (only your own). Attachments are kept; only the text changes.

delete_message

message_id, oase_id?

Delete a message (soft delete). Your own, or anyone's if you're an oase admin/owner.

send_post

body, title?, attachments?, oase_id?

Publish a post (opslag) to the oase's feed/wall — the front-page items in the app, distinct from chat. Markdown body, optional title (shown as the headline). Comments on the post are thread replies: send_message with thread_id=<post id>. Fails with posting_restricted if an admin limited posting to admins.

update_post

post_id, body, title?, oase_id?

Edit a feed post's body (and optionally title; omit title to keep it). Attachments are kept. Your own, or anyone's if you're an oase admin/owner.

delete_post

post_id, oase_id?

Delete a feed post. Your own, or anyone's if you're an oase admin/owner.

read_posts

oase_id?, limit?

Read recent feed posts (decrypted), oldest first, each line prefixed with the post id and tagged (you)/(them), with title and attachment tags. Post attachments work with read_media.

react_to_message

message_id, reaction, oase_id?

Add an emoji reaction to a message (one per participant per message).

read_media

message_id, media_index?, oase_id?

Download and decrypt a message attachment (image, voice message / sound bite, file). Images are returned inline so the agent can view and analyze them; every attachment is also saved to a local temp file whose path is returned (e.g. for transcribing audio).

read_messages

oase_id?, limit?

Read recent messages (decrypted), oldest first, each line prefixed with its message id and tagged (you)/(them) (followed by <Name> when the sender's name is known); reactions show as {reactions: šŸ‘ Anders, 🟢 Nana(you)} (emoji, then who reacted; name omitted if it can't be resolved; your own are marked (you)); replies are marked (in thread <rootId>). Attachments show as [attachment <n>: <mime> "<name>"] tags — fetch them with read_media.

list_oases

—

Show Claude's Oase identity and joined oases.

set_name

display_name, oase_id?

Change the display name Claude posts under.

Threads and replies

Threads in Oase are one level: every reply to a message lives under that message's resource id (chat_id <oaseId>/m/<messageId>), and you cannot reply to a reply — a nested thread would never be shown in the app. The server enforces this: a thread_id that points at a reply is auto-resolved to the thread's root message, so nothing ever lands in an invisible nested chat. To reply to a message, pass its id as thread_id to send_message; use read_messages to catch up on context and get the ids.

Attachments (images, voice messages, files)

Messages with attachments show them as [attachment <n>: <mime> "<name>"] tags in every read result (a voice message is simply an audio/* attachment, usually audio/mp4). read_media downloads the blob and, for modern uploads, decrypts it: the app uploads media as an encrypted .oase container — [4-byte length][metadata JSON {alg, kid, oaseId, ivBase64}] [ciphertext][16-byte GCM tag] — encrypted with the same server-escrowed oase key as text, while the original filename/mime travel as cipher bundles on the media item (legacy attachments are plaintext blobs behind signed CDN URLs and pass through unchanged; giphy attachments resolve via their encrypted giphy object).

What the agent gets back:

  • Images (jpeg/png/gif/webp up to 3 MB) are returned inline as MCP image content, so the agent can look at them directly and use what it sees in its response. Larger images fall back to the saved file.

  • Everything is also written to <tmpdir>/oase-mcp/media/<messageId>-<n>-<name> and the path returned. For audio (Claude can't listen natively) the agent is nudged to transcribe the saved file with a local speech-to-text tool (e.g. hear on macOS or whisper) and work from the transcript; documents can be opened with normal file tools.

Blob download URLs are provider-signed and expire after ~2 days; read_media refreshes the chat projection and retries once if a URL has gone stale. Voice messages / media-only messages have an empty text body and are shown by read_messages like any other message.

Typical flow

  1. Log Claude in: promise_login_start → open the URL → promise_login_finish.

  2. In the Oase app, open your oase → invite → copy the join link.

  3. Ask Claude: "Join this oase: https://oase.app/oase/…/join/…" → join_oase.

  4. Ask Claude 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):

  • OASE_MCP_CONFIG_DIR — where to store config.json (default ~/.oase-mcp).

  • OASE_API_ROOT — mainframe API root (default https://api.oase.app), e.g. point at staging.

  • OASE_KMS_ROOT — KMS root (default https://kms.oase.app/, trailing slash required).

  • OASE_TRANSLOADIT_KEY, OASE_TRANSLOADIT_TEMPLATE — required to send attachments: the Transloadit auth key and template id the Oase apps upload with (not shipped in this repo). OASE_TRANSLOADIT_SERVICE overrides the region endpoint (default EU, https://api2-eu-west-1.transloadit.com). Instead of setting them in the MCP's environment you can keep them as KEY=value lines in a user-only file ~/.oase-mcp/env (outside any repo, chmod 600); real environment variables win over the file.

Sending attachments

send_message and send_post accept attachments: [{ path, name?, mime? }] (client: sendMessage(oaseId, text, threadId?, attachments?), sendPost(oaseId, body, title?, attachments?)). Same wire format as the apps:

  1. The file is wrapped in the .oase container — [uint32 LE meta length][meta JSON {version:1, alg:"AES-GCM", kid, oaseId, ivBase64}][AES-256-GCM ciphertext][16-byte tag] — under the oase's current key, fresh 12-byte IV.

  2. A Transloadit assembly is created from the apps' template and the container is tus-uploaded under a random name (outer mime application/x.oase-encrypted).

  3. The message's media gets {provider:"transloadit", id:<assembly>, file:{uploadURL}, mime, originalFile:{size, width, height, name_cipher_bundle, mime_cipher_bundle}}; the real filename and mime only travel as cipher bundles, and the backend imports the blob into storage.

Local files only (no URLs), max 50 MB each (an oase admin may set a lower cap) and 10 per message; empty files, directories and credential-looking paths (~/.oase-mcp, ~/.ssh, .env, …) are refused. Mime is guessed from content/extension. read_media decrypts what was sent. Run the tests with npm test.

Notes & limitations

  • Works on an oase's group chat (and per-message reply threads) and its feed posts (send_post/read_posts; a post's title and body are separate cipher bundles under the same oase key). It can send and read/decrypt attachments (send_message/send_post attachments, read_media); it doesn't handle private 1:1 chats or realm join-approval flows.

  • Replies can't be nested — threads are one level deep. A thread_id that is itself a reply is silently resolved to the thread's root message (best effort: for a message older than the latest chat page the id is used as-is).

  • Signing in as a different Promise account clears joined oases, since memberships are per-person — re-invite Claude afterward.

  • Deleting ~/.oase-mcp/config.json forgets the identity (Claude must log in and be re-invited).

  • Many server processes (one per Claude session) share the identity in ~/.oase-mcp/config.json. The backend rotates the refresh token on every oauth2/refresh and deletes the session if it ever sees a stale one (anti-replay) — so the access token is persisted for reuse, and refreshes are serialized across processes via ~/.oase-mcp/auth.lock with a re-read under the lock. Don't hit oauth2/refresh out-of-band while servers are running; if the session does get revoked, tools will say so — log in again with promise_login_start.

License

MIT — see LICENSE.

Available Tools

16 tools
delete_messageDelete a messageA

Delete a chat message (soft delete — it shows as removed in the app). Get the message_id from send_message or read_messages output. Omit oase_id to use the default (last joined) oase. You can delete your own messages; deleting someone else's requires being an oase admin/owner, otherwise the backend rejects it.

Inputs: message_id (required), oase_id.

delete_postDelete a feed postA

Delete a post (opslag) from an oase's feed. Get the post_id from send_post or read_posts output. Omit oase_id to use the default (last joined) oase. You can delete your own post; deleting someone else's requires being an oase admin/owner, otherwise the backend rejects it.

Inputs: post_id (required), oase_id.

join_oaseJoin an OaseA

Join an oase using an invite link (e.g. https://oase.app/oase//join/). Requires being logged in as a Promise user first (promise_login_start/finish). Sets your display name and makes this oase the default target for send_message.

Inputs: invite_link (required), display_name.

list_oasesList joined OasesA

Show this agent's Oase identity and the oases it has joined.

Inputs: no named parameters.

login_with_promiseLog in with a Promise identityA

Exchange a fresh Promise id_token (OIDC, audience 'oase.app') for a persistent Promise-backed Oase identity. One-time setup: the resulting Oase refresh token is long-lived, so Promise is never contacted again. Replaces any prior identity (joined oases from a different account are cleared, since memberships are per-person).

Inputs: id_token (required).

promise_login_finishFinish Promise loginA

Complete the login started by promise_login_start: waits for the browser redirect to deliver the token, exchanges it for a persistent Oase identity, and shuts down the callback server.

Inputs: no named parameters.

promise_login_startStart Promise login (browser)A

Begin logging Claude in as a persistent Promise identity. Starts a local callback server and opens the login page in the user's default browser (the URL is also returned as a fallback). The user signs in to (or creates) the Promise account for Claude; then call promise_login_finish to complete it. Recommended over pasting a raw id_token.

Inputs: no named parameters.

react_to_messageReact to a messageA

Add an emoji reaction to a message in an oase. Get the message_id from read_messages output. The backend allows one reaction per message per participant; a second attempt fails with 'already reacted'.

Inputs: reaction (required), message_id (required), oase_id.

read_mediaRead a message attachment (image/audio/file)A

Download and decrypt an attachment from a chat message — images, voice messages (sound bites), videos, documents. Messages list attachments as [attachment : "name"]; pass the message id and that index. Images are returned inline so you can view and analyze them directly. Every attachment is also saved to a local file whose path is returned — transcribe audio with a local speech-to-text tool, open documents with your file tools, etc., and use the content when composing your response.

Inputs: message_id (required), oase_id, media_index.

read_messagesRead recent Oase messagesA

Read the most recent chat messages in an oase (decrypted), oldest first. Each line starts with the message id and is tagged (you) for messages this agent sent. To reply to a main-chat message, call send_message with thread_id=. Messages marked 'in thread ' are replies — to continue that conversation, use thread_id=, not the reply's own id. Any id also works as react_to_message's message_id. Reactions people left on a message are shown as '{reactions: 🟢 šŸ‘}' — treat them as real answers, since someone may vote with an emoji instead of typing; your own are marked '(you)'. Attachments (images, voice messages, files) show as [attachment : …] tags — download and decrypt them with read_media.

Inputs: limit, oase_id.

read_postsRead recent Oase feed postsA

Read the most recent posts (opslag) in an oase's feed, decrypted, oldest first. Each line starts with the post id and is tagged (you) for posts this agent published. Attachments show as [attachment : …] tags — download them with read_media using the post id. To comment on a post, use send_message with thread_id=; to react, react_to_message with message_id=.

Inputs: limit, oase_id.

send_messageSend a message to an OaseA

Send a markdown chat message into an oase. Omit oase_id to use the default (last joined) oase. Pass thread_id (a message id from a prior send_message/read_messages) to post inside that message's reply thread instead of the main chat — use this to reply to a specific message or keep a conversation going. Threads are one level deep: you cannot reply to a reply. To continue a conversation, always thread under the root message; a reply's own id passed as thread_id is auto-resolved to its thread root.

Inputs: message (required), oase_id, thread_id.

send_postPublish a post to an Oase's feedA

Publish a post (Danish: opslag/indlƦg) to an oase's feed/wall — the front-page items in the app, distinct from chat messages. Use for announcements and longer write-ups; use send_message for chat. Body is markdown; the title is optional but recommended (the app shows it as the post's headline). Omit oase_id to use the default (last joined) oase. Returns the post id — comments on a post are ordinary thread replies, so send_message with thread_id= comments on it, and react_to_message works on post ids too. Fails with 'posting_restricted' if an admin limited posting to admins.

Inputs: body (required), title, oase_id.

set_nameSet display name in an OaseA

Change the display name this agent shows under in an oase. Omit oase_id to use the default oase. Also updates the default name for future joins.

Inputs: display_name (required), oase_id.

update_messageEdit a message you sentA

Edit the text of a chat message this agent sent earlier, replacing its body with new markdown. Get the message_id from send_message or read_messages output. Omit oase_id to use the default (last joined) oase. Only your OWN messages can be edited — the backend rejects edits to anyone else's. Any attachments on the message are kept as-is; only the text changes. The message must be in the recent chat history.

Inputs: message (required), message_id (required), oase_id.

update_postEdit a feed postA

Edit a post (opslag) on an oase's feed, replacing its body (and optionally its title) with new markdown. Get the post_id from send_post or read_posts output. Omit oase_id to use the default (last joined) oase. If you omit title, the post's current title is kept; pass title to change it (pass an empty string to clear it). Any attachments on the post are kept as-is. You can edit your own post; editing someone else's requires being an oase admin/owner. The post must be in the recent feed.

Inputs: body (required), post_id (required), title, oase_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: login steps are separated (start/finish vs. direct token exchange), messaging vs. posts are explicit (send_message vs. send_post), and read/update/delete operations are mapped to specific resources (messages, posts, media). There is no ambiguity between tools.

    Naming Consistency4/5

    Tool names mostly follow a verb_noun pattern (send_message, update_post, read_media), with consistent prefixes for CRUD operations. Minor deviations exist like promise_login_start/finish and login_with_promise, but they are still intuitive and do not break the overall consistency.

    Tool Count5/5

    16 tools is well-scoped for a chat/oase platform covering authentication, messaging, posts, reactions, media retrieval, and profile management. Each tool has a clear role and none feel redundant; the count is appropriate for the domain.

    Completeness4/5

    The tool set covers the primary workflows: messaging (send, read, update, delete), posts (publish, read, update, delete), reactions, media download, and authentication. Minor gaps exist, such as no explicit 'leave oase' tool and no direct attachment uploading (only media download), but these are not critical to core agent tasks and can be worked around.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables Claude.ai and Claude Desktop to securely connect to self-hosted OpenClaw AI assistants via OAuth 2.1, sending chat messages, checking gateway health, and queuing, polling, or cancelling long-running tasks. Supports orchestrating multiple OpenClaw gateway instances (such as prod, staging, and dev) from a single authenticated bridge.
      406 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Bridges Claude.ai and Claude Desktop to self-hosted OpenClaw AI assistants through an OAuth 2.1-secured HTTP endpoint. Enables sending chat messages, tracking long-running tasks, checking gateway health, and routing requests across multiple isolated instances from a single connection.
      406 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables Claude clients to securely connect to self-hosted OpenClaw assistants via OAuth 2.1, send synchronous or asynchronous chat messages, check gateway health, and manage long-running tasks. It also supports routing requests across multiple isolated gateway instances.
      406 npm
      MIT