Connecting a Client

The CheckFlow MCP server is a remote server that uses the Streamable HTTP transport. A client can connect to it in one of two ways:

Sign in with your CheckFlow account (OAuth). The client opens CheckFlow in your browser, you sign in and choose Allow, and the assistant then works as you. There is no key to copy or store. This is the only way to connect claude.ai, Claude Desktop's Connectors screen, the Claude mobile apps and ChatGPT.
An API key, sent in the X-API-KEY header. This is for clients that cannot sign in, for an assistant that should act as somebody other than you or as the workspace, and for scripts.

This page shows how to set up the common clients both ways.

Before You Start

Note your server address. Use the one for the region your workspace is in:

Region	Address
United States	`https://api.checkflow.io/mcp`
Europe	`https://api-eu.checkflow.io/mcp`

Check that an Administrator has left Allow AI assistants to connect switched on, on the AI tab. It is on unless someone has turned it off.
If you are a Member, check that you have the AI.Assistant permission. New Members are given it; an Administrator can grant or remove it on the Users tab. Administrators do not need it. See Choose Who Can Connect an AI Assistant.
To connect with an API key, ask an Administrator to create one on the API & Integrations tab of Team Management. For a personal assistant, the key should act as you. See Creating an API Key. You do not need a key to sign in.

The examples below use the United States address. Use the Europe address instead if your workspace is in Europe.

Signing In

When a client connects by signing in:

Your browser opens a CheckFlow page that names the assistant asking to connect.
Sign in the way you normally do: with your email and password, with Google or Microsoft, or with your company's single sign-on. For single sign-on, enter your workspace's address (for example acme for acme.checkflow.io) and CheckFlow sends you to your company's sign-in page.
CheckFlow shows what the assistant will be able to do, which workspace it is for and the address it will send you back to. Check them, then click Allow.
Your browser returns to the assistant, which is now connected.

The assistant works as you, in the workspace you were signed in to. It sees what you can see, its changes are recorded in your name, and it is refused wherever you would be. If you belong to more than one workspace, switch to the right one in CheckFlow before you connect. To connect another workspace too, add the server to your assistant a second time and connect it while that workspace is selected.

Administrators, and Members with the AI.Assistant permission, can connect an assistant this way. Guests cannot.

The connection lasts until you or an Administrator disconnects it, or until it goes unused for 30 days. It also stops working if you leave the workspace or are made a Guest. See Disconnecting an Assistant.

Claude (Web, Desktop and Mobile)

In Claude, open Settings and then Connectors, and choose Add custom connector.
Name it CheckFlow, enter your server address, and add it.
Click Connect and sign in.

A connector you add on the web is also available in the Claude Desktop and mobile apps. On a Team or Enterprise plan, an Owner may need to add the connector for your organisation before members can connect it.

ChatGPT

ChatGPT connects to CheckFlow as a custom MCP server, which you add from Plugins. You do not need to turn on developer mode.

Who can add it depends on your ChatGPT plan:

Business: only admins and owners can add a custom MCP server and publish it for the workspace.
Enterprise and Edu: admins and owners can add one. Admins can also give selected members permission to add one, through role-based access control (RBAC).
Pro: you can connect a custom MCP server with read and fetch permissions only. Write actions, such as completing a task, need Business, Enterprise or Edu.

Custom MCP servers work in ChatGPT on the web only, not in the mobile apps.

In ChatGPT on the web, open Plugins, select the plus button, then Add custom MCP server.
Name it CheckFlow.
Under Connection, enter your server address, including /mcp.
Choose OAuth as the authentication. ChatGPT finds CheckFlow's sign-in page on its own, so there is nothing else to configure.
Review the risk warning, select I understand and want to continue, then select Create as a plugin.
Review the tools ChatGPT has found. When ChatGPT asks you to, sign in.
Install the plugin, start a new conversation, type @ and choose CheckFlow.

ChatGPT may ask you to confirm an action before it runs.

After an admin first approves the server for the workspace, ChatGPT keeps a fixed copy of CheckFlow's tool list. When CheckFlow adds or changes tools, an admin refreshes the tool list in the workspace's app settings to pick them up.

