Skip to main content
The Control MCP gateway is a remote MCP server that lets an MCP client — Claude Code, a Claude.ai connector, or any agent runtime — configure and operate your Flowyte tenant through a curated set of safe tools. It’s a thin, scoped wrapper over the same /api/v1 the rest of the platform uses: every tool call re-enters the API, carrying your key, so your organization scoping, scopes, and audit trail all apply exactly as they would over REST. Use it when you want an agent to drive Flowyte — list agents, create and configure one, add knowledge, wire skills and guardrails, deploy the chat widget, test, publish, and text a customer — without writing REST glue. If you’re calling the API directly instead, see For AI agents.
  • Endpoint: https://mcp.flowyte.com/mcp
  • Transport: Streamable HTTP + JSON-RPC 2.0 (stateless, plain JSON)
  • Protocol: MCP 2025-11-25, negotiated down for older clients
  • Auth: Authorization: Bearer flowyte_sk_…

Connect

The client runs initialize to negotiate the protocol, then tools/list to discover the tools your key can call. The server is stateless — there is no session id, and it never pushes changes — so each request is authorized on its own.
Mint a scoped key in the dashboard’s Developer page (Settings → API keys) and grant only the scopes you need. Your key alone determines your organization — no other headers. See Authentication.

Authentication

The gateway accepts only Flowyte-issued bearers — a foreign token is rejected 401. Two credentials work, both resolved by the same resolver /api/v1 uses: The gateway holds no credentials of its own and never touches the database directly. Because each tool call re-runs your key’s scopes and organization isolation, a revoked key stops working instantly and a scope your key lacks fails the same way it would over REST.
Full OAuth (authorization-server metadata, dynamic client registration) is on the roadmap. Today, API-key auth is the supported path — a compliant MCP posture. OAuth-capable clients can already discover the seam: an unauthenticated request returns 401 with a WWW-Authenticate: Bearer resource_metadata="…" header pointing at /.well-known/oauth-protected-resource.

Tools

Tools split into two capability domains, and tools/list is scope-filtered — a key sees only the tools whose scopes it holds. A config-only key never sees the escalation tools, and a connector-only key never sees the control tools.

Control tools

Configure and run an agent. Reads are safe; writes re-run your scopes on the underlying endpoint.
test_agent is not a safe read. It runs the draft agent’s LLM, and the agent’s configured skills may take real actions (webhooks, emails, integration calls). Its annotations say so — prefer a test tenant.
send_sms texts a real person and a text can’t be unsent — its annotations mark it destructive and open-world so your client asks before calling it. Every compliance gate is enforced server-side, exactly as over REST: the recipient needs recorded consent (they texted you first, or you recorded it with record_sms_consent), an opt-out (STOP) is honored, and outside the recipient’s quiet-hours window the text is refused with a nextOpen time to retry after — never silently queued (a reply to someone who texted you within the last 24 hours is exempt, unless your workspace’s strict quiet-hours setting also covers replies). Send the message only; the platform appends your brand and the opt-out disclosure. The text is converted to plain ASCII: smart punctuation is mapped to its plain equivalent; accented letters, emoji and other non-ASCII characters are removed. A text that is empty after that conversion is refused (400), even with media_ids or media_urls (omit text to send the media alone). Pass a unique client_message_id: retrying with the same id returns the original receipt instead of texting twice.
record_sms_consent records a legal attestation that send_sms then relies on. Only record consent the customer actually gave you (a booking form they submitted, a paper they signed, an agreement you documented) — never to get past consent_required.
send_sms (texting a person) and record_sms_consent (an sms:write configuration action) use separate scopes, so a key minted only to send never sees the consent tool, and vice versa. get_sms_contact and get_sms_media need only sms:read. Revoking consent isn’t an MCP tool — call DELETE /api/v1/sms/contacts/{e164}/consent over the REST API. It withdraws only the express consent your workspace recorded (for example a record entered in error); a customer who texted you first keeps conversational consent. A customer asking you to stop texting is an opt-out: add them to the suppression list with POST /api/v1/sms/suppressions (or the dashboard), which blocks every kind of text immediately.

Let your agent handle a conversation

pause_sms_ai → send_sms → resume_sms_ai lets your own software take over one customer’s text conversation from the AI. Give the key sms:send and sms:write. While the contact is paused, the AI stays silent for them, and every text they send is still saved to the conversation (you’ll see it in Observe) and delivered to your webhooks subscribed to sms.message.received. Subscribe a webhook before pausing (POST /api/v1/webhooks, or the dashboard), or your system won’t hear the customer’s replies. pause_sms_ai returns webhookSubscribed: false when no active webhook is subscribed. The pause applies to numbers an agent answers; a number that rings your team keeps ringing them. A text you send within 24 hours of the customer’s last message counts as a reply. The pause has no expiry, so call resume_sms_ai when you’re done. A teammate who takes the thread in the phone app outranks the pause, and send_sms won’t text that customer from any of your numbers while they have it.

