Octocom MCP

Connect your AI agent (Claude, Claude Code, or any MCP-compatible client) to Octocom so it can read and modify your bot's configuration, drive test conversations, and build custom integrations.

Octocom exposes its API as an MCP (Model Context Protocol) server. Once connected, an AI agent can manage almost every aspect of your Octocom workspace on your behalf — from inspecting why a bot replied a certain way to writing new Python actions.

Only Organization Admins and Managers can authorize an MCP connection. Basic and Quality Assurance users cannot connect, including in read-only mode. Your current role is checked on every MCP request, so existing connections stop working if you change to an ineligible role.

list_businesses includes active and archived businesses, with isArchived on each result. Archived businesses retain their data for inspection, but MCP and Copilot block configuration changes and operational tools targeting them, including changes addressed by a resource or conversation ID. Select an active business, or restore the business before making changes. Organization-wide configuration remains editable.


What you can do with the Octocom MCP

The best way to discover what's possible is to ask your agent itself: "What Octocom tools do you have and what can you do with them?" The agent will introspect its available tools and give you an up-to-date overview.

Popular use cases include:

  • Deeply debug bot responses. The agent can pull the exact system prompt the bot saw on any past response and the full sequence of tool calls it made — then trace which rule, workflow, article, or action drove the behavior, and fix it.
  • Drive test conversations against your bot. The agent can literally chat with your Octocom bot through MCP, send messages, read replies, then iterate on the configuration in a tight loop — like an automated QA engineer. These appear in the inbox as Agent playground, separately from Human playground sessions. Email and WebChat retain their normal channel labels. Phone calls can be tested over text too: see voice AI testing.
  • Operate on real customer conversations. List and read conversations, inspect transcripts, tag them, close them, or hand them off to humans.
  • Manage every part of the bot's configuration:
    • Bot rules — the policies that guide responses, with full version history and rollback
    • Workflows — multi-step playbooks for handling specific situations, with variants
    • Articles & documents: the knowledge base, with recoverable archival
    • Macros & folders — canned responses for human agents
    • Tags — for routing, reporting, and conversation triage
    • Data collection prompts — structured intake of customer info (email, order number, etc.)
    • Writing style and system prompt: tone, chat and email writing style, language, and the expert prompt sections such as safety
    • Web chat configurations — deployments, appearance, greetings, suggestions, attention grabbers, live chat, and widget behavior
  • Write custom code on your behalf, and test it before deploying:
    • Python actions — let the bot do anything Python can do
    • API actions — call any external API as a bot action
    • Condition providers — Python-based gates that decide when workflows/rules apply
    • Event handlers — Python listeners that react to bot/conversation events
    • Sidebar widgets — Python-rendered widgets for the agent UI
    • Every one of these has a matching test_* tool, so the agent can validate its code with real inputs before you push it live.
  • Configure social media response automation — comment workflows that handle Instagram/Facebook comments and DMs, including testing them against sample comments.
  • Configure the review-response bot — Trustpilot, Okendo, and Google review workflows, including simulating an incoming review end-to-end and inspecting workflow runs.
  • Build and run AI-generated product catalog parsers. Hand the agent any product feed (XML/JSON/CSV) and have it write a Python parser that maps it into Octocom's product catalog — sample the feed, write the parser, run it, inspect the execution, iterate. Useful for stores not on a directly-supported platform.
  • Explore legacy sites through an audited browser. Inspect rendered DOM content, perform guarded steps, extract data and create saved Python actions. See Browser Automation for connection authorization, failure handling and evidence.
  • Search and inspect your product catalog directly from your agent.
  • Set up phone calls: phone lines, call routing and time slots, voice AI settings, phone line routers, and outbound campaigns with recipients, test calls and start/pause/cancel. See Voice.
  • Host public images and downloadable files with create_public_file_upload_url and finalize_public_file_upload, then use their URLs in articles, workflows or actions. See Public files.
  • Manage your customer portal — enable or disable it, configure built-in help-center and public article API access, publish HTML/JavaScript pages with previews and assets, and connect custom domains. See the portal MCP tool reference.
  • Use the dashboard's docs as a reference. The MCP exposes Octocom's own documentation as tools, so the agent can pull up the right page when it doesn't know how something works — no Octocom expertise required on your end.

The real superpower: combining tools at scale

