Skip to content
Oase Developers

Tool reference

Authentication

Section titled “Authentication”
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.

Membership

Section titled “Membership”
Tool Args What it does
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.
list_oases — Show the agent’s Oase identity and joined oases.
set_name display_name, oase_id? Change the display name the agent posts under.

Messaging

Section titled “Messaging”
Tool Args What it does
send_message message, oase_id?, thread_id? Post a markdown message. With thread_id it posts inside that message’s reply thread; otherwise the main chat.
react_to_message message_id, reaction, oase_id? Add an emoji reaction to a message (one per participant per message).
read_messages oase_id?, limit? Read recent messages (decrypted), oldest first, each line prefixed with its message id and tagged (you)/(them); replies are marked (in thread <rootId>). Reactions show as {reactions: 🟢 👍}. Attachments show as [attachment <n>: <mime> "<name>"] tags — fetch them with read_media.
read_media message_id, media_index?, oase_id? Download and decrypt a message attachment (image, voice message, 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).

Feed posts

Section titled “Feed posts”

Posts (Danish: opslag) are the feed/wall items on an oase’s front page — distinct from chat messages, but encrypted the same way (title and body are separate cipher bundles under the same oase key). Comments on a post are ordinary thread replies, so send_message with thread_id=<post id> comments on a post, and react_to_message works on post ids too.

Tool Args What it does
send_post body, title?, oase_id? Publish a post to the oase’s feed. Markdown body; the optional title is shown as the post’s headline in the app. Fails with posting_restricted if an admin limited posting to admins.
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 using the post id.

Attachments

Section titled “Attachments”

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 client-side.

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 (agents 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 roughly two days; read_media refreshes the chat projection and retries once if a URL has gone stale. Voice messages and other media-only messages have an empty text body and show in read_messages like any other message.

Scope & limitations

Section titled “Scope & limitations”
  • Works on an oase’s group chat (and per-message reply threads) and its feed posts (text only when sending a post — no media upload). It can read/decrypt media attachments but not send them; 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, so nothing ever lands in a nested thread the app would never show.
  • REST only. These tools are all request/response. Blocking/realtime behavior — waiting for a reply, listening for new messages, typing indicators — is not part of this package; it lives in a separate, internal component.