Send and read pictures (MMS)

Give send_sms up to 10 media_urls: pictures (JPEG, PNG, GIF) or short videos (MP4, 3GP, MOV), up to 1 MiB each. Each URL must be https:// (port 443 or 8443) and downloadable directly from the public internet within 10 seconds. Flowyte downloads each picture or video, checks its real type and size, and sends its own copy, so the carrier never sees your URL. text is optional when you attach media. A URL that can’t be fetched is refused with media_fetch_failed, a file type outside that list (a PDF, for example) with media_unsupported_type, and a file over 1 MiB with media_too_large; nothing is sent. If Flowyte is already downloading other messages’ media, the call is refused with media_fetch_busy: nothing was sent, so retry shortly with the same client_message_id. A picture goes through exactly the same consent, opt-out, quiet-hours and volume-cap checks as a text, and those checks run before anything is downloaded. The receipt lists what was sent under media. media_ids forwards an attachment your workspace already holds, by id: a picture a customer texted you (its id from a transcript turn’s attachments, or the media array of the sms.message.received webhook), one you sent before (from a send_sms receipt’s media), or one you uploaded with POST /api/v1/sms/media. Use it to forward a customer’s photo to a crew member, or to send back a picture you received. A message carries up to 10 attachments, media_ids and media_urls together. An uploaded id is valid for 24 hours, until you first send it; once sent, and for a picture you received, the id stays valid. A forwarded file must still be one of the types above and at most 1 MiB (a PDF a customer sent can’t be forwarded). An id that is unknown, belongs to another workspace, is a file a visitor uploaded in a web chat, or is an unsent upload older than 24 hours is refused with media_not_found; nothing is sent. get_sms_media reads an attachment back by id: from a send_sms receipt, from the media array of the sms.message.received webhook (pictures a customer sent you), or from a transcript turn’s attachments. It returns the file’s details and a download link that expires after about 5 minutes on purpose. Download right away, and call get_sms_media again for a fresh link instead of storing one. Only text-message attachments are served: a file a visitor uploaded in a web chat isn’t found. Uploading a picture’s bytes (POST /api/v1/sms/media) isn’t an MCP tool, because MCP tool calls carry JSON rather than files. To send a new picture or video that isn’t on a public web address, upload it over the REST API, then pass the returned id to send_sms in media_ids.

Escalation tools

Manage where and when an agent hands a conversation to an external operator agent, and — for connector runtimes — work the live handoff. These tools carry their own scope family, so they only appear for a key that holds it, and they’re enabled once you’ve connected an AI Harness. A connector key holding only escalations:* sees exactly the runtime tools — never a config or control tool. See AI Harnesses for the full setup.

The publish confirm gate

publish_agent changes live traffic, so it’s a two-call operation — never a one-shot:
1

Get the report

Call get_prepublish_report. It compiles the draft, returns what will and won’t change, and mints a short-lived prepublishToken bound to the exact draft you reviewed. The token expires in 10 minutes and is absent if the draft doesn’t compile.
2

Publish with the token

Call publish_agent with that prepublish_token. It verifies the token and that the draft hasn’t changed since the report ran, then freezes a new version. Any edit in between (a configure_agent or configure_skill) invalidates the token — re-run the report and publish with the fresh one.
This guarantees you publish exactly what you reviewed.

A worked example

The tool-call flow to list, build, and publish an agent. Each call is a JSON-RPC tools/call request to POST /mcp; the response carries both a structured ApiResponse envelope and the same JSON as text.
Make a retried create or publish safe by passing a client-generated _meta.idempotencyKey on the tools/call request — a retry with the same key and arguments replays the original result instead of creating a second agent or version.

Safety

  • Curated, task-level tools — not a raw endpoint mirror. Each tool has a closed input schema and is written for an operator agent.
  • Writes re-run your scopes. Every call re-enters /api/v1 with your key, so scope enforcement, organization isolation, and rate limits all apply per call.
  • Publish needs the confirm token from a fresh get_prepublish_report — you can’t publish blind.
  • Texting is compliance-gated server-side. send_sms and initiate_escalation inherit consent, opt-out, quiet-hours, and volume-cap enforcement from the API — the gateway can’t bypass them.
  • Everything is audited. Each tool call lands in your audit trail exactly as the equivalent REST call would.

Errors

Business, validation, and permission failures come back as a tools/call result with isError: true and actionable text (the REST error body) so the model can self-correct — for example, a downstream 403 when your key lacks the underlying scope. JSON-RPC error objects are reserved for protocol faults (unknown tool, malformed request, auth). Next: build against the REST API directly in For AI agents, or set up an AI Harness to work escalated conversations.