---
url: 'https://docs.mychatbot.app/agents/mcp-and-connectors.md'
description: >-
  Complete setup, security, and tool reference for MyChatBot's five MCP surfaces
  and the direct Claude Code plugin.
---

# MCP & connectors

Start with the [MCP surface map](/agents/mcp-overview) if you only need to choose
the right server and setup path. This page is the complete cross-surface setup,
security, and tool reference used by external authoring agents.

MyChatBot exposes five separate MCP (Model Context Protocol) surfaces you can attach to an external MCP client — Claude Code, Codex, Cursor, or your own tooling. Use this page when you want to author Agents Platform routines, drive product search, operate your Sales Platform, use UGC tools, or traverse the public docs from *outside* MyChatBot, and to understand how those surfaces relate to the **connectors** you attach *to* an agent inside the app.

These external surfaces form the configuration and prototyping plane. After promotion,
the saved routine runs inside MyChatBot and its agents use enabled runtime connectors;
Claude or Codex does not remain in the execution path. See the complete
[Agents Platform operating model](/agents/operating-model).

All five speak the standard MCP protocol, so any compatible MCP client can connect. What differs is the scope (how much of your account a surface can touch) and how each one is secured. For the Agents MCP, the app gives you ready-to-paste Claude Code and Codex setup; the other surfaces provide their own connection details as described below.

## Cheat sheet

| Surface | What it drives | Where the app hands you the setup | How it's secured |
|---|---|---|---|
| **Agents MCP** | Configure agents, skills, connectors, knowledge and staged automation; validate, save, check and preview custom routines | Any Agent → **Tasks** → **Connect Claude or Codex** | A per-account `mcp_…` **Bearer access key** |
| **Product MCP** | One indexed product catalog (semantic + attribute search) | Knowledge Base → a connected **Products** card → **⋯** menu → **Connect AI tools** | The address itself is the key — no token |
| **Sales-Management MCP** | Your Sales Platform (assistants, leads, chats, channels, knowledge base, orders, calendar…), as 12 focused areas or one combined server | Agents → **Connectors** → a **From your sales platform** card → the small **i** (**Connect AI tools**) | A per-account `mcp_…` **Bearer access key** |
| **UGC MCP** | Content, posting, analytics, and ads for one business | Server address below + the account access key | The same per-account `mcp_…` **Bearer access key**; legacy `ugc_mcp_…` keys also work |
| **Docs MCP** | Search the docs outline and read current raw Markdown pages | Public endpoint below | No credential; public and read-only |

::: warning Keep MCP access keys secret
Product MCP URLs are credentials; Agents, Sales-Management, and UGC use Bearer credentials. Keep all of them private. The Sales account and area in the URL select scope but do not authorize a request. The Docs MCP is the exception: it contains public documentation only and requires no account credential.
:::

### Which surface do I want?

| I want to… | Use |
|---|---|
| Have Claude or Codex build and safely preview complex routine YAML | **Agents MCP** — copy the setup from an Agent's Tasks tab |
| Query one product catalog by semantic / attribute search | **Product MCP** — copy it from the catalog's **Connect AI tools** dialog |
| Manage assistants, chats, leads, channels, knowledge base, orders, calendar… | **Sales-Management MCP** — pick an area on the Connectors page |
| Generate media, schedule posts, read social analytics or ads | **UGC MCP** — needs a per-account token |
| Search or read current MyChatBot documentation | **Docs MCP** — public, read-only, and account-free |
| Give a MyChatBot **agent** an *external* MCP endpoint | A **custom connector** (see below) |

## Agents MCP (per-account system and routine authoring)

The Agents MCP lets an external Claude or Codex session assemble the supporting
Agents Platform configuration and work with the **same custom-routine YAML and
validator** as the editor in MyChatBot. It is an authoring and testing surface,
not a second workflow format. Agents, skills, connectors, Business Knowledge,
schedules, triggers and routines continue to use their ordinary MyChatBot
records and runtime.

For the user-facing sequence—from connecting Claude through preview and staged
activation—follow [Build and test a routine with
Claude](/guides/build-routines-with-claude). This section is the exact tool and
safety reference behind that guide.

The account comes only from the Bearer key. None of the tools accepts an
`account_id`, so a model cannot switch tenants by changing an argument.

::: tip In the app
Open any Agent, choose **Tasks**, then **Connect Claude or Codex**. Create an access key and copy the Claude Code command or Codex `config.toml` block. The full key is shown only once.
:::

Server address:

```text
https://api.mychatbot.app/api/mcp/agents
```

The server's initialize response tells the coding assistant to call
`get_routine_authoring_context` before drafting. That tool returns these
machine-readable Markdown references, so Claude or Codex does not have to infer
the YAML format from examples alone:

| Reference | Markdown URL |
|---|---|
| Complete field-by-field YAML contract | `https://docs.mychatbot.app/agents/routine-yaml-reference.md` |
| Custom-routine lifecycle and safety guide | `https://docs.mychatbot.app/agents/custom-routines.md` |
| MCP setup and boundaries (this page) | `https://docs.mychatbot.app/agents/mcp-and-connectors.md` |
| Documentation index for coding assistants | `https://docs.mychatbot.app/llms.txt` |

Claude Code:

```bash
claude mcp add mychatbot-agents \
  "https://api.mychatbot.app/api/mcp/agents" \
  --transport http \
  --header "Authorization: Bearer mcp_YOUR_ACCESS_KEY"
```

::: tip Server name and URL first, flags after
`--header` takes a list, so Claude Code reads everything following it as another
header. Keep the name and URL at the front of the command — move a flag ahead of
them and it stops with `error: missing required argument 'name'`.
:::

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.mychatbot-agents]
url = "https://api.mychatbot.app/api/mcp/agents"
http_headers = { Authorization = "Bearer mcp_YOUR_ACCESS_KEY" }
default_tools_approval_mode = "writes"
```

`writes` lets Codex use discovery and validation tools automatically while
asking before configuration changes, routine saves, billed previews, and
cancellation. Both snippets store the key in the client's configuration, so
protect that file like any other credentials file.

The `mcp_…` credential is an account-wide MyChatBot MCP key, not a key scoped
only to routines. The Agents server exposes only the narrow tools below, but the
same key can authorize another account MCP surface if someone configures its
server address. Revoke an exposed key through support.

### Starter prompt

After connecting, paste this into Claude Code or Codex:

```text
Use the MyChatBot Agents MCP to help me configure an agentic system and build or
update its custom routine.

First call get_routine_authoring_context and read the Markdown documentation
URLs it returns, especially routine_yaml_reference_markdown. Then call
get_account_authoring_inventory, list my existing custom routines, and inspect
any relevant routine before drafting. Prefer reusing existing resources. Read
an agent or skill before a full replacement and preserve every field I want to
keep. Never ask me to paste a connector credential into an MCP tool: give me an
OAuth consent URL when supported, and direct me to the MyChatBot app for API-key
or authenticated custom connectors.

Show me every proposed create, replacement, reset, disconnect, or delete and
wait for explicit approval. A connector probe is a real connection and tool-list
discovery only; ask before it and do not claim it read customer data or tested a
connector operation.

Use only the documented YAML format. Validate the complete YAML until it is
valid, show me the complete canonical YAML, and wait for my explicit approval
before creating or updating it. After saving, call get_routine_readiness and
resolve every blocker. Ask separately before starting a billed, tool-free
preview. Create any schedule or trigger disabled, show me the staged resource,
and ask separately before enabling it. Do not claim that inventory, readiness,
or preview tested live connectors, customer data, writes, messages, calls, or
other external effects.
```

### Tool reference

The server currently exposes 34 tools. All top-level input objects are closed:
an unknown argument is rejected. The compact signatures below use `?` for an
optional value. Your MCP client receives the complete JSON Schema, including
string lengths, patterns, numeric bounds, enums, nested object shapes, and
read/write/destructive annotations, from `tools/list`.

#### Discovery and custom routines

| Tool | Effect |
|---|---|
| `get_routine_authoring_context` | Returns the YAML node types, limits, reserved names, rollout notes, documentation URLs, and an example |
| `get_account_authoring_inventory` | Returns effective routine-capable agents/models, skill metadata, connector catalog/configured health, Business Knowledge metadata, and trigger sources—without credentials or external probes |
| `list_routines` / `get_routine` | Reads saved custom routines and their normalized YAML; built-in routines are outside this authoring surface |
| `validate_routine` | Validates without saving; returns every error, canonical YAML, a conservative Agent-call estimate, and preview eligibility |
| `create_routine` / `update_routine` | Saves a validated custom routine after you approve the final YAML |
| `get_routine_readiness` | Checks a saved routine's explicit agent/model/skill/connector/knowledge dependencies and shows redacted schedule/trigger bindings, blockers, warnings, fan-out and preview coverage |
| `start_routine_dry_run` | Starts a billed, persisted, **tool-free** preview of a saved custom routine |
| `get_routine_run` | Polls a preview and returns bounded output or its error |
| `cancel_routine_run` | Requests cooperative cancellation at the next workflow checkpoint |

The routine tools accept these principal values:

| Tool | Parameters |
|---|---|
| `get_routine` | `slug: string` |
| `validate_routine` | complete routine `spec_yaml: string` |
| `create_routine` | complete routine `spec_yaml: string` |
| `update_routine` | `slug: string`, complete routine `spec_yaml: string` |
| `get_routine_readiness` | `slug: string` |
| `start_routine_dry_run` | `slug: string`, representative `message: string` |
| `get_routine_run` | `slug: string`, opaque `run_token: string` returned by the start call |
| `cancel_routine_run` | `slug: string`, opaque `run_token: string` returned by the start call |

`get_routine_authoring_context`, `get_account_authoring_inventory`, and
`list_routines` take no parameters.

#### Agents and skills

| Tool | Parameters and effect |
|---|---|
| `get_agent` | `slug: string`; read the effective configuration before replacement |
| `claim_custom_agent` | `slug`, `display_name`, `model_alias`; optional `instructions`, complete `tools_enabled` and `connectors_enabled` maps, `attached_skills`, `template_tasks`, `labels`, `disabled`, `memory_capture`, `description`, `avatar` |
| `hire_library_agent` | `slug: string`; add an available Library agent |
| `replace_agent_configuration` | `slug` plus any agent fields above; **full replacement**, so omitted overrides revert to platform defaults |
| `reset_agent_configuration` | `slug: string`; remove overrides while preserving sessions |
| `delete_custom_agent` | `slug: string`; delete a claimed custom agent, its sessions, and schedules |
| `get_skill` | `name: string`; read full skill content before replacement |
| `create_skill` | required `name`, `description`, `instructions`; optional `scripts`, `references`, `allowed_tools`, `metadata`, `labels` |
| `replace_skill` | the same skill fields; **full replacement**, so include all content that must remain |
| `delete_skill` | `name: string`; account-authored skills only |

Each script or reference item has `name: string`, `content: string`, and an
optional `interpreter: string`. Dynamic maps such as tool toggles and skill
metadata remain maps because AgentOS intentionally supports changing catalogs;
the surrounding shapes and sizes are still validated.

#### Connectors and Business Knowledge

| Tool | Parameters and effect |
|---|---|
| `start_connector_authorization` | `toolkit: string`; start OAuth and return a human consent URL |
| `connect_sales_platform_connector` | `toolkit: string`; enable one `sales_…` account domain without OAuth |
| `disconnect_connector` | `toolkit: string`; revoke/remove its stored authorization and possibly affect event triggers |
| `probe_connector` | `toolkit: string`; perform a real MCP handshake and bounded tool discovery, without invoking a discovered tool |
| `create_knowledge_source` | required `provider_type`, `provider_id`, `display_name`; optional provider `config` and `read_only` (defaults to `true`) |
| `update_knowledge_source` | `provider_id` plus one or more of `display_name`, provider `config`, `enabled`, `read_only` |
| `delete_knowledge_source` | `provider_id: string` |

`provider_type` is one of `web`, `drive`, `notion`, `slack`, `onedrive`,
`gmail`, `calendar`, `products_faq`, `products_catalog`, `products_feed`,
`products_spreadsheet`, or `products_business_docs`. Provider `config` is a
provider-specific object: product sources use `integration_id`; Web may use
`timeout_seconds`, `include_tools`, and `tool_name_prefix`; Composio sources may
use `toolkit_slug`.

::: warning Connector credentials never go through the model
OAuth tools return a URL for a human to open. API-key connector secrets and
authenticated custom-MCP headers must be entered in the MyChatBot app. Do not
paste them into Claude, Codex, prompts, skill files, routine YAML, or MCP tool
arguments.
:::

#### Schedules and triggers

| Tool | Parameters and effect |
|---|---|
| `create_routine_schedule` | required `slug`, five-field `cron_expr`; optional IANA `timezone`, `run_message`, `name`, `description`; always created **disabled** |
| `set_routine_schedule_enabled` | `slug`, `schedule_id`, `enabled: boolean`; enabling permits future cron fires |
| `delete_routine_schedule` | `slug`, `schedule_id` |
| `create_trigger` | required `target_kind: "routine" | "agent"`, `target_slug`; optional `kind: "webhook" | "connector_event"`, `name`, `source_slug`, `message_template`, `source_config`, `dedup_key_path`, `max_fires_per_hour` (1–120); always created **disabled** |
| `set_trigger_enabled` | `trigger_id`, `enabled: boolean`; enabling a connector-event trigger may create an external subscription |
| `delete_trigger` | `trigger_id`; also tears down an existing external subscription |

`source_config` is a closed object with optional `filters` and
`trigger_config`. `filters` maps event dot-paths to a string, number, boolean,
membership array, or `{ "contains": "text" }` predicate. `trigger_config`
accepts only typed, non-secret fields from the curated trigger catalog, and the
selected source is checked again before creation for unsupported or missing
fields. If that source requires a provider credential, configure the trigger in
the MyChatBot app instead—the MCP never accepts the credential.

The MCP forces every schedule and trigger create to `enabled: false`, even if a
client tries to infer another default. Enabling is a separate write that needs
its own review and approval. Existing schedules and triggers made in the app
retain their existing behavior.

For a webhook trigger, the MCP returns the trigger identifier and staged state
but not its tokened URL or internal session identifier. Copy the secret webhook
URL from the routine's **Automations** panel in MyChatBot and give it only to
the service that should fire the trigger.

### End-to-end setup flow

A good external authoring session follows this order:

1. Read the authoring context and its Markdown references.
2. Read the account inventory and inspect existing agents, skills, connectors,
   Business Knowledge, and routines. Prefer reuse over duplication.
3. If a connector is missing, initiate OAuth and let the human open its consent
   URL, connect a Sales Platform domain, or direct the human to the app for a
   secret-bearing connector. Refresh inventory afterward.
4. With approval, create or change the minimum supporting skills, knowledge,
   and agent configuration. Read before every full replacement.
5. If useful, separately approve `probe_connector`. Treat its discovered tools
   as connectivity metadata, not proof of a customer-data read or write.
6. Draft routine YAML and validate until `valid: true`.
7. Review the complete canonical YAML before approving a create or update.
8. Save it, call `get_routine_readiness`, resolve blockers, and review warnings.
9. With separate approval, start a billed dry run using a small representative
   input and poll until it completes. Remember that this preview is tool-free.
10. Stage any schedule or trigger disabled. Review the target, cron/event,
    message, limits, connector dependencies, and preview history.
11. Ask for a final, separate approval before enabling automation. Inspect live
    history in MyChatBot after it starts running.

### What inventory and readiness prove

The inventory is an account-scoped, secret-free view of **configured state**.
It does not sign in to Gmail, query HubSpot, search a product catalog, fetch a
web page, or call any other external system. A connection shown as active means
MyChatBot has an active configuration row—not that the provider will answer the
next request.

Readiness checks the saved routine's explicit YAML references against that
inventory. `ready: true` means no known configuration blocker was found. It
does **not** prove live connectivity, available customer data, write safety, or
exactly-once execution. If part of the inventory could not be read, readiness
fails closed instead of treating the missing evidence as an empty account.

Readiness also returns redacted schedule and trigger bindings. The inventory is
deliberately compact and secret-free; use the dedicated resource read tools
when full agent instructions or skill source are needed. No session ID, webhook
secret, connector endpoint/header value, OAuth credential, or stored secret is
returned.

::: warning Business Knowledge connector boundary
Product-search and Web knowledge providers have read-oriented provider
surfaces. A Composio-backed Business Knowledge provider currently reuses its
ordinary connector MCP, whose tool list may include writes; its stored
`read_only` flag is not yet a runtime tool filter. Readiness reports this as a
warning. Do not treat that warning as a successful read-only dry-run check.
:::

### Connector probe versus routine dry run

These are deliberately different operations:

| Check | External connection? | Invokes a connector tool? | Calls models / runs the workflow? | Persisted and billed? |
|---|---:|---:|---:|---:|
| Inventory/readiness | No | No | No | No |
| `probe_connector` | Yes | **No**—initialize and `tools/list` only | No | No |
| `start_routine_dry_run` | No connector connection | No—all tools are removed | Yes | **Yes** |

### What “dry run” means

The preview executes the real sequence/parallel/loop/condition/router/foreach graph and calls the selected models, so it **uses Agents balance** and its result is saved in routine history. Before any step runs, AgentOS removes all tools—including local skills, code/browser tools, connectors, Business Knowledge and Sales Platform tools—disables account-memory reads and writes, and adds a system rule that proposed reads/writes must be described as simulations, never as completed actions.

To bound cost, an MCP dry run must have a statically calculable worst case of at most **25 Agent calls**. Dynamic foreach sources such as `items: "{previous}"` and larger graphs remain valid for live routines, but preview them first with a small literal sample. The production YAML limits are unchanged; this is only a preview limit.

::: warning The Agents MCP deliberately stops before live execution
The MCP can configure resources and stage or explicitly enable automation, but
it does not expose an immediate live-routine run. A live scheduled or triggered
routine uses its ordinary account Agent tools and can perform explicitly
authored external reads and writes; a dry run cannot. The MCP also does not
expose memories or Sales Platform customer records through the Agents surface.
:::

## Product MCP (per-catalog)

Scoped to a single indexed product catalog — one integration on one account. You don't need to assemble the address by hand.

::: tip In the app
Open the **Sales Platform's Knowledge Base** — [app.mychatbot.app/knowledge-base](https://app.mychatbot.app/knowledge-base) (the product page, not the Agents-Platform **Knowledge** section) — find a connected **Products** card, open its **⋯** menu, and choose **Connect AI tools**. The dialog shows the server address plus a copy-paste Claude Code command and Cursor config for exactly this catalog.
:::

The server address looks like this (the dialog fills in your account and catalog):

```
https://product.mychatbot.app/mcp/<account_id>/<integration_id>/stream
```

Add it to Claude Code:

```bash
claude mcp add product-search \
  "https://product.mychatbot.app/mcp/<account_id>/<integration_id>/stream" \
  --transport http
```

Cursor (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "product-search": {
      "url": "https://product.mychatbot.app/mcp/<account_id>/<integration_id>/stream"
    }
  }
}
```

::: tip One catalog per server
Each product catalog is its own MCP server. To search two catalogs, add two entries with two addresses (and two distinct server names) — copy each from the matching catalog's **Connect AI tools** dialog.
:::

## Sales-Management MCP (per-account, per-area)

One MCP surface for your whole Sales Platform. You can attach a single **area** (leads only, knowledge base only, …) to keep the tool list focused, or attach the combined server that exposes every area at once — the same all-tools view the agent's **Sales Platform tools** toggle relies on.

::: tip In the app
Open **Agents → Connectors** — [app.mychatbot.app/agents/connectors](https://app.mychatbot.app/agents/connectors). In the **From your sales platform** section, click the small **i** (**Connect AI tools**) on any area card to get its server address, access key, and client setup. The examples below cover Claude Code, Codex, and Cursor.
:::

The server address carries your account and the chosen area:

```
https://api.mychatbot.app/api/mcp/sales-management?account_id=<account_id>&domain=<area>
```

Every external request also carries the per-account access key from the **Connect AI tools** dialog:

```text
Authorization: Bearer mcp_YOUR_ACCESS_KEY
```

The full key is shown only when you create it. If the dialog shows only a masked existing key and you no longer have the secret, create a new key and update your MCP client. Creating a new key does not revoke existing keys.

Every tool each area exposes is documented with full parameters in the **[Sales tools reference](/agents/sales-tools-reference)**.

The 12 areas map to the Sales Platform sidebar (Testing & evals is tool-only — it has no Sales Platform page):

| Area (`domain`) | Sidebar label | What it exposes |
|---|---|---|
| `sales_assistants` | Configurations | Create/edit assistants, manage their skills, run test chats |
| `sales_clients` | Leads | Contacts — full note and attachment-record CRUD, tasks, labels, pipeline stages |
| `sales_conversations` | Chats | Chat history and message context |
| `sales_channels` | Channels | Messaging channels and their setup links |
| `sales_outreach` | FollowUp | Follow-up campaigns, one-off messages, outbound calls |
| `sales_knowledge` | KnowledgeBase | FAQs, product catalogs, and product feeds |
| `sales_integrations` | Integrations | Your third-party integrations and their config links |
| `sales_account` | Dashboard | Account summary, subscription, and usage stats |
| `sales_orders` | Orders | Orders and order stats |
| `sales_calendar` | Calendar | Calendar events, staff, and services |
| `sales_automations` | Automations | Lead Forms automation: list Meta Lead Gen forms, diagnose routing, configure per-form mappings (writes are confirm-gated) |
| `sales_evals` | — | [Testing & evals](/agents/testing-and-evals): save conversations as eval scenarios, replay them against current or candidate instructions, score answer stability |

Add one area to Claude Code:

```bash
claude mcp add mychatbot-sales \
  "https://api.mychatbot.app/api/mcp/sales-management?account_id=<account_id>&domain=sales_knowledge" \
  --transport http \
  --header "Authorization: Bearer mcp_YOUR_ACCESS_KEY"
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.mychatbot-sales]
url = "https://api.mychatbot.app/api/mcp/sales-management?account_id=<account_id>&domain=sales_knowledge"
http_headers = { Authorization = "Bearer mcp_YOUR_ACCESS_KEY" }
default_tools_approval_mode = "writes"
```

The `writes` approval mode lets Codex perform Sales reads while asking before write tools.
Read calls still touch real account data; message, call, delete, and live-record effects
need deliberate review regardless of client configuration.

When configuring campaigns, connect `sales_outreach`, `sales_channels`, and—when targeting
needs account data—`sales_clients`, then follow
[Build and operate outreach with Claude or Codex](/guides/build-outreach-with-claude).

Cursor:

```json
{
  "mcpServers": {
    "mychatbot-sales": {
      "url": "https://api.mychatbot.app/api/mcp/sales-management?account_id=<account_id>&domain=sales_knowledge",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_ACCESS_KEY"
      }
    }
  }
}
```

::: tip One area vs the combined server
Attach one server per area to keep each client's tool list small and focused, or drop `&domain=…` for a single server that exposes every area at once. The combined server is broader but noisier for the model.
:::

### Client notes and attachments

The `sales_clients` area exposes complete note operations:

* `client_list_notes`, `client_get_note`, `client_create_note`, `client_update_note`, `client_delete_note`

It also exposes complete attachment-record operations:

* `client_list_attachments`, `client_get_attachment`, `client_create_attachment`, `client_update_attachment`, `client_delete_attachment`

`client_create_attachment` registers metadata for an **already-hosted HTTP(S) file URL**. It does not upload bytes. Required inputs are `client_id`, `file_name`, and `file_url`. Optional metadata fields are `file_size` in bytes, `file_type` as a MIME type, `description`, and `folders` such as `internal`, `sent`, or `received`. On update, an empty `description` or `file_type` clears that field, an empty `folders` array clears document sections, and `file_size: 0` resets the recorded size. Deleting an attachment record does not delete the remote file.

## UGC MCP (per-account)

The UGC surface exposes content, posting, analytics, and ads tools for **one** business. Like Sales-Management, it requires a **per-account Bearer token**. Unlike Sales-Management, the account is derived entirely from that token, so the address doesn't carry your account id.

```
https://api.mychatbot.app/api/mcp/ugc?domain=<content|posting|analytics|ads>
```

Four areas (omit `domain` to expose every UGC tool at once):

| `domain` | What it does | Plan / balance gate |
|---|---|---|
| `content` | Generate media, poll media tasks, text-to-speech | Balance-metered — needs a positive balance, no plan requirement |
| `posting` | Create posts, timelines, best-times, posting frequency | Requires a social paid plan |
| `analytics` | Post analytics, engagement decay, daily metrics, campaign tree | Requires a social paid plan |
| `ads` | List ad accounts, ads, and campaigns | Requires the stricter ads plan (Scale+) |

### 1. Get an account access key

The UGC MCP accepts the same per-account `mcp_…` access key as the Agents and
Sales-Management MCPs. Create one from any Agent's **Tasks → Connect Claude or
Codex** dialog. MyChatBot shows the full value exactly once; afterward only a
masked preview is available. Legacy `ugc_mcp_…` keys remain valid across all
account MCP surfaces. You can revoke a key to cut off every client that still
uses it.

### 2. Connect the client

Claude Code — pass the token as a header, never in the URL:

```bash
claude mcp add mychatbot-ugc \
  "https://api.mychatbot.app/api/mcp/ugc?domain=content" \
  --transport http \
  --header "Authorization: Bearer mcp_YOUR_ACCESS_KEY"
```

Cursor — add a `headers` block alongside the `url`:

```json
{
  "mcpServers": {
    "mychatbot-ugc": {
      "url": "https://api.mychatbot.app/api/mcp/ugc?domain=content",
      "headers": { "Authorization": "Bearer mcp_YOUR_ACCESS_KEY" }
    }
  }
}
```

::: warning The UGC token spends money
Content generation bills your account balance. The token is accepted **only** via the `Authorization: Bearer` header — a token placed in the query string is rejected. Store it like an API key, and revoke it if it leaks.
:::

## Docs MCP (public, read-only)

The Docs MCP lets a coding agent traverse the same current Markdown corpus as
this site. It has no account scope and accepts no credential. Its upstream host
is fixed to `docs.mychatbot.app`: none of its tools accepts a URL, so it cannot
be used to fetch an arbitrary website.

Server address:

```text
https://api.mychatbot.app/api/mcp/docs
```

It exposes three read-only operations:

| Tool | What it returns |
|---|---|
| `get_docs_structure` | The annotated documentation outline and page paths |
| `search_docs` | Up to 10 matching pages with bounded excerpts |
| `read_docs_page` | One raw Markdown page from the docs host, with tables and callouts intact |

Claude Code:

```bash
claude mcp add mychatbot-docs \
  "https://api.mychatbot.app/api/mcp/docs" \
  --transport http
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.mychatbot-docs]
url = "https://api.mychatbot.app/api/mcp/docs"
```

Start with `get_docs_structure`, or use `search_docs` for concrete feature and
button names. Follow a result with `read_docs_page` rather than relying on a
short search excerpt. A docs result is product guidance, not evidence about the
connected account or a live external system.

## How each surface is secured

| Surface | How it's scoped | Secret required? |
|---|---|---|
| Agents MCP | Account resolved entirely from the Bearer token | Yes — `Authorization: Bearer mcp_…` |
| Product MCP | Account + catalog, baked into the address | No — the address *is* the key |
| Sales-Management MCP | Bearer key resolves the account; `account_id` is cross-checked and `domain` limits the tools | Yes — `Authorization: Bearer mcp_…` |
| UGC MCP | Account resolved from the same account access key as Agents and Sales; legacy UGC keys remain valid | Yes — `Authorization: Bearer mcp_…` header only |
| Docs MCP | Public documentation corpus; fixed upstream host and no account access | No |

The URL still expresses the selected catalog/account/area where applicable,
while Bearer-authenticated surfaces independently resolve or verify account
ownership. Never rely on an `account_id` query parameter as authorization.

## How this relates to connectors

The five surfaces above are **outbound**: MyChatBot exposes them so *your*
external client can configure, query, or learn about the platform. **Connectors**
are the **inbound** direction — they let a MyChatBot **agent** reach out to
tools. There are three families, all managed at **Agents → Connectors**:

| Connector family | What it is | How it's set up |
|---|---|---|
| **From your sales platform** | The same 10 Sales Platform areas listed above, attached to an agent | One click on the Connectors page — no sign-in |
| **External apps** (HubSpot, Gmail, Slack, Notion, Stripe, …) | A third-party app's tools, scoped to your account (powered by our connector service) | One-time sign-in on the Connectors page (Stripe: a pasted API key) — or [straight from a chat](/agents/custom-connectors#connect-apps-from-chat) when the agent suggests it |
| **Custom** | Any MCP server you host yourself | You supply the server address, transport, and headers |

A **custom connector** has no sign-in and no credential refresh — you provide the endpoint and any headers directly. That means you can even point one back at a MyChatBot surface (for example, hand an agent the UGC MCP by pasting the UGC address plus its `Authorization: Bearer` header), though the **From your sales platform** connectors already cover the Sales-Management case with no manual URL.

::: warning A Sales Platform area and an external app can't both hold the same slot
On the Connectors page a **From your sales platform** connector and an external-app connector **can't both be connected for the same slug at once**. Disconnect one before connecting the other.
:::

See **[Connectors cheat sheet](/agents/custom-connectors)** for the full app walkthrough (connecting, per-agent toggles, and custom servers).

## Test it

Verify a connection from your client:

```bash
claude mcp list
```

Or list the tools a surface exposes (any MCP client works; here with `curl`):

```bash
curl -sS -X POST \
  "https://api.mychatbot.app/api/mcp/sales-management?account_id=<account_id>&domain=sales_knowledge" \
  -H "Authorization: Bearer mcp_YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

For the UGC surface, add the token header:

```bash
curl -sS -X POST \
  "https://api.mychatbot.app/api/mcp/ugc?domain=content" \
  -H "Authorization: Bearer ugc_mcp_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A healthy response returns a list of tools. An empty list, or an authorization error, means a missing/invalid token or an unknown area.

## Best practices

* **Do** attach one area (or one catalog) per server so each client sees a small, focused tool list.
* **Do** keep Sales-Management and UGC Bearer keys in headers and treat them as API keys; revoke and reissue them if they leak.
* **Do** use the Docs MCP without credentials; a docs response never proves account state.
* **Don't** paste the UGC token into a URL or the `domain` query string — it will be rejected.
* **Don't** put a Sales-Management access key in the URL or assume an account id grants access; only the Bearer header authorizes the call.
* **Don't** point a custom connector at an unreachable or wrong-transport endpoint — see [Connectors cheat sheet](/agents/custom-connectors) for the supported transports.

## See also

* [Agents Platform operating model](/agents/operating-model) — configuration plane, production runtime, and Sales boundary

* [MyChatBot agent plugin](/agents/claude-code-plugin) — guided Sales, Agents, content, and routine work from Claude Code or Codex

* [Sales tools reference](/agents/sales-tools-reference)

* [Connectors cheat sheet](/agents/custom-connectors)

* [Tools & toggles](/agents/tools-and-toggles)

* [Knowledge bases](/agents/knowledge-bases)

* [Build an agent](/agents/build-an-agent)

* [Troubleshooting](/agents/troubleshooting)