Casama

Tìm kiếm tài liệu và tài liệu tham khảo HTTP API của Casama mà không cần đăng nhập, đồng thời điều khiển các bot AI Casama của bạn từ các công cụ lập trình.

Máy chủ MCP được lưu trữ

npx add-mcp 'https://api.casama.ai/mcp/docs'

Cài vào Claude Code, Codex, Cursor và nhiều công cụ khác

Tài liệu

Casama is an MCP server, so AI apps such as Claude, ChatGPT, Gemini CLI, Cursor and other MCP clients can list your bots, give them tasks and read the results. Use it when you work in another AI app and want a Casama bot, with its own computer, memory and tools, to do part of the job.

There are two ways to connect:

Hosted, by URLLocal, over stdio
Addresshttps://<your Casama API>/mcp (Streamable HTTP)The casama-mcp command from @casama/mcp
Best forApps that only take a URL: web and mobile AI apps, custom connectorsDesktop coding tools
Sign-inOAuth, or a workspace API keyYour casama login session, or CASAMA_TOKEN
ScopeOne workspaceEvery workspace you belong to

Both give the same tools, and your bots' approvals, action rules and budgets apply either way.

Building something on Casama? The docs tools let a coding agent search these docs and the API reference, with no sign-in.

This page is about AI apps using Casama. To let your bots use other MCP servers as tools, see Connections.

Find your address

  1. Open Settings → Workspace settings and open Advanced.
  2. Under Connect AI Apps, copy the address.

It's your API's address followed by /mcp, for example https://api.example.com/mcp. Self-hosters can set the advertised address with PUBLIC_API_URL; otherwise Casama uses the address the request came in on.

Add Casama to your AI app

On Casama Cloud the address is https://api.casama.ai/mcp. On your own server, use your address. Every app below signs in with OAuth: you pick the workspace and tap Allow in Casama, as in Hosted with OAuth.

AppWhere to add it
Claude (claude.ai and the desktop app)Settings → Connectors → Add custom connector. Give it a name (Casama) and the address, then Connect.
ChatGPTTurn on developer mode under Settings → Apps → Advanced settings, then create an app with the address and OAuth sign-in.
Gemini CLIgemini extensions install https://github.com/stackwares/casama-gemini, or gemini mcp add --transport http casama https://api.casama.ai/mcp. Then /mcp auth casama.
Claude Codeclaude mcp add --transport http casama https://api.casama.ai/mcp, then /mcp to sign in.
VS Code (Copilot)code --add-mcp '{"name":"casama","type":"http","url":"https://api.casama.ai/mcp"}'
CursorAdd the address under mcpServers in ~/.cursor/mcp.json as "url".

Menu names change as these apps update; look for "connectors", "apps" or "MCP servers". Apps that can't sign in with OAuth can use an API key.

Try it with a request such as:

  • "List my Casama bots."
  • "Ask my research bot to compare three CRMs for a five-person bakery and give me a table."
  • "Do any of my Casama bots have steps waiting for my approval?"

Hosted with OAuth (recommended)

  1. In your AI app, add a custom connector or remote MCP server and give it the address:
    https://api.example.com/mcp
    
  2. The app finds Casama's sign-in on its own, registers itself, and opens Casama in your browser.
  3. On the screen that says the app wants to use Casama, pick the Workspace and tap Allow (or Refuse).
  4. When you see Done. You can go back to the AI app., return to the app.

The app acts as you, in that one workspace only. Its access token lasts an hour. The app renews it with a refresh token that lasts 60 days and is replaced each time it's used. Connections are recorded in the workspace's audit log.

Hosted with an API key

Use a key for apps that don't support OAuth, or for scripts. Owners and admins create keys.

  1. Open Settings → Workspace settings → Advanced → Connect AI Apps.
  2. Tap New API Key, enter a Name and tap Create.
  3. Copy the key (it starts with ksk_). It isn't shown again.

The key acts as the person who created it, in that workspace only. Revoke it there at any time. A key or OAuth connection also stops working if that person leaves the workspace.

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "casama": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ksk_..." }
    }
  }
}

Claude Code:

claude mcp add --transport http casama https://api.example.com/mcp \
  --header "Authorization: Bearer ksk_..."

Any client that supports Streamable HTTP with custom headers works the same way.

Local over stdio

The local server runs on your machine and uses the same sign-in as the Casama CLI. @casama/mcp is also listed in the official MCP Registry as io.github.stackwares/casama, so tools that browse the registry can add it from there.

  1. Sign in with the CLI:
    casama login
    
  2. Add the server to your tool. Claude Code:
    claude mcp add casama -- npx -y @casama/mcp
    
    Any tool that takes a JSON config:
    {
      "mcpServers": {
        "casama": { "command": "npx", "args": ["-y", "@casama/mcp"] }
      }
    }
    
Environment variableWhat it does
CASAMA_API_URLYour Casama API. Default: the address from casama config, else https://api.casama.ai.
CASAMA_TOKENAn access token to use instead of the CLI's saved session
CASAMA_CONFIG_DIRWhere to find the CLI's saved session and config
CASAMA_DOCS_URLWhere the docs tools read the docs. Default: https://docs.casama.ai

