MCP API key

​

Overview

OAuth is available. See MCP OAuth (Recommended).

​

Prerequisites

1. Go to your Formo workspace settings
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

Authorization: Bearer <your_workspace_api_key>

​

Setup

• Claude Desktop
• Cursor
• Claude Code
• Windsurf
• VS Code
• Codex
• mcp-remote / CLI
• Other clients

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:

{
  "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.

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

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: sse
   • URL: https://api.formo.so/v0/mcp/
   • Headers: Authorization: Bearer YOUR_API_KEY

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

{
  "mcpServers": {
    "formo": {
      "url": "https://api.formo.so/v0/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Run the following command:

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.

1. Open Windsurf Settings and navigate to the MCP section, or edit ~/.codeium/windsurf/mcp_config.json directly.
2. Add the following configuration:

{
  "mcpServers": {
    "formo": {
      "serverUrl": "https://api.formo.so/v0/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

3. Restart Windsurf for the changes to take effect.

Add the following to .vscode/mcp.json in your project:

{
  "servers": {
    "formo": {
      "type": "http",
      "url": "https://api.formo.so/v0/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Add the following to ~/.codex/config.toml:

[mcp_servers.formo]
url = "https://api.formo.so/v0/mcp/"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }

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:

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:

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

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.

​

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 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.