Connecting Flow9 to an AI assistant (MCP)

Flow9 ships a Model Context Protocol (MCP) server, so an MCP-capable assistant —

Flow9 ships a Model Context Protocol (MCP) server, so an MCP-capable assistant — Claude (Desktop or web) and other MCP clients — can read and act on your CRM through natural language: “add a note to this lead”, “draft a follow-up workflow”, “summarise this week’s pipeline”.

This guide gets you connected and explains what the assistant can and cannot do.

What you need

• A Flow9 account (the person connecting signs in with their own login).
• An MCP client. The steps below use Claude; any client that supports remote MCP servers with OAuth works the same way.

Endpoint

https://<your-backend>.supabase.co/functions/v1/mcp-server

The server speaks Streamable HTTP + JSON-RPC 2.0 (protocol 2025-06-18) and is protected by OAuth 2.1. You never paste a token — the client runs the OAuth flow for you, including Dynamic Client Registration, so there is nothing to pre-provision.

Connect (Claude)

1. Settings → Connectors → Add custom connector.
2. Name: Flow9 · URL: the endpoint above.
3. Click Connect. A browser window opens.
4. Sign in to Flow9 and approve the consent screen. You choose which permission groups to grant:
   • Records — read/write leads, customers, activities.
   • Automation — read, draft, and trigger workflows; manage webhooks.
   • Messaging (elevated) — off by default. Only grant this to let the assistant send SMS/email or place calls on your behalf (it consumes your plan’s allowance).
   • Admin — off by default. Workspace settings and credentials.
5. Approve and you’re returned to the client — the Flow9 tools are now available.

Tip: keep the browser tab where you signed in open until the consent step completes — the consent page needs your session.

What the assistant can do

Ask in plain language. Behind the scenes the assistant calls typed tools such as whoami, find_record, add_note, create_task, list_activities, pipeline_summary, enroll_in_workforce, and create_workforce_draft — and, for scheduling, find_slots, book_meeting, reschedule_meeting and cancel_meeting, which run the same booking engine as the app (real availability, the team’s routing policy, a calendar event on the rep’s connected calendar). Booking a meeting the prospect asked for is a transactional confirmation, not outreach: the assistant still cannot send SMS, email or calls to your customers.

Every tool call is:

• Tenant-scoped — it can only ever see your workspace’s data.
• Least-privilege — a tool only runs if you granted the matching permission group; read tools are marked read-only.
• Audited — every call is logged with a request id.

Building a workflow by conversation

You can ask the assistant to compose a Workforce (automation):

“Create a workflow that adds a welcome note and a follow-up call task when a new lead is created.”

It returns a link to a draft in Workforce Studio, laid out and ready — a human reviews and publishes it. The assistant can draft and trigger, but publishing stays with a person.

Safety model (why this is safe to connect)

• Secure by default — the MCP surface is off per workspace until enabled; tools are read-only unless you grant write/automation.
• Spend is gated — anything that costs money (sending messages, enrolling into a sending workflow) requires the Messaging group, which is off by default and which the assistant cannot grant itself — only you can, on the consent screen. An assistant (or untrusted text it reads) can never self-authorize spend.
• No bulk/destructive tools — there is no delete-everything tool; actions are record-scoped and reversible.
• Deletion is a request, and it is off by default — a workspace admin turns on “Allow deletion requests” in Settings → Developers (it needs record writes on first). Even then the assistant only asks: the record is hidden, an admin approves or rejects, and the assistant can restore it meanwhile. One record per request.
• Test safely — pair this with a f9_test_ API key for headless testing so nothing real is sent. See test-mode.md.

Headless / server-to-server MCP

For non-interactive clients, the same MCP endpoint also accepts an API key as a Bearer token (Authorization: Bearer f9_live_…) instead of the OAuth flow — the tool surface and scoping are identical. Use a read_only key to pin the connection to read tools. See authentication.

Troubleshooting

Symptom	Cause & fix
”Authorization failed” right after the browser opens	The client requested a scope the auth server doesn’t accept. Flow9’s authorize step takes only OIDC scopes; API permissions come from the consent groups. Remove and re-add the connector to retry with a clean handshake.
Browser can’t load the consent page	You must be signed in to Flow9 in that browser first; sign in, then reconnect.
Tools appear but a write fails with a scope error	You didn’t grant the matching group (e.g. Automation). Reconnect and approve it.
A record won’t create and the error names a field	Call get_object_schema first and send only known fields with valid types. Required fields must be present — e.g. a lead needs a name, but email is optional.
create_task fails	scheduled_at is required — send an ISO‑8601 date/time (e.g. 2026‑08‑10T15:00:00Z).
log_activity fails	Use entity_type lead, deal, customer or account, and an activity_type your workspace defines (call list_activity_types first) — an invalid type is rejected with the list of valid ones.
A write repeatedly returns “an identical call is still in progress”	Short‑lived duplicate protection: an identical call is already running, so a retry is held rather than run twice. Wait a moment and retry — it clears on its own. If it never clears, the write itself is failing and the returned error names the real reason (it is not a stuck lock).

Every tool error carries a machine‑readable code; see the error reference for the full list and what each means.

See also: OAuth integration · authentication.