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).
Connection Details & Supported Clients
Section titled “Connection Details & Supported Clients”- MCP Endpoint:
https://<your-domain>/api/mcp - Transport: Stateless Streamable HTTP with JSON responses (
POSTonly;GETandDELETEreturn HTTP405 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
Section titled “Authentication: OAuth 2.1 or Personal Access Token”OmnyBot supports two authentication methods for MCP clients:
1. OAuth 2.1 (PKCE + Dynamic Client Registration)
Section titled “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 atPOST /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 (3600s) access token and a single-use 30-day refresh token (omny_mcpr_ prefix).
2. Personal Access Token (Manual)
Section titled “2. Personal Access Token (Manual)”- On Settings → AI Connections, click
+in the Access Tokens section. - 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).
- Select an expiration: 30 days, 90 days (default), 365 days, or Never.
- Copy the generated token immediately (starts with
omny_mcp_).
Exposed Tools & Per-Tool Permissions
Section titled “Exposed Tools & Per-Tool Permissions”The MCP server shares the same tool belt as Mina (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
Section titled “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).