The individual tools are useful, but the leverage shows up when you combine them with what AI is already great at — reading large dumps of unstructured input, writing and testing code, and driving repeated test conversations. A few examples of what this looks like in practice:

  • "Configure this, then stress-test it." Ask the agent to set up a workflow, action, or rule, then run 20 test conversations against it with varied scenarios, summarize where it broke, and iterate.
  • "Here's a CSV of feedback — fix the bot." Drop a CSV (or spreadsheet) of conversation IDs and human comments. The agent reads each conversation, correlates the feedback, and proposes/applies targeted changes — rule by rule, article by article.
  • "Here are 100 sample customer comments — evaluate the social media workflow." Hand the agent a batch of real comments. It runs each one through your comment workflow (or data collection prompt), writes the responses back to a CSV, and analyzes overall quality, edge cases, and failure modes.
  • "Build me an integration." Describe an external system. The agent writes a Python action, tests it with realistic inputs, wires it into a workflow, then runs end-to-end test conversations to confirm it all works.

In short: it's not just that you can do individual things through MCP — it's that you can finally do them at scale, with the same agent doing the analyzing, the coding, the configuring, and the testing in one loop.

We keep evolving the MCP and our goal is that you can do everything through MCP — eventually going beyond what's possible in the dashboard.


Organization context and mutation history

Every mutating MCP or Copilot tool accepts an optional note. Use it for useful reasoning, decisions or constraints. Attribution is recorded even without a note; keep credentials and customer data out of explanations.

The organization mutation ledger records supported resource changes and successful mutating tool executions. Copilot attaches its session and turn automatically, so related changes can be traced back to their discussion. External MCP calls retain the authenticated user and client identity, but Octocom cannot load the external client's conversation.

  • list_configuration_changes finds events by resource, session or organization. get_configuration_change reads their available details.
  • get_copilot_session_context returns session author/time attribution and its recorded mutation inventory. Customer users, including Organization Admins, need ownership or an owner-issued shareToken to read private titles, summaries and discussion, and search_copilot_sessions searches only their own sessions. Octocom admins can search and read other users' sessions within organizations they can access. After an explicit sharing request, create_copilot_session_share creates a read-only link for a session you own, valid for 30 days within the same organization. Pass the token from its #share= fragment to read_copilot_session or get_copilot_session_context to read a shared discussion. A session UUID alone grants no discussion access. Links include future messages, can be forwarded within the organization and cannot be individually revoked.
  • get_organization_context and list_context_notes retrieve shared facts, decisions and relationships. Agents can create or update context notes as the organization's understanding changes.

Copilot's organization context tools are available automatically from the first step, subject to permissions. Sessions are personal: colleagues, including admins, see a session's author, time and recorded changes, but not its title, summary or discussion unless the owner shares a link. Archiving a session hides it from the owner's list; existing share links remain valid until they expire.

Removal tools are named archive_* and archived listings list_archived_*. The previous delete_* and list_deleted_* names remain callable as deprecated aliases for existing clients and saved prompts, but they are not listed; update integrations to the current names.

Mutation history is separate from restoration. Some resources retain full versions, some support archives, and other events record only the tool and referenced IDs. An event does not promise a reversible operation or a configuration diff. Coverage currently focuses on MCP/Copilot; existing versioned services also contribute history, but not every dashboard or REST change is recorded yet.


You're responsible for what the agent does

When you connect an AI agent to Octocom via MCP, that agent acts on your behalf with your permissions. The person driving the agent is responsible for everything it does — including misconfigured bots, deleted or broken workflows, unintended messages sent to real customers, and large conversation counts run up by automated testing. Octocom does not take responsibility for these outcomes.

That said, we work hard to make the MCP safer to use:

  • Read-only mode (see below) lets you use the MCP without any risk of mutations.
  • Version history for resources such as workflows, articles and bot rules, plus recoverable archives for selected authored configuration. Recovery depends on the resource; configuration restoration cannot undo sent messages or external actions.
  • Tool design is biased toward clarity and safety — descriptive names, explicit test_* companions to mutating tools, and unambiguous arguments so the LLM is unlikely to do something it didn't mean to.
  • Rate limiting to prevent runaway loops and unbounded tool-call sprees.
  • Audit logging of every MCP tool call.

These are guardrails, not guarantees. The agent can still make wrong choices, and an unattended agent can still cause real damage. Treat MCP like a powerful intern with full keyboard access: review what it proposes before merging, supervise it during meaningful changes, and reach for read-only mode whenever you don't need write access.


Read-only mode

Octocom MCP exposes two endpoints:

URLModeWhat it can do
https://api.octocom.ai/mcpRead-writeRead and modify configuration, archive supported resources, send messages, upload documents, and run mutating tools.
https://api.octocom.ai/mcp?readonly=trueRead-onlyInspection tools only. Configuration writes, operational mutations and tests that can mutate state are excluded.

Read-only mode is useful when you want the agent to analyze, audit, or explain your Octocom setup without any risk of accidental mutations — for example:

  • A first-time exploration where you just want the agent to describe what's configured
  • Letting a teammate connect their own AI agent for inspection only
  • Running scripted audits, reports, or one-off analyses
  • Pairing with another MCP server (e.g. your data warehouse) where Octocom is purely a source of context

Connect to the read-only endpoint the same way as the regular one — just use the ?readonly=true URL when adding the custom connector. The OAuth flow is identical.

You can also have both endpoints connected at once in the same client (e.g. as Octocom (read-only) and Octocom), and decide per-conversation which one to use.


Connect from Claude (chat, Cowork, or Desktop)

Anthropic calls this a custom connector using remote MCP, and the same connector configuration works across the Claude chat (claude.ai), Claude Cowork, and Claude Desktop — connect once and it's available everywhere you use Claude on that account. It's supported on Free, Pro, Max, Team, and Enterprise plans (the setup steps differ slightly between individual and Team/Enterprise plans — see below).

These instructions are valid as of May 20th, 2026. The Claude app is updated frequently — if the buttons described below no longer exist, search Anthropic's support docs for how to add a custom MCP connector. The latest reference is Get started with custom connectors using remote MCP.

Pro and Max plans (individual)

  1. Navigate to Customize > Connectors.
  2. Click "+", then "Add custom connector".
  3. Enter the MCP server URL: https://api.octocom.ai/mcp
  4. Set the name to Octocom.
  5. Click Add.

You don't need to touch Advanced settings — leave the OAuth Client ID and Secret fields empty.

Once added, click Connect. You'll be redirected to the Octocom dashboard to grant the MCP access to your account, and then back to Claude.

Team and Enterprise plans

On Team and Enterprise, custom connectors must first be configured at the organization level by an Owner or Primary Owner. After that, individual members can connect.

Step 1 — Owner adds the connector (one-time setup):

  1. Navigate to Organization settings > Connectors.
  2. Click Add.
  3. Hover over Custom, then select Web.
  4. Enter the MCP server URL: https://api.octocom.ai/mcp
  5. Set the name to Octocom.
  6. Click Add.

You don't need to touch Advanced settings — leave the OAuth Client ID and Secret fields empty.

Step 2 — Each member connects:

  1. Navigate to Customize > Connectors.
  2. Find the Octocom connector in the list (it will have a Custom label).
  3. Click Connect to authenticate. You'll be redirected to the Octocom dashboard to grant access, and then back to Claude.

Connect from Claude Code

Add Octocom to your project's .mcp.json (or your user-level Claude Code config):

{
  "mcpServers": {
    "octocom": {
      "type": "http",
      "url": "https://api.octocom.ai/mcp"
    }
  }
}

The first time Claude Code calls an Octocom tool, it will open a browser window for you to authenticate with the Octocom dashboard. After that, the OAuth tokens are cached and the connection stays live.


Connect from ChatGPT

OpenAI calls these apps (formerly "connectors") and they're powered by remote MCP servers. The connector configuration is per-account and available across web, desktop, and mobile once added.

These instructions are valid as of June 5th, 2026. The ChatGPT UI changes frequently — if a menu described below has moved, the latest reference is Developer mode and MCP apps in ChatGPT.

Plan availability: On Plus and Pro plans, ChatGPT only exposes the read-only tools of a custom MCP server, even if the server offers writes. To get full read-write access (creating workflows, sending messages, etc.) you need a Business, Enterprise, or Edu workspace. Because of this, Plus and Pro users should connect to the read-only Octocom endpoint (https://api.octocom.ai/mcp?readonly=true) — it's the only thing ChatGPT will actually use on those plans, and it avoids confusing "tool not available" errors.

Plus and Pro plans (individual)

  1. Navigate to Settings > Apps & Connectors > Advanced settings and toggle Developer mode on. (Without Developer mode, the option to add a custom connector is hidden.)
  2. Go back to Settings > Apps & Connectors and click Create (also labeled "Add custom connector").
  3. Enter the following:
    • Name: Octocom
    • URL: https://api.octocom.ai/mcp?readonly=true
    • Description: anything — ChatGPT uses this to decide when to invoke the connector
  4. Acknowledge the custom MCP server risk notice, then complete the OAuth flow — you'll be redirected to the Octocom dashboard to grant access and then back to ChatGPT.

To use it in a chat: click Tools > Use apps in the composer and toggle Octocom on for that conversation.

Business, Enterprise, and Edu workspaces

On these plans, custom connectors must first be enabled and published at the workspace level by an admin, after which individual members connect.

Step 1 — Admin enables and publishes the connector (one-time setup):

  1. In Workspace settings > Permissions & Roles > Connected data, enable "Developer mode / Create custom MCP connectors".
  2. Go to Workspace settings > Connectors and click Create.
  3. Enter:
    • Name: Octocom
    • URL: https://api.octocom.ai/mcp (or ?readonly=true if you want to restrict the workspace to read-only access)
  4. Publish it to the workspace.

Step 2 — Each member connects:

  1. In Settings > Apps & Connectors, find the published Octocom connector.
  2. Click Connect and complete the OAuth flow with the Octocom dashboard.
  3. In any chat, enable it via Tools > Use apps.

If you want both endpoints available in the same workspace (e.g. a default read-only one plus an opt-in read-write one), publish two connectors named Octocom (read-only) and Octocom, each pointing at the corresponding URL.


Connect from OpenAI Codex CLI

Codex stores MCP server configuration in ~/.codex/config.toml (or a project-scoped .codex/config.toml). Add an [mcp_servers.octocom] table pointing at the Octocom MCP endpoint:

[mcp_servers.octocom]
url = "https://api.octocom.ai/mcp"

Use https://api.octocom.ai/mcp?readonly=true if you want Codex to only see read-only tools.

Octocom MCP uses OAuth, not a static bearer token, so don't set bearer_token_env_var. Instead, after editing the config, authenticate from the CLI:

codex mcp login octocom

This opens your browser, takes you through the Octocom dashboard OAuth flow, and caches the token for future Codex sessions. From the next codex session onwards, the Octocom tools will be available to the agent.

For fine-grained control you can also set enabled_tools / disabled_tools, tool_timeout_sec, or default_tools_approval_mode on the same [mcp_servers.octocom] block — see the Codex configuration reference for the full list of options.


Connect from other MCP clients

Any MCP client that supports remote HTTP MCP servers with OAuth can connect to Octocom. The general steps are:

  1. Add a new remote/HTTP MCP server in your client's configuration.
  2. Use the URL https://api.octocom.ai/mcp.
  3. Leave any OAuth Client ID / Client Secret fields empty — the server handles OAuth dynamic client registration automatically.
  4. Trigger the connection. The client will open the Octocom dashboard in your browser to authenticate, then return you to the client with the connection ready.

If your client doesn't support remote MCP servers directly, you can usually bridge to it using mcp-remote:

npx -y mcp-remote https://api.octocom.ai/mcp

Refer to your MCP client's documentation for the exact configuration format.

Drive the real Copilot from an evaluation agent

Octocom administrators can use run_copilot_turn to start an asynchronous turn of the real Copilot. These evaluation tools are available only through external MCP, so Copilot cannot recursively invoke itself. They use the same prompt and tool assembly as dashboard sessions.

Supply a new UUID runId and a message, then poll get_copilot_run. Use its conversationId for follow-up turns. Each conversation is also saved as a Copilot session owned by you, so you can open it from your Copilot sidebar in the dashboard; the finished run's session.url links to it. Runs are read-write by default, with the same tools a customer's dashboard session has, so use an organization you are authorized to change. Pass readonly: true to inspect without mutating; read-only MCP connections are always read-only. Regular write tools execute immediately, while browser interactions, tests of saved Python actions/HTTP endpoints, manual recurring-job execution and customer messaging retain their approval gates.

When a run returns pendingApprovals, review the exact tool name and stored input. Start a new turn with the same conversation ID, a fresh run ID, and approvalResponses: [{ approvalId, approved, reason? }]. Omit message for that turn and answer every pending request. The server accepts decisions only for unresolved requests in this operator's stored conversation; it rejects fabricated, duplicate, resolved and foreign-conversation IDs. Denial is an actual tool denial, not an instruction for the model to ignore.

Do not automatically approve requests merely to finish an evaluation. An operator or test harness must decide whether the exact request is within the scenario's authorized scope. Use get_copilot_eval_transcript to inspect the complete conversation and tool evidence. Runs and transcripts expire after one hour. Interrupted runs are not retried automatically because a write may already have occurred.

Model selection and internal model identifiers are not exposed through MCP or Copilot, including on admin connections. Bot test conversations and Copilot runs use the configured defaults. Engineers can inspect internal model records through an explicitly requested, authorized production SQL query.

On this page