# 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 URL | Local, over stdio |
| --- | --- | --- |
| Address | `https://<your Casama API>/mcp` (Streamable HTTP) | The `casama-mcp` command from `@casama/mcp` |
| Best for | Apps that only take a URL: web and mobile AI apps, custom connectors | Desktop coding tools |
| Sign-in | OAuth, or a workspace API key | Your `casama login` session, or `CASAMA_TOKEN` |
| Scope | One workspace | Every 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](#docs-tools-for-building-on-casama) 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](https://docs.casama.ai/guide/connections.md).

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

## Hosted with OAuth (recommended)

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 variable | What it does |
| --- | --- |
| `CASAMA_API_URL` | Your Casama API. Default: the address from `casama config`, else `https://api.casama.ai`. |
| `CASAMA_TOKEN` | An access token to use instead of the CLI's saved session |
| `CASAMA_CONFIG_DIR` | Where to find the CLI's saved session and config |
| `CASAMA_DOCS_URL` | Where 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](https://docs.casama.ai/develop/cli.md).

## Tools

| Tool | What it does |
| --- | --- |
| `list_workspaces` | Workspaces you belong to, with your role |
| `list_bots` | Bots in a workspace, with their status. Takes an optional workspace slug, name or id. |
| `ask_bot` | Sends 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_run` | A run's status and cost, and its recent events: tool calls, outputs and errors |
| `list_approvals` | Actions waiting for approval in a workspace |
| `decide_approval` | Approves or denies a pending action. The bot continues, or skips the step, right away. |

Both servers also have the [docs tools](#docs-tools-for-building-on-casama), 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
```

| Tool | What it does |
| --- | --- |
| `search_docs` | Searches these docs by keyword and returns the best-matching sections, with their address |
| `read_doc` | One page as markdown, by path (`/develop/plugins`) or address. Pass `section` for one section. |
| `list_doc_pages` | Every page, with its title and address |
| `get_api_operation` | Looks up the [HTTP API](https://docs.casama.ai/develop/api.md) by operationId (`sendMessage`), `METHOD /path` or keywords, and shows the parameters, request body and responses as types |
| `check_plugin` | Local server only: checks a [plugin](https://docs.casama.ai/develop/plugins.md) folder the way Casama does at install |
| `gallery_search` | Local server only: searches the [gallery](https://gallery.casama.ai) 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](https://docs.casama.ai/develop/agents.md) 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**.

| Connection | Can use `decide_approval` |
| --- | --- |
| OAuth or API key | Only when **Allow Approvals from AI Apps** is on |
| Local stdio with your own sign-in | Yes, like the app |

Either way, a high-risk step still stops and waits for a decision. See
[Autonomy, approvals and action rules](https://docs.casama.ai/guide/autonomy.md).

## 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

- [Connections](https://docs.casama.ai/guide/connections.md)
- [Autonomy, approvals and action rules](https://docs.casama.ai/guide/autonomy.md)
- [CLI](https://docs.casama.ai/develop/cli.md)
- [API](https://docs.casama.ai/develop/api.md)
- [Build with AI agents](https://docs.casama.ai/develop/agents.md)
- [Talk to outside agents (A2A)](https://docs.casama.ai/develop/a2a.md)
