> ## 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 OAuth

> Connect OAuth-capable MCP clients to Formo.

## Overview

Formo supports OAuth for remote MCP clients that can discover and complete an OAuth authorization flow.

<Frame>
  <img src="https://mintcdn.com/formo/Ukc8jUCHmP_WHpK2/images/mcp-oauth-claude.png?fit=max&auto=format&n=Ukc8jUCHmP_WHpK2&q=85&s=2bed32618af93b6e7f50289825e71a5a" alt="Formo OAuth consent page for MCP clients" width="1436" height="1538" data-path="images/mcp-oauth-claude.png" />
</Frame>

## Setup

<Tabs>
  <Tab title="ChatGPT">
    1. Open ChatGPT settings
    2. Go to **Apps**
    3. Click **Advanced settings**
    4. Enable **Developer mode**

    <Frame>
      <img src="https://mintcdn.com/formo/rWzBrWvAs6uGGfLp/images/chatgpt-developer-mode.png?fit=max&auto=format&n=rWzBrWvAs6uGGfLp&q=85&s=04594d0a0df30376471a32bd0b38e9a2" alt="Enable Developer mode in ChatGPT app settings" width="942" height="834" data-path="images/chatgpt-developer-mode.png" />
    </Frame>

    5. Go back to Apps
    6. Click **Create app**
    7. Enter the app details:

       **Name**

       ```text theme={null}
       Formo
       ```

       **MCP server URL**

       ```text theme={null}
       https://api.formo.so/v0/mcp/
       ```

       * **Description:** optional
       * **Authentication:** OAuth

    <Frame>
      <img src="https://mintcdn.com/formo/rWzBrWvAs6uGGfLp/images/chatgpt-apps-add.png?fit=max&auto=format&n=rWzBrWvAs6uGGfLp&q=85&s=7f3d3de3f6cc0da76c14a44aac63ddb2" alt="Create a Formo MCP app in ChatGPT" width="764" height="1128" data-path="images/chatgpt-apps-add.png" />
    </Frame>

    8. Click **Create**
    9. Sign in to Formo, select a project, and approve access
    10. Start asking ChatGPT questions about your Formo analytics

    <Note>
      ChatGPT Developer mode is a beta feature. ChatGPT apps created in Developer mode also cannot use memory.
    </Note>

    Formo can be configured as a data-only MCP app; no extra app UI is required to query analytics.
  </Tab>

  <Tab title="Claude">
    1. Open **Customize** → **Connectors**
    2. Add a custom connector
    3. Enter the connector details:

       **Name**

       ```text theme={null}
       Formo
       ```

       **Server URL**

       ```text theme={null}
       https://api.formo.so/v0/mcp/
       ```

    <Frame>
      <img src="https://mintcdn.com/formo/rWzBrWvAs6uGGfLp/images/claude-web-connectors-add.png?fit=max&auto=format&n=rWzBrWvAs6uGGfLp&q=85&s=addfa60b832203c4794654918dcca025" alt="Add Formo as a custom connector in Claude.ai" width="638" height="451" data-path="images/claude-web-connectors-add.png" />
    </Frame>

    4. Click **Add**
    5. On the Formo confirmation page, select the project Claude.ai should access
    6. Click **Allow access**
    7. Return to Claude.ai and confirm Formo appears with the available tools

    <Frame>
      <img src="https://mintcdn.com/formo/rWzBrWvAs6uGGfLp/images/claude-web-connectors-config.png?fit=max&auto=format&n=rWzBrWvAs6uGGfLp&q=85&s=01a6c756fe8cb74b3b853caa7b03059d" alt="Formo connector configuration in Claude.ai" width="980" height="735" data-path="images/claude-web-connectors-config.png" />
    </Frame>

    <Note>
      Claude.ai stores and refreshes the OAuth connection for the signed-in user. In managed workspaces, an owner or admin may need to add the remote MCP server before members can connect it individually.
    </Note>
  </Tab>

  <Tab title="Others">
    1. Open your MCP client's connector or app settings
    2. Add a remote MCP server
    3. Enter the Formo MCP server URL:

    ```text theme={null}
    https://api.formo.so/v0/mcp/
    ```

    4. Choose OAuth if the client asks for an authentication method
    5. Save or connect the server
    6. Sign in to Formo, select a project, and approve access

    If the client asks for scopes, request the permissions you need (for example `query:read`) plus `offline_access` if it needs to refresh.
  </Tab>
</Tabs>

## Scopes

Formo MCP OAuth supports the following scopes:

| Scope | Description |
| :- | :- |
| `profiles:read` / `profiles:write` | Read or manage wallet profiles |
| `query:read` | Analytics and SQL tools for the selected project |
| `alerts:read` / `alerts:write` | Read or manage alerts |
| `boards:read` / `boards:write` | Read or manage charts and boards |
| `contracts:read` / `contracts:write` | Read or manage tracked contracts |
| `segments:read` / `segments:write` | Read or manage segments |
| `offline_access` | Allows the MCP client to refresh access without asking the user to sign in again |

> OAuth access is bound to the project selected on the Formo consent page. The MCP server validates that the user still has access to that project before serving requests.

## Troubleshooting

* **`403 MCP access requires a Scale or Enterprise plan`:** The signed-in workspace is on a Growth plan. MCP authorization is gated server-side, so the OAuth flow will not complete. [Upgrade the workspace](https://app.formo.so) to a Scale or Enterprise plan, then reconnect.
* **Client does not start OAuth:** Confirm the MCP server URL is exactly `https://api.formo.so/v0/mcp/` and includes the trailing slash.
* **Invalid scope:** Request supported scopes only (see the table above), plus `offline_access` when refresh is needed.
* **Consent page asks you to sign in again:** Sign in to Formo and you will be returned to the same OAuth authorization flow.
* **No projects are available:** The signed-in Formo account must be an owner or admin of a team with at least one project.
* **Project access denied after connecting:** Reconnect and choose a project that your Formo user can still access.
* **API key stopped working:** OAuth does not replace API keys. Check that the key has the permission the failing tool needs (analytics and SQL need `query:read`), has not been revoked, and is sent as `Authorization: Bearer <workspace_api_key>`.

## OAuth discovery

Most OAuth-capable MCP clients discover Formo's OAuth configuration automatically from the MCP server URL:

```text theme={null}
https://api.formo.so/v0/mcp/
```

Unauthenticated requests return a `401` with a `WWW-Authenticate` challenge that points clients to Formo's protected resource metadata. Access tokens expire after 1 hour; clients that request `offline_access` can refresh access without asking the user to sign in again.

<Accordion title="OAuth metadata URLs">
  | Metadata | URL |
  | :- | :- |
  | Protected resource metadata | `https://api.formo.so/.well-known/oauth-protected-resource/v0/mcp` |
  | Authorization server metadata | `https://api.formo.so/v0/mcp/oauth/.well-known/oauth-authorization-server` |
  | OpenID configuration alias | `https://api.formo.so/v0/mcp/oauth/.well-known/openid-configuration` |

  The `openid-configuration` path is an alias that returns the same OAuth authorization-server metadata for clients that look there. Formo MCP is OAuth 2.0 only and does not implement full OpenID Connect.
</Accordion>


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