--- title: "Connect Flowie to an AI assistant (MCP)" description: "Copy-ready MCP configuration for Flowie: which server to pick (the Flowie app or the Exchange API), the production and staging URLs, a ready-to-paste config for Claude Code, Claude.ai, Claude Desktop, ChatGPT, Cursor and VS Code, how sign-in works (OAuth discovery, dynamic client registration, PKCE), the API key option, rate limits and troubleshooting." canonical: "https://docs.get-flowie.com/mcp.md" --- # Connect Flowie to an AI assistant (MCP) This page is self-contained: copy it whole into an assistant, or copy one block from it, and you have a working configuration. Everything here was checked against the live servers. **Short version.** To use Flowie through Claude, ChatGPT, Cursor or any other assistant, add this URL and sign in with your normal Flowie login (SSO and Google included). You do not need an API key, and you do not need to ask Flowie for anything first: ``` https://back.p2p-flowie.com/agent-hub/mcp ``` ## 1. Which server do I want? Flowie publishes two MCP servers. Each runs on production and on staging. | | **App server** (most people want this one) | **API server** | |---|---|---| | What it is | The Flowie app as an MCP server: what Flowie's in-app AI agent can do | The Flowie Exchange API as tools | | What you can do | Purchase requests, approvals, tasks, budgets, flows, forms, partners, payments, documents and invoices, organizations, inbox, custom fields and tags | E-invoicing: send, receive, validate, lifecycle, companies, partners, Peppol/PPF directory | | Acts as | **You**, the signed-in user, with exactly your Flowie permissions | The signed-in user, or the organization an API key belongs to | | How you connect | Sign in (OAuth). No API key. | Sign in (OAuth) **or** an API key header | | Production URL | `https://back.p2p-flowie.com/agent-hub/mcp` | `https://back.p2p-flowie.com/exchange/mcp` | | Staging / sandbox URL | `https://back.flowie.ink/agent-hub/mcp` | `https://back.flowie.ink/exchange/mcp` | **Rule of thumb.** - **A person using Flowie through an LLM** (Claude, ChatGPT, Cursor, Claude Code…) wants the **App server**. This is the usual case. - **An integration** — a system talking to Flowie: an ERP, a script, a backend, an automated pipeline, no person in the loop — uses the **API server**, typically with an API key. You can add both to the same client. They do not share credentials: an API key works only on the API server, and the App server accepts only a sign-in. `https://back.p2p-flowie.com` is **production**. `https://back.flowie.ink` is **staging / sandbox** (synthetic data, test networks). Use production unless you are testing. ## 2. Production — ready-to-paste configuration ### Claude Code ```bash claude mcp add --transport http flowie-app https://back.p2p-flowie.com/agent-hub/mcp ``` Then, inside Claude Code, run `/mcp`, pick **flowie-app**, choose **Authenticate**. A browser opens on the normal Flowie sign-in page (SSO and Google work as usual). Done. Add the API server the same way if you also want the e-invoicing tools: ```bash claude mcp add --transport http flowie-api https://back.p2p-flowie.com/exchange/mcp ``` Or, per project, commit a `.mcp.json` at the repository root: ```json { "mcpServers": { "flowie-app": { "type": "http", "url": "https://back.p2p-flowie.com/agent-hub/mcp" } } } ``` ### Claude.ai and Claude Desktop **Settings → Connectors → Add custom connector**, paste the URL, then **Connect** and sign in with your Flowie login. ``` https://back.p2p-flowie.com/agent-hub/mcp ``` Nothing to fill in besides the URL: no client ID, no client secret. On a Team or Enterprise plan an owner may have to add the connector for the organization first. ### ChatGPT Add a custom connector (Settings → Apps & Connectors, developer mode), paste the URL above and choose **OAuth** as the authentication. ChatGPT registers itself and opens the Flowie sign-in. ### Cursor `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "flowie-app": { "url": "https://back.p2p-flowie.com/agent-hub/mcp" } } } ``` Cursor shows a **Needs login** / **Connect** button next to the server; click it and sign in. ### VS Code (GitHub Copilot agent mode) `.vscode/mcp.json` — note VS Code uses `"servers"` and `"type": "http"`: ```json { "servers": { "flowie-app": { "type": "http", "url": "https://back.p2p-flowie.com/agent-hub/mcp" } } } ``` Start the server from the file (or **MCP: List Servers**) and accept the sign-in prompt. ### Any other MCP client Any client that supports remote MCP over **Streamable HTTP** with OAuth works: give it the URL and nothing else. A client that only speaks stdio can go through a bridge such as `npx mcp-remote https://back.p2p-flowie.com/agent-hub/mcp`. ### Both servers in one file ```json { "mcpServers": { "flowie-app": { "url": "https://back.p2p-flowie.com/agent-hub/mcp" }, "flowie-api": { "url": "https://back.p2p-flowie.com/exchange/mcp" } } } ``` (Add `"type": "http"` for Claude Code's `.mcp.json`; use `"servers"` plus `"type": "http"` for VS Code.) ## 3. Staging / sandbox Same commands, staging host. Sign in with your staging Flowie account. ```bash claude mcp add --transport http flowie-app-staging https://back.flowie.ink/agent-hub/mcp claude mcp add --transport http flowie-api-staging https://back.flowie.ink/exchange/mcp ``` ```json { "mcpServers": { "flowie-app-staging": { "url": "https://back.flowie.ink/agent-hub/mcp" }, "flowie-api-staging": { "url": "https://back.flowie.ink/exchange/mcp" } } } ``` No staging account? The API server also takes a sandbox key that needs no signup: `POST https://back.flowie.ink/exchange/v1/sandbox/bootstrap` returns a `flw_test_…` key (see [auth.md](https://docs.get-flowie.com/auth.md)). ## 4. How sign-in works Both servers implement the standard MCP authorization flow, so a client needs only the server URL. You do not register an application with Flowie, and there is no client ID or secret to obtain. 1. **Challenge.** An unauthenticated call returns `401` with `WWW-Authenticate: Bearer resource_metadata=""`: - App, production: `https://back.p2p-flowie.com/agent-hub/.well-known/oauth-protected-resource/mcp` - API, production: `https://back.p2p-flowie.com/exchange/.well-known/oauth-protected-resource/mcp` - Staging: the same paths on `https://back.flowie.ink`. The JSON-RPC body says `Unauthorized: sign in to Flowie to use these tools.` 2. **Protected-resource metadata** (RFC 9728) names the authorization server: `"authorization_servers": ["https://back.p2p-flowie.com/exchange"]` (staging: `https://back.flowie.ink/exchange`). The API server also lists the Flowie identity provider (`https://login.flowie.me`, staging `https://login.flowieapp.io`), which issues the user tokens behind the sign-in. 3. **Authorization-server metadata** (RFC 8414) at `https://back.p2p-flowie.com/exchange/.well-known/oauth-authorization-server`: | Field | Production value | |---|---| | `authorization_endpoint` | `https://back.p2p-flowie.com/exchange/oauth/authorize` | | `token_endpoint` | `https://back.p2p-flowie.com/exchange/v1/oauth/token` | | `registration_endpoint` | `https://back.p2p-flowie.com/exchange/v1/oauth/register` | | `code_challenge_methods_supported` | `["S256"]` | | `token_endpoint_auth_methods_supported` | `["none"]` (public client) | | `grant_types_supported` | `authorization_code`, `refresh_token` | Staging: replace the host with `https://back.flowie.ink`. 4. **Dynamic client registration** (RFC 7591) is **supported**. The client `POST`s its `redirect_uris` to the `registration_endpoint` and receives a public `client_id` (no secret). A redirect to your own machine (`http://localhost:/…`) is accepted, so desktop and CLI clients work without declaring a callback. 5. **Authorization code + PKCE (S256).** The browser opens the Flowie sign-in — the normal login, so SSO, Google and your company's identity provider all work — then a consent screen. The client exchanges the code at the `token_endpoint`. 6. **Tokens.** The access token lasts **24 hours**. The client renews it with the refresh token on its own: no new sign-in, no new consent. The token is yours: it reaches the organizations you can reach in Flowie, with the permissions you hold in each. On the App server, `list_my_organizations` lists them and every tool takes an optional `organization_id`. ## 5. API key (API server only) For an integration with no person to sign in, send an Exchange API key as a header. The App server does not accept API keys. ```bash # production claude mcp add --transport http flowie-api https://back.p2p-flowie.com/exchange/mcp \ --header "Authorization: Bearer flw_live_..." # staging / sandbox claude mcp add --transport http flowie-api-staging https://back.flowie.ink/exchange/mcp \ --header "Authorization: Bearer flw_test_..." ``` ```json { "mcpServers": { "flowie-api": { "url": "https://back.p2p-flowie.com/exchange/mcp", "headers": { "Authorization": "Bearer flw_live_..." } } } } ``` `flw_live_…` keys work on production, `flw_test_…` keys on staging. Keys are created in the Flowie app (production) or minted with the sandbox bootstrap (staging). A backend that prefers OAuth uses the client-credentials grant described in [auth.md](https://docs.get-flowie.com/auth.md#machine-to-machine-oauth-20-client-credentials). ## 6. Rate limits - **App server** (`/agent-hub/mcp`): **600 JSON-RPC requests per minute per user** — the same budget as a user calling the Exchange API with their own token. Over it, the server answers `429` with `Retry-After` (seconds); wait that long and retry. - **API server** (`/exchange/mcp`): one `tools/call` costs one REST request against your existing API quota (default 600/minute per key or client), with the same `429` + `Retry-After`. ## 7. Troubleshooting | You see | What it means | Fix | |---|---|---| | `401` / `Unauthorized: sign in to Flowie to use these tools.` | The client has not completed sign-in (or the sign-in was cancelled) | Claude Code: `/mcp` → pick the server → **Authenticate**. Claude.ai / Desktop: **Connect** on the connector. Cursor / VS Code: the login button next to the server | | `Server not found` from `claude.ai/api/…/mcp/start-auth/mcpsrv_…` | The claude.ai connector was removed or re-added while Claude Code was running, so it holds a stale connector id | Restart Claude Code, or add the server directly with `claude mcp add --transport http flowie-app https://back.p2p-flowie.com/agent-hub/mcp` | | `tool not found` | The tool lives on the other server | App tools (purchase requests, approvals, tasks, budgets, flows…) are on `/agent-hub/mcp`; e-invoicing tools are on `/exchange/mcp` | | An API key is rejected on `/agent-hub/mcp` | Expected: the App server is sign-in only | Remove the `Authorization` header and sign in, or use `/exchange/mcp` for the key | | `flw_live_…` rejected on `back.flowie.ink` (or `flw_test_…` on production) | Key and environment do not match | Live keys on `back.p2p-flowie.com`, test keys on `back.flowie.ink` | | `429` | Rate limit | Wait for `Retry-After` seconds | | Sign-in shows no organization / wrong data | Signed in on the wrong environment | Production data is on `back.p2p-flowie.com`; `back.flowie.ink` is staging | ## Related - Authentication in depth (API keys, OAuth, handoff, machine-to-machine): - Build with AI (tool catalog, worked workflows, raw JSON-RPC): - Documentation index for LLMs: