Skip to content

External AI Connections (MCP Server)

View as Markdown

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

  • 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

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 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 (3600s) access token and a single-use 30-day refresh token (omny_mcpr_ prefix).

  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_).

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

PermissionBehavior
alwaysRuns 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
denyHides the tool from tools/list and blocks execution

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