Agents MCP & connectors

The Agents MCP lets Claude Code, Codex, Cursor, or your own MCP client build on the Agents Platform: agents, skills, connectors, Business Knowledge, schedules, triggers, and custom routines, with the same YAML and validator as the editor in MyChatBot. This page is its complete setup, safety, and tool reference, and explains how it relates to the connectors you attach to an agent inside the app.

Looking for something else?

I want to…	Go to
Manage sales assistants, leads, chats, channels, knowledge, orders, calendar, or automations from an AI tool	Sales Platform MCP and the Sales tools reference
Set up the whole account from Claude Code or Codex with one browser sign-in	MyChatBot plugin
Query one product catalog	Product search MCP
Generate media, post, or read social analytics and ads; search these docs	Content and Docs MCP
See every MyChatBot MCP server side by side	MCP at MyChatBot
Give an agent an external app or your own MCP server	Connectors

The Agents MCP is where you configure and try things. After a routine is validated and saved, it runs inside MyChatBot and its agents use their enabled connectors; Claude or Codex does not stay in the execution path. See the Agents Platform operating model.

Keep MCP access keys secret

The Agents MCP takes the account's mcp_… access key as a Bearer credential. Keep it private, and never put it in a URL, routine YAML, a skill, or a chat transcript. Only the account owner or an Admin can create keys and see them listed; support revokes them.

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

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 mychatbot-agents \
  "https://api.mychatbot.app/api/mcp/agents" \
  --transport http \
  --header "Authorization: Bearer mcp_YOUR_ACCESS_KEY"

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

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

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 35 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
get_routine_session_history	Reads the routine's recent runs, newest first (scheduled, triggered, manual, and previews): status, error, input, final output, steps, and token metrics; with include_tool_details, each step's own tool calls. May expose customer inputs and tool results, so use it only for a bounded diagnostic

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_session_history	slug: string, limit?: integer (1–50, default 10), run_id?: string, include_tool_details?: boolean, max_tool_result_chars?: integer (0–20,000, default 2,000; 0 = the full stored summary)

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.

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

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.

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.

Other MyChatBot MCP servers

The Sales Platform, product catalogs, content tools, and these docs have their own servers, documented with the Sales Platform: Sales Platform MCP, Product search MCP, and Content and Docs MCP. MCP at MyChatBot compares them all. The same mcp_… access key works on the Agents, Sales, and Content servers; the URL never authorizes a request on its own.

How this relates to connectors

MyChatBot's MCP servers, the Agents MCP included, 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 Sales Platform areas as the Sales Platform MCP, 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 the server exposes (any MCP client works; here with curl):

curl -sS -X POST \
  "https://api.mychatbot.app/api/mcp/agents" \
  -H "Authorization: Bearer mcp_YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A healthy response returns a list of tools. An authorization error means a missing or invalid key.

Best practices

• Do keep the access key in the Authorization header and treat it as an API key; if it leaks, create a new one and ask support to revoke the old one.
• Do validate, show the complete YAML, and get approval before saving a routine; ask separately before a billed preview or switching on a schedule or trigger.
• Don't treat inventory, readiness, or a tool-free preview as proof that live connectors, customer data, or messages work.
• Don't point a custom connector at an unreachable or wrong-transport endpoint — see Connectors cheat sheet for the supported transports.

See also

• MCP at MyChatBot — every MyChatBot MCP server and when to use which
• Agents Platform operating model — configuration plane, production runtime, and Sales boundary
• Build routines with Claude or Codex — the authoring flow step by step
• MyChatBot plugin — guided Sales, Agents, content, and routine work from Claude Code or Codex
• Connectors cheat sheet
• Tools & toggles
• Knowledge bases