For the full steps and the admin settings, see OpenAI's Connecting custom MCP servers in ChatGPT.

Claude Code

Add the server from a terminal:

claude mcp add --transport http checkflow https://api.checkflow.io/mcp

Then, in Claude Code, run /mcp, choose checkflow and Authenticate. Your browser opens so that you can sign in.

To connect with an API key instead, add the header:

claude mcp add --transport http checkflow https://api.checkflow.io/mcp --header "X-API-KEY: your-api-key-here"

Add --scope user to either command to make the server available in every project, rather than only the current one. Run claude mcp list to check that it connected, then ask Claude something like "List my CheckFlow templates."

Cursor

Add the server to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json in one project. With only the address, Cursor offers to sign you in when you enable the server:

{
  "mcpServers": {
    "checkflow": {
      "url": "https://api.checkflow.io/mcp"
    }
  }
}

To use an API key instead, add a headers entry:

{
  "mcpServers": {
    "checkflow": {
      "url": "https://api.checkflow.io/mcp",
      "headers": {
        "X-API-KEY": "your-api-key-here"
      }
    }
  }
}

Open Cursor's MCP settings to check that the server shows as connected and its tools are listed.

Visual Studio Code

Add the server to .vscode/mcp.json in your workspace. With only the address, VS Code asks you to sign in when the server starts:

{
  "servers": {
    "checkflow": {
      "type": "http",
      "url": "https://api.checkflow.io/mcp"
    }
  }
}

To use an API key instead, add an inputs block, which makes VS Code prompt for the key once and store it securely rather than keeping it in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "checkflow-api-key",
      "description": "CheckFlow API key",
      "password": true
    }
  ],
  "servers": {
    "checkflow": {
      "type": "http",
      "url": "https://api.checkflow.io/mcp",
      "headers": {
        "X-API-KEY": "${input:checkflow-api-key}"
      }
    }
  }
}

Start the server from the file or the MCP: List Servers command, then use the tools from Copilot Chat in agent mode.

Microsoft 365 Copilot

Microsoft 365 Copilot agents are not supported yet. Their MCP plugins sign in with OAuth, and Microsoft's automatic setup needs the server to issue a client secret during registration. CheckFlow does not issue client secrets. See Microsoft's dynamic client registration page.

This does not affect GitHub Copilot in VS Code, which signs in as described above.

Claude Desktop with an API Key

Claude Desktop's Connectors screen signs in, as described above. To connect Claude Desktop with an API key instead, use the mcp-remote bridge, which needs Node.js 18 or later.

In Claude Desktop, open Settings, then Developer, and click Edit Config.
Add a checkflow entry under mcpServers:

{
  "mcpServers": {
    "checkflow": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.checkflow.io/mcp",
        "--header",
        "X-API-KEY:${CHECKFLOW_API_KEY}"
      ],
      "env": {
        "CHECKFLOW_API_KEY": "your-api-key-here"
      }
    }
  }
}

Save the file and restart Claude Desktop. The CheckFlow tools appear in the tools menu of a new conversation.

Write the header as X-API-KEY:${CHECKFLOW_API_KEY} with no space after the colon. Some platforms split arguments on spaces, which would break the header.

warning

Configuration files are often synced, backed up or shared. Where a client supports environment variables or a secret prompt, use them rather than pasting an API key into the file. Signing in avoids storing a key at all.

MCP Inspector

MCP Inspector is a browser-based tool for exploring a server's tools and calling them by hand. It is the quickest way to check a key and see exactly what a tool returns.

Run npx @modelcontextprotocol/inspector.
Choose the Streamable HTTP transport and enter https://api.checkflow.io/mcp.
Add a custom header named X-API-KEY with your key.
Click Connect, then List Tools.

Other Clients

Any client works if it can connect to a remote MCP server over Streamable HTTP, and either:

signs in using the MCP authorization specification (OAuth 2.1), or
sends an API key with every request, in the X-API-KEY header or as Authorization: Bearer your-api-key-here.

The Authorization: Bearer form is for clients that can send a bearer token but not a custom header, such as the MCP connector in the Claude API and Microsoft 365 agent connectors. If a request carries both headers, X-API-KEY is used.

CheckFlow only sends a sign-in back to the addresses of a set list of assistants: Claude, Claude Code, ChatGPT, VS Code, Cursor, Microsoft 365 Copilot, and other desktop applications that receive the sign-in on your own computer. Microsoft 365 Copilot is on the list but cannot connect yet. See Microsoft 365 Copilot. If a client's sign-in page says CheckFlow does not send sign-ins to its address, connect it with an API key, or ask support to add the client.

A client that cannot do either can connect through a bridge such as mcp-remote, as in the Claude Desktop example. You can also talk to the server directly with HTTP — see How the MCP Server Works.

Disconnecting an Assistant

An assistant you connected by signing in: open My Profile & Settings from the menu under your name, go to the AI Assistants tab, and click Disconnect next to it. Removing the connector in the assistant itself also ends the connection.
Any member's assistant, as an Administrator: on the API & Integrations tab of Team Management, find it under Connected AI assistants and revoke it. Other Administrators are notified.
An assistant that uses an API key: an Administrator revokes the key on the API & Integrations tab.

The assistant is refused from its next request. To stop every assistant at once, an Administrator turns off Allow AI assistants to connect on the AI tab.

Checking the Connection

Ask your assistant: "Which CheckFlow workspace are you connected to?" It answers from get_workspace_info, which returns the workspace's name, region, members, groups, tags and templates. To see which member an API key acts as, call GET /v3/auth/test with it.

If the connection fails:

What you see	Cause	Fix
The sign-in page says This application cannot connect.	The client, or the address it asked CheckFlow to send you back to, is not one CheckFlow recognises.	Remove the server from the client and add it again. If it keeps happening, connect with an API key.
The sign-in page says an administrator has turned off connections from AI assistants.	Allow AI assistants to connect is off.	Ask an Administrator to turn it back on, on the AI tab.
The sign-in page says Guests cannot connect AI assistants.	You are a Guest in this workspace.	Ask an Administrator to make you a Member.
The sign-in page says you do not have the AI.Assistant permission.	An Administrator has not given you AI.Assistant.	Ask an Administrator to grant it on the Users tab.
The assistant is connected to the wrong workspace.	You were signed in to another workspace when you connected.	Disconnect it, switch workspace in CheckFlow, and connect again.
The assistant asks you to connect or sign in again.	The connection was disconnected or revoked, went unused for 30 days, or you have left the workspace or been made a Guest.	Connect again.
The client reports an authorisation or `401` error with an API key.	The key is missing, mistyped, revoked or expired, or its member can no longer be acted as.	Check the header name is exactly `X-API-KEY` and copy the key again from the API & Integrations tab.
Calls say `WRONG_REGION`.	The workspace is in the other region.	Use the address the message gives. If you signed in, remove the connection and connect again with that address.
Calls say `API_KEY_ACTS_AS_WORKSPACE`.	The key acts as the workspace and the tool is about a person.	Use a key that acts as a member, or sign in.
Calls say `RATE_LIMIT_EXCEEDED`.	The workspace has used its hourly budget.	Wait for the number of seconds the message gives.
Every call fails with `AI_ASSISTANT_NOT_PERMITTED`.	The member the assistant acts as does not have AI.Assistant.	Ask an Administrator to grant it on the Users tab. The assistant works again within a minute, without reconnecting.
The connection fails, or every call fails, with `MCP_DISABLED`.	An Administrator has turned off Allow AI assistants to connect.	Ask an Administrator to turn it back on, on the AI tab.

CheckFlow MCP Server — what the server can do and how to keep it safe.
How the MCP Server Works — the protocol and sign-in details behind a connection.
Authentication — creating keys and choosing who they act as.

Before You Start​

Signing In​

Claude (Web, Desktop and Mobile)​

ChatGPT​

Claude Code​

Cursor​

Visual Studio Code​

Microsoft 365 Copilot​

Claude Desktop with an API Key​

MCP Inspector​

Other Clients​

Disconnecting an Assistant​

Checking the Connection​

Related Pages​