# External AI Connections (MCP Server)

OmnyBot exposes a built-in **MCP Server** managed under **Settings → Admin → AI Connections** (`/{slug}/settings/mcp`), letting external AI assistants and editors securely access your workspace's Knowledge Base, AI bots, and conversations over the **Model Context Protocol (MCP)**.

:::note[Required permission]
Open **Configuration → AI Connections** or **Settings → AI Connections**. Managing tokens and tool permissions in the UI requires **`workspace:manage`** (the backend API accepts `ai:manage` or `workspace:manage`).
:::

## Connection Details & Supported Clients

- **MCP Endpoint**: `https://<your-domain>/api/mcp`
- **Transport**: Stateless **Streamable HTTP** with JSON responses (**`POST`** only; `GET` and `DELETE` return HTTP `405 Method Not Allowed`).
- **Built-in client setup guides**:
  - **Claude (Web)** (OAuth 2.1)
  - **ChatGPT** (OAuth 2.1)
  - **Claude Code**: `claude mcp add --transport http omnybot <endpoint>`
  - **Cursor** & **Antigravity**: JSON config via `mcpServers.omnybot.url`
  - **Manual Bearer Token**: pass `Authorization: Bearer omny_mcp_...`

## Authentication: OAuth 2.1 or Personal Access Token

OmnyBot supports two authentication methods for MCP clients:

### 1. OAuth 2.1 (PKCE + Dynamic Client Registration)

OAuth-capable clients (such as Claude Web, ChatGPT, and Claude Code) automatically discover endpoints via:
- `/.well-known/oauth-protected-resource` (RFC 9728)
- `/.well-known/oauth-authorization-server` (RFC 8414)
- Dynamic registration at `POST /api/oauth/register` (RFC 7591) and token exchange at `POST /api/oauth/token`.

During setup, OmnyBot opens a consent screen where you choose the target **Workspace** and scope (**`READ`** or **`WRITE`**). OAuth issues a **1-hour** (`3600`s) access token and a single-use **30-day** refresh token (`omny_mcpr_` prefix).

### 2. Personal Access Token (Manual)

1. On **Settings → AI Connections**, click **`+`** in the **Access Tokens** section.
2. Enter a **Token name** and choose a scope:
   - **`READ`**: Exposes read-only tools only.
   - **`WRITE`**: Exposes both read and write tools (still governed by per-tool permissions and confirmations).
3. Select an expiration: **30 days**, **90 days** (default), **365 days**, or **Never**.
4. Copy the generated token immediately (starts with **`omny_mcp_`**).

:::caution[Token security & revocation]
The raw token is shown **only once** at creation; the server stores only its **SHA-256** hash. Every token inherits the creator's live workspace membership and permissions on each request — removing the member or reducing their role immediately restricts or invalidates their tokens. Token creation and revocation are recorded in the **Audit Log**.
:::

## Exposed Tools & Per-Tool Permissions

The MCP server shares the same tool belt as [Mina](/mina-mcp/mina-assistant/) (excluding `connect_account` and `manage_bot_tools`, which are not exposed over MCP) plus dedicated inbox tools:

- **Tools from Mina**: search/create/update/delete Knowledge Base sources, manage collections, inspect/resolve knowledge gaps, manage/test AI bots, inspect channel health (`nick_health`), read unread conversations, and create/rename tags.
- **MCP conversation tools**: `list_conversations`, `get_conversation_messages`, `reply_conversation`.

In the **Tools** section on **Settings → AI Connections**, configure each tool's policy (shared with Mina):

| Permission | Behavior |
|---|---|
| **`always`** | Runs immediately without asking |
| **`ask`** *(default)* | Requires confirmation: the first call returns `needs_confirmation` with a `confirm_token`; the client resends the call with `confirm_token` only after user approval |
| **`deny`** | Hides the tool from `tools/list` and blocks execution |

## Rate Limiting

`POST /api/mcp` enforces two-tier sliding-window rate limits (returning HTTP `429 Too Many Requests` with `X-RateLimit-*` and `Retry-After` headers when exceeded):

- **Tier 1 (per IP)**: **120 requests / 60 seconds** (default).
- **Tier 2 (per Token)**: **60 requests / 60 seconds** (default).