/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
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 rejected401. 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, andtools/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.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)
Givesend_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.A worked example
The tool-call flow to list, build, and publish an agent. Each call is a JSON-RPCtools/call request
to POST /mcp; the response carries both a structured ApiResponse envelope and the same JSON as text.
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/v1with 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_smsandinitiate_escalationinherit 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 atools/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.