With the CLI session, the server refreshes your sign-in as needed. See CLI.

Tools

Reads means the tool only reads. Changes means it can change something in Casama, and Acts means it can lead to actions outside Casama. Each tool tells the AI app which it is, so apps can ask you before calling one that changes or acts.

ToolKindWhat it does
list_workspacesReadsWorkspaces you belong to, with your role
list_botsReadsBots in a workspace, with their status. Takes an optional workspace slug, name or id.
ask_botActsSends a message to a bot (by name or id) and waits for the run to finish, fail or need approval. Returns the reply, the tools used, the cost, and the conversation and run ids. Pass conversation_id to continue a thread. The bot may use its computer and connected apps; risky steps wait for approval.
get_runReadsA run's status and cost, and its recent events: tool calls, outputs and errors
react_to_messageChangesReacts to a message with one emoji, or takes your reaction back (remove). Without message_id it reacts to the bot's latest reply in the conversation. A 👍 or 👎 tells the bot whether the reply worked.
list_approvalsReadsActions waiting for approval in a workspace
decide_approvalActsApproves or denies a pending action. The bot continues, or skips the step, right away.
list_sitesReadsPages published on the web at their own address, with their hosts and states
list_domains, get_domainReadsConnected and bought domains: the site each shows, its state, the DNS records to add with what DNS shows now
check_domainChangesChecks a domain's DNS and certificate now (admins)
connect_domainChangesConnects a domain the workspace owns, optionally to a published site; answers the records to add (admins)
search_domainsReadsNames with availability and prices. Only a person can buy one, in the app.
list_packsReadsPacks installed in the workspace
preview_packReadsWhat a pack from GitHub or the plugin directory would add, and the commit to install
install_packChangesInstalls a pack at the previewed commit. Secrets are added in the app, never over MCP.

Both servers also have the docs tools, and the local one has check_plugin and gallery_search.

ask_bot waits up to 10 minutes. If the bot needs approval, the result says waiting_approval; approve it in the Casama app, or with decide_approval if your workspace allows it.

Docs tools for building on Casama

For people building on Casama, and their coding agents, there's a docs-only server at https://api.casama.ai/mcp/docs. It needs no sign-in and can't see any account. A self-hosted server has one too, at /mcp/docs, reading the docs shipped with that server.

claude mcp add --transport http casama-docs https://api.casama.ai/mcp/docs
ToolWhat it does
search_docsSearches these docs by keyword and returns the best-matching sections, with their address
read_docOne page as markdown, by path (/develop/plugins) or address. Pass section for one section.
list_doc_pagesEvery page, with its title and address
get_api_operationLooks up the HTTP API by operationId (sendMessage), METHOD /path or keywords, and shows the parameters, request body and responses as types
check_pluginLocal server only: checks a plugin folder the way Casama does at install
gallery_searchLocal server only: searches the gallery for ready-made skills, apps, routines, bots, plugins, starter sets and looks, so an agent reuses one before building it

The local server has these tools too. To run only them, with no sign-in:

claude mcp add casama-docs -- npx -y @casama/mcp --docs-only

See Build with AI agents for the other ways agents can learn Casama.

Allow approvals from AI apps

By default, connected apps can't approve or deny your bots' actions, so a bot can't get its own risky step approved by the app that asked for it.

To change that, an owner or admin opens Settings → Workspace settings → Advanced → Connect AI Apps and turns on Allow Approvals from AI Apps.

ConnectionCan use decide_approval
OAuth or API keyOnly when Allow Approvals from AI Apps is on
Local stdio with your own sign-inYes, like the app

Either way, a high-risk step still stops and waits for a decision. See Autonomy, approvals and action rules.

What a connected app can see

A connected app acts as you, in one workspace, and only through the tools above. It goes through the same rules as the Casama app, so it reaches only what you can reach there. No tool reads your connections' secrets, buys anything or changes billing, and decide_approval is refused unless an owner or admin allows it. What the app does with what it reads is covered by that app's own privacy policy. See Privacy and security and casama.ai/privacy.

See and disconnect connected apps

Open Settings → Workspace settings, open Advanced, and find Connected AI Apps. It lists each app you connected by signing in, with when it was last used. Owners and admins see every person's connected apps in the workspace, with who connected each one.

Tap Disconnect next to an app. It loses access to the workspace at once: its next request is refused and it can't renew its sign-in. To use it again, connect it again from the app. Removing Casama inside the app also ends its access.

An API key stops working as soon as it's revoked in Connect AI Apps, and leaving the workspace cuts off every connection you made to it. Questions: support@casama.ai.

Limits

  • The local server needs Node.js 20 or later.
  • OAuth connections and API keys don't count as a two-step sign-in. In a workspace that requires two-step sign-in for admins, they get member access only.
  • The Connect AI Apps section is shown to owners and admins only.
  • OAuth sign-in only accepts apps whose redirect address is https or localhost.

Related