Connect any MCP app to Zyflow: URL, API key or local bridge

# Which way should your app connect?

It depends on what your app’s MCP settings support. Use your Zyflow link with sign-in if you can, an API key if your app can send a fixed header but can’t sign in, and the bridge if it can only start local (stdio) servers. The bridge needs an API key too.

Prefer your Zyflow link with sign-in when your app supports it, because there’s no secret to store. Each app also gets its own line under Connected apps and puts its registered name on every change, so you can disconnect one without touching the others.

# Connect with the server URL and sign in (OAuth)

Paste your Zyflow link into your app. Zyflow answers the app’s first request with a 401 that points to its sign-in details. An app that supports MCP authorization then registers itself and opens your browser, where you sign in and approve one workspace. Zyflow accepts dynamic client registration and client ID metadata documents, and requires PKCE (S256).

Steps

1. Paste https://app.zyflowcrm.com/mcp where your app adds a remote MCP server. Field names vary by app.

2. Your browser opens. Sign in to Zyflow, or create a free account. No account yet? Get your Zyflow link first, then paste it.

3. Choose one workspace, then press Approve.

4. Your app appears under Connected apps on the Connect page.

What your app needs

What you’ll see when you approve

The approval screen shows the app’s name and logo, the host you’ll return to, and a workspace picker. Apps with a client ID metadata document also show “Verified app from <domain>”. That names the domain that published the app’s details; Zyflow hasn’t reviewed the app.

The scopes are crm:read and crm:write. There’s no read-only switch on the sign-in screen yet; an app that asks only for crm:read gets read-only access. Access tokens last 60 minutes. Refresh tokens last 90 days and rotate on every use. If an app reuses a replaced refresh token more than 30 seconds later, Zyflow ends the connection.

Your app’s changes show the name it registered, as in “Added by <App> via MCP”, and each one can be undone.¹ An app that registers no name shows as “An AI app”.

Disconnect an app

On the Connect page, press Disconnect next to the app under Connected apps. Every token it holds stops working at once. Your records stay as they are.

# Use an API key as a Bearer token

If your app can’t sign in with OAuth but can send a header, create an API key on the Connect page and send it as a Bearer token in the Authorization header. Keys start with zf_live_. Choose Read only if the app only needs to look things up, and keep that key just as private: a read-only key can still export the workspace. Keys don’t expire, so revoke any key you stop using.

Steps

1. On the Connect page, go to API keys and press New key.

2. Name the key after the app or script that will use it, such as “Office agent”. History shows this name on every change the key makes.

3. Under Access, choose Read and write, or Read only. Press Create key.

4. Copy the key. This is the only time it’s shown.

{
  "mcpServers": {
    "zyflow": {
      "url": "https://app.zyflowcrm.com/mcp",
      "headers": { "Authorization": "Bearer zf_live_…" }
    }
  }
}

Field names vary by app, so check your app’s MCP docs. If your app can read the key from an environment variable, keep it there instead of in the file.

Create an API key

For scripts that don’t speak MCP: Read the REST API docs

# Use the local stdio bridge if your app only runs local servers

The Zyflow bridge is a local stdio bridge for AI apps that can only start local MCP servers: one JavaScript file that your app runs with Node 18 or newer. It reads your API key from ZYFLOW_API_KEY and relays each message to your Zyflow link over HTTPS. Set ZYFLOW_URL as well. It defaults to a local address, so without it the bridge can’t reach Zyflow.

Steps

1. Create an API key on the Connect page.

2. Download the bridge, and save the file somewhere it will stay, such as your home folder.

3. Add the config below to your app’s MCP settings, with the full path to the file.

4. Restart your app.

{
  "mcpServers": {
    "zyflow": {
      "command": "node",
      "args": ["/path/to/zyflow-mcp.mjs"],
      "env": {
        "ZYFLOW_URL": "https://app.zyflowcrm.com/mcp",
        "ZYFLOW_API_KEY": "zf_live_…"
      }
    }
  }
}

What the bridge does

Before you run it

The bridge is one file of about 160 lines, with no dependencies and an MIT license, so you can read all of it before your app runs it. Because you download it once from your Zyflow app, nothing is fetched from a package registry when your app starts it. It reads your key from the environment, as the MCP authorization spec says stdio servers should (“retrieve credentials from the environment”, MCP specification, 2025-11-25), and sends the key only to the address in ZYFLOW_URL. Changes made through it carry the key’s name in History.

The bridge uses API keys only; it doesn’t do OAuth sign-in. Zyflow tests it with an app on protocol version 2025-06-18. Stdio apps on 2026-07-28 aren’t tested yet.

If your app can’t start it

# Which MCP protocol versions does Zyflow support?

Zyflow’s MCP server speaks the 2026-07-28 specification natively and accepts clients on 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. It uses Streamable HTTP at one URL, answers each POST with plain JSON, and takes one JSON-RPC message per request.

• Read the MCP reference
• Read the MCP server overview

# Troubleshooting 401, 403 and 429 errors

Common causes are a missing or revoked credential, a read-only key asked to write, and ZYFLOW_URL left unset. Find the message your app shows in the table for its cause and fix. Through the bridge, an error starts with “Zyflow answered” and the status code, followed by a hint.

First, check the connection. Ask your app:

• What’s on my plate today?

If it answers with today’s list from Zyflow, or says nothing is due, you’re connected.

Still stuck? Contact us. Spot an error? Tell us. Size limits and key counts are on the Zyflow limits page.

# Questions about connecting other MCP apps

An app we haven’t tested gets the same rules as the guided ones. It reaches one workspace, it can move things to the 30-day trash but can’t empty it, and every change it makes is labeled.

Read the security page