> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formo.so/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP API key

> Connect MCP clients to Formo with a Workspace API Key.

## Overview

Use Workspace API Key authentication for MCP clients that let you configure custom HTTP headers, local editor integrations, or stdio bridges such as `mcp-remote`.

> OAuth is available. See [MCP OAuth](/mcp/oauth) (Recommended).

## Prerequisites

Requires an owner or admin role on the workspace.

1. Go to your [Formo workspace settings](https://app.formo.so)
2. Navigate to **Settings** → **API**
3. Click **Create API Key**
4. Enable the permissions you need. **Query API** read covers analytics and SQL; add **Alerts**, **Charts**, **Contracts**, or **Segments** to let it read or manage those.
5. Copy the generated key

Use the API key as a Bearer token:

```bash theme={null}
Authorization: Bearer <your_workspace_api_key>
```

Workspace API keys are project-specific. The MCP server can only read analytics data for the project attached to the key.

## Setup

Select your client below to configure Formo with API key authentication.

<Tabs>
  <Tab title="Claude Desktop">
    1. On Claude Desktop, go to Settings > Developer > Edit Config
    2. This opens the Claude Desktop config file:
       * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
       * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
    3. Add the following configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "formo": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://api.formo.so/v0/mcp/",
            "--header",
            "Authorization: Bearer YOUR_API_KEY"
          ]
        }
      }
    }
    ```

    4. Restart Claude Desktop for the changes to take effect.
    5. Upon successful restart, click the + icon on a new chat screen to enable Formo.

    <Frame>
      <img src="https://mintcdn.com/formo/rTyyDF1NvgOLjZau/images/claude-connectors-enable.png?fit=max&auto=format&n=rTyyDF1NvgOLjZau&q=85&s=26d2b84f9c31e594bc0e2659c0b7b305" alt="Enable Formo" width="703" height="527" data-path="images/claude-connectors-enable.png" />
    </Frame>

    6. You can go to the Connectors settings to configure the Formo connector permissions to Always Allow.

    <Frame>
      <img src="https://mintcdn.com/formo/rTyyDF1NvgOLjZau/images/claude-connectors-config.png?fit=max&auto=format&n=rTyyDF1NvgOLjZau&q=85&s=aba4bc4ed89f1d5e80da41f0d422f36b" alt="Formo Connector Settings" width="769" height="809" data-path="images/claude-connectors-config.png" />
    </Frame>
  </Tab>

  <Tab title="Cursor">
    1. Press `Cmd+,` (macOS) or `Ctrl+,` (Windows/Linux) to open Settings.
    2. Find the "MCP" section in the settings sidebar.
    3. Click "Add new MCP server" and configure:
       * **Name:** `formo`
       * **Type:** `http`
       * **URL:** `https://api.formo.so/v0/mcp/`
       * **Headers:** `Authorization: Bearer YOUR_API_KEY`

    <Note>
      Formo MCP uses the Streamable HTTP transport. Selecting the legacy `sse`
      type makes the connection fail, because the server has no SSE endpoint.
    </Note>

    Alternatively, add this to `.cursor/mcp.json` in your project:

    ```json theme={null}
    {
      "mcpServers": {
        "formo": {
          "url": "https://api.formo.so/v0/mcp/",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Run the following command:

    ```bash theme={null}
    claude mcp add --scope user --transport http formo https://api.formo.so/v0/mcp/ --header "Authorization: Bearer YOUR_API_KEY"
    ```

    This registers the Formo MCP server globally for your user. To scope it to a specific project, use `--scope project` instead.
  </Tab>

  <Tab title="Windsurf">
    1. Open Windsurf Settings and navigate to the MCP section, or edit `~/.codeium/windsurf/mcp_config.json` directly.
    2. Add the following configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "formo": {
          "serverUrl": "https://api.formo.so/v0/mcp/",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    3. Restart Windsurf for the changes to take effect.
  </Tab>

  <Tab title="VS Code">
    Add the following to `.vscode/mcp.json` in your project:

    ```json theme={null}
    {
      "servers": {
        "formo": {
          "type": "http",
          "url": "https://api.formo.so/v0/mcp/",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Add the following to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.formo]
    url = "https://api.formo.so/v0/mcp/"
    http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }
    ```
  </Tab>

  <Tab title="mcp-remote / CLI">
    For clients that only support stdio-based MCP servers, use the `mcp-remote` bridge to connect to Formo's HTTP-based server.

    1. Ensure Node.js is installed: `node --version`
    2. Run the following command:

    ```bash theme={null}
    npx mcp-remote https://api.formo.so/v0/mcp/ --header "Authorization: Bearer YOUR_API_KEY"
    ```

    You can use this with any MCP client that supports stdio transports:

    ```json theme={null}
    {
      "mcpServers": {
        "formo": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://api.formo.so/v0/mcp/",
            "--header",
            "Authorization: Bearer YOUR_API_KEY"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Most MCP clients support HTTP transport with custom headers. Configure your client with:

    * **Server URL:** `https://api.formo.so/v0/mcp/`
    * **Header:** `Authorization: Bearer YOUR_API_KEY`

    If your client only supports stdio transport, use the `mcp-remote` bridge.
  </Tab>
</Tabs>

<Card title="Example questions" icon="message-question" href="/mcp/overview#example-questions">
  Try questions you can ask once Formo is connected.
</Card>

## Troubleshooting

* **`403 MCP access requires a Scale or Enterprise plan`:** MCP is available only on Scale and Enterprise plans. A valid API key is not sufficient on a Growth workspace. [Upgrade your workspace](https://app.formo.so) to connect MCP.
* **Tools not appearing:** Check that the URL ends with a trailing slash: `https://api.formo.so/v0/mcp/`. Restart your AI assistant after configuration changes.
* **`insufficient scope` on a tool call:** the key is missing that tool's permission. Analytics and SQL tools need **Query API** read; managing alerts, charts, contracts, or segments needs the matching permission. There is no separate MCP scope to enable.
* **Authentication errors:** Ensure the API key is sent as `Authorization: Bearer YOUR_API_KEY`. Check that the API key has not been revoked.
* **Wrong project data:** Workspace API keys are project-specific. Create or use a key attached to the project you want the MCP client to query.
* **Claude Desktop not connecting:** Ensure Node.js is installed and accessible from the command line. Check Claude Desktop logs: `~/Library/Logs/Claude/` on macOS.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.