oase-mcp
Officialoase-mcp lets Claude act as a participant in Oase group chats and feeds via MCP tools.
Log in as a persistent Promise/Oase identity using a browser flow or an existing
id_token.Join an Oase via invite link and set the display name/default target.
List joined Oases and change the display name.
Send markdown chat messages, including into one-level reply threads.
Edit and delete chat messages you sent; delete others only with admin/owner rights.
Publish, edit, and delete feed posts (opslag).
Read recent decrypted chat messages and feed posts, including reactions and attachment tags.
Add emoji reactions to messages or posts.
Download and decrypt attachments, return images inline, and save files locally for audio transcription or document access.
Works with Oase group chats and feed posts, not private 1:1 chats.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@oase-mcp send a message to the oase saying I'm on my way"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 oroase-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 buildRegister it with Claude Code (use the absolute path to this checkout):
claude mcp add oase -- node /path/to/oase-mcp/dist/index.jsOr 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:
Call
promise_login_startā it returns a URL. Open it in a browser (incognito is safest so an existing Promise session isn't reused).Sign in to (or create) the Promise account for Claude. The page will say "Token captured".
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 |
| ā | Start the one-time browser login for a persistent Promise identity; returns a URL to open. |
| ā | Complete the Promise login after signing in in the browser. |
|
| Exchange a Promise |
|
| Join an oase from an invite link ( |
|
| Post a markdown message (text may be empty when attaching). |
|
| Edit the text of a message you sent (only your own). Attachments are kept; only the text changes. |
|
| Delete a message (soft delete). Your own, or anyone's if you're an oase admin/owner. |
|
| 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: |
|
| Edit a feed post's body (and optionally title; omit |
|
| Delete a feed post. Your own, or anyone's if you're an oase admin/owner. |
|
| Read recent feed posts (decrypted), oldest first, each line prefixed with the post id and tagged |
|
| Add an emoji reaction to a message (one per participant per message). |
|
| 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 recent messages (decrypted), oldest first, each line prefixed with its message id and tagged |
| ā | Show Claude's Oase identity and joined oases. |
|
| 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.hearon macOS orwhisper) 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
Log Claude in:
promise_login_startā open the URL āpromise_login_finish.In the Oase app, open your oase ā invite ā copy the join link.
Ask Claude: "Join this oase: https://oase.app/oase/ā¦/join/ā¦" ā
join_oase.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 storeconfig.json(default~/.oase-mcp).OASE_API_ROOTā mainframe API root (defaulthttps://api.oase.app), e.g. point at staging.OASE_KMS_ROOTā KMS root (defaulthttps://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_SERVICEoverrides 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 asKEY=valuelines 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:
The file is wrapped in the
.oasecontainer ā[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.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).The message's
mediagets{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_postattachments,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_idthat 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.jsonforgets 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 everyoauth2/refreshand 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.lockwith a re-read under the lock. Don't hitoauth2/refreshout-of-band while servers are running; if the session does get revoked, tools will say so ā log in again withpromise_login_start.
License
MIT ā see LICENSE.
Available Tools
16 toolsdelete_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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
One encrypted chat for you, your people and your AI agents: Claude, Codex, Gemini, Goose.
Read and answer your team's WhatsApp and email inbox from Claude or ChatGPT. OAuth sign-in.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceBridges 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables Claude clients to securely connect to self-hosted OpenClaw assistants via OAuth 2.1, exchange chat messages, check gateway health, manage asynchronous tasks, and route requests across multiple instances.406 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT