MCP & connectors

MyChatBot exposes four 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, your Sales Platform, or UGC tools from outside MyChatBot, and to understand how those surfaces relate to the connectors you attach to an agent inside the app.

All four 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	Inspect effective agents, models, skills, connectors and knowledge; validate, create, 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 10 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 + a per-account token	A per-account Bearer token (sent in a header)

Keep MCP access keys secret

Product MCP URLs are credentials; 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.

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
Give a MyChatBot agent an external MCP endpoint	A custom connector (see below)

Agents MCP (per-account routine authoring)

The Agents MCP lets an external Claude or Codex session work with the same custom-routine YAML and validator as the editor in MyChatBot. The account comes from the Bearer key; the tools never accept an account_id, so a model cannot switch tenants by changing an argument.

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:

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:

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

Codex (~/.codex/config.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 create, update, dry-run, and cancel operations. 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:

Use the MyChatBot Agents MCP to help me build or update a 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. Use the inventory's effective agents,
models, skills, connectors, and Business Knowledge metadata; remember that
configured status is not a live external-system probe.

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.
Resolve every blocker and explain every warning before asking for separate
approval to start a billed preview. A readiness result is a configuration
check, and the preview is tool-free, so do not claim that either one tested
live connectors, customer data, writes, messages, calls, or other external
effects.

Tools and intended authoring flow

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

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 routines.
3. Draft YAML and validate until valid: true.
4. Review the complete canonical YAML before approving a create or update.
5. Save it, then call get_routine_readiness.
6. Resolve readiness blockers and review its warnings.
7. With separate approval, start a dry run with a small representative input and poll until it completes.
8. Open MyChatBot to inspect history and, when ready, launch a live run or add automation.

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, but the Agents MCP still does not create or edit those automations. No run message, session ID, webhook secret, connector endpoint/header value, OAuth credential, provider config value, skill source, or full agent instructions are returned.

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.

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.

The Agents MCP deliberately stops before live automation

The Agents MCP does not expose live routine execution, schedules, triggers, deletion, agent configuration, connectors, memories, or customer records. Configure those in MyChatBot. A live routine still uses its ordinary account Agent tools and can perform explicitly authored writes; a dry run cannot.

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.

In the app

Open the Sales Platform's Knowledge Base — 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:

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

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

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

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.

In the app

Open Agents → Connectors — 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, Claude Code command, and Cursor config.

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:

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.

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: save conversations as eval scenarios, replay them against current or candidate instructions, score answer stability

Add one area to Claude Code:

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

Cursor:

{
  "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"
      }
    }
  }
}

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 a token

The UGC MCP is authorized by a per-account token (prefixed ugc_mcp_…). MyChatBot issues it for your account and shows the full secret exactly once — copy it immediately; afterward only a masked preview is available. You can revoke a token at any time, which cuts off any client still using it. If you need a UGC token issued, contact support.

2. Connect the client

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

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

Cursor — add a headers block alongside the url:

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

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.

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 Bearer token	Yes — Authorization: Bearer header only

The URL still expresses the selected catalog/account/area, 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 three surfaces above are outbound: MyChatBot exposes them so your external client drives 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 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.

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 for the full app walkthrough (connecting, per-agent toggles, and custom servers).

Test it

Verify a connection from your client:

claude mcp list

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

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:

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.
• 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 for the supported transports.

See also

• Sales tools reference
• Connectors cheat sheet
• Tools & toggles
• Knowledge bases
• Build an agent
• Troubleshooting