Skip to main content

Connecting a Client

The CheckFlow MCP server is a remote server that uses the Streamable HTTP transport and authenticates with the X-API-KEY header. Any MCP client that can connect to a remote server and send a custom header can use it. This page shows how to set up the common ones.

Before You Start​

  1. Check that your workspace is on the Enterprise plan — the MCP server is not available on other plans.
  2. Ask an Administrator to create an API key on the API & Integrations tab of the Team page. For a personal assistant, the key should act as you. See Creating an API Key.
  3. Note your server address:
RegionAddress
United Stateshttps://api.checkflow.io/mcp
Europehttps://api-eu.checkflow.io/mcp

In the examples below, replace your-api-key-here with your key and use the EU address if your workspace is in Europe.

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 the key into the file.

Claude Code​

Add the server from a terminal:

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

Add --scope user to make it 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."

Claude Desktop​

Claude Desktop connects to remote servers with a custom header through the mcp-remote bridge, which needs Node.js 18 or later.

  1. In Claude Desktop, open Settings, then Developer, and click Edit Config.
  2. 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"
      }
    }
  }
}
  1. 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.

Cursor​

Add the server to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json in one project:

{
  "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. The inputs block 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.

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.

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

Other Clients​

Any client works if it can:

  • connect to a remote MCP server over Streamable HTTP, and
  • send the X-API-KEY header with every request.

The server does not support OAuth, and there is no Authorization header to set. A client that can only authenticate a remote server with OAuth 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.

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 a key acts as, call GET /v3/auth/test with it.

If the connection fails:

What you seeCauseFix
The client reports an authorisation or 401 error.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 Team page.
The connection fails, or every call fails, with ENTERPRISE_PLAN_REQUIRED.The workspace is not on the Enterprise plan.Upgrade the workspace, or use the REST API.
Calls say WRONG_REGION.The workspace is in the other region.Use the address the message gives.
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.
Calls say RATE_LIMIT_EXCEEDED.The workspace has used its hourly budget.Wait for the number of seconds the message gives.
Last updated on