Skip to content

Connect AI apps to Casama (MCP) ​

Casama is an MCP server, so AI apps such as Claude Code, 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.

  1. In your AI app, add a custom connector or remote MCP server and give it the address:

    text
    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):

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

Claude Code:

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

  1. Sign in with the CLI:

    sh
    casama login
  2. Add the server to your tool. Claude Code:

    sh
    claude mcp add casama -- npx -y @casama/mcp

    Any tool that takes a JSON config:

    json
    {
      "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 ​

ToolWhat it does
list_workspacesWorkspaces you belong to, with your role
list_botsBots in a workspace, with their status. Takes an optional workspace slug, name or id.
ask_botSends 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.
get_runA run's status and cost, and its recent events: tool calls, outputs and errors
list_approvalsActions waiting for approval in a workspace
decide_approvalApproves or denies a pending action. The bot continues, or skips the step, right away.

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.

sh
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:

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

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.