> ## Documentation Index > Fetch the complete documentation index at: https://flow9.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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://.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](/api-reference/test-mode). ## 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](/api-reference/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](/api-reference/errors) for the full list and what each means. See also: [OAuth integration](/api-reference/oauth) · [authentication](/api-reference/authentication).