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

# Connect an AI client to the Square Cloud MCP server

> Connect Claude and ChatGPT with OAuth, or Claude Code, VS Code and Cursor with an API key, to the Square Cloud MCP server, and learn how long a connection lasts.

Every client uses the same address, `https://mcp.squarecloud.app/mcp`. How it signs in depends on the client:

| Client | How it connects |
| - | - |
| [Claude](#claude) (claude.ai and the Claude apps) | OAuth: paste the address and authorize on Square Cloud |
| [ChatGPT](#chatgpt) | OAuth: paste the address and authorize on Square Cloud |
| [Claude Code](#claude-code) | [API key](#create-an-api-key) in the `Authorization` header |
| [VS Code](#vs-code) | [API key](#create-an-api-key) in the `Authorization` header |
| [Cursor](#cursor) | [API key](#create-an-api-key) in the `Authorization` header |
| [Other clients](#other-clients) | [API key](#create-an-api-key) in the `Authorization` header |

Your account needs an active [plan](https://docs.squarecloud.app/en/platform/plans.md) in both cases.

## Claude

**1. Add a custom connector**

In Claude, open **Customize > Connectors**, click **+ Add** and then **Add custom connector**. On Team and Enterprise plans, an Owner adds it first under **Organization settings > Connectors** (**Add > Custom > Web**), and each member then connects it from **Customize > Connectors**.

**2. Enter the address**

Name it `Square Cloud`, enter `https://mcp.squarecloud.app/mcp` and click **Continue**.

**3. Keep Claude's own identity**

Keep a sign-in option (**Sign in now** or **Sign in when needed**) and, as the OAuth client, **Use Claude's published identity (Recommended)**. Leave **Request headers** empty and click **Add**.

**4. Authorize on Square Cloud**

Claude opens a Square Cloud page. Sign in if needed, review the permissions Claude asks for and click to authorize. You can uncheck permissions to give Claude less access; `mcp` always stays, since it is what connects.

**5. Use it in a chat**

Back in Claude, click **+** in the chat box, open **Connectors** and turn **Square Cloud** on.

> [!NOTE]
>
> Square Cloud only accepts Claude's published identity. **Register automatically** and **Use your own OAuth client** don't work with it.

## ChatGPT

**1. Add a custom MCP server**

Open [ChatGPT Plugins](https://chatgpt.com/plugins), select **+** and then **Add custom MCP server**. Depending on your ChatGPT plan, a workspace admin may need to allow custom MCP servers first.

**2. Enter the address**

Name it `Square Cloud`, choose the public endpoint as the connection and enter `https://mcp.squarecloud.app/mcp`. Choose OAuth for authentication.

**3. Create it**

Review the warning, select **I understand and want to continue** and then **Create as a plugin**.

**4. Authorize on Square Cloud**

When ChatGPT asks you to sign in, it opens a Square Cloud page. Sign in if needed, review the permissions and click to authorize. You can uncheck permissions; `mcp` always stays.

**5. Use it in a chat**

Start a new conversation, type `@` and pick **Square Cloud**.

> [!NOTE]
>
> ChatGPT changes the names of these menus from time to time. If they differ, follow [OpenAI's guide to connecting an MCP server](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt).

## Claude Code

Claude Code connects with an [API key](#create-an-api-key) in a header, not with OAuth. Store the key in the `SQUARECLOUD_API_KEY` environment variable and run:

```bash theme={"system"}
claude mcp add --transport http squarecloud https://mcp.squarecloud.app/mcp \
  --header "Authorization: Bearer $SQUARECLOUD_API_KEY"
```

Your shell fills in the key when you run the command, and Claude Code saves it in its own configuration. To share the server with a project without sharing the key, add it to the project's `.mcp.json` instead; Claude Code reads the variable each time it starts:

```json .mcp.json theme={"system"}
{
  "mcpServers": {
    "squarecloud": {
      "type": "http",
      "url": "https://mcp.squarecloud.app/mcp",
      "headers": {
        "Authorization": "Bearer ${SQUARECLOUD_API_KEY}"
      }
    }
  }
}
```

Check the connection with `claude mcp list`, or with `/mcp` inside Claude Code.

## VS Code

Add the server to `.vscode/mcp.json` in your project, or to your user configuration with **MCP: Open User Configuration** from the command palette:

```json .vscode/mcp.json theme={"system"}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "squarecloud-api-key",
      "description": "Square Cloud API key",
      "password": true
    }
  ],
  "servers": {
    "squarecloud": {
      "type": "http",
      "url": "https://mcp.squarecloud.app/mcp",
      "headers": {
        "Authorization": "Bearer ${input:squarecloud-api-key}"
      }
    }
  }
}
```

VS Code asks for the [API key](#create-an-api-key) when the server starts, so it never sits in the file. Start, stop or restart the server with **MCP: List Servers**.

> [!TIP]
>
> This is separate from the [Square Cloud extension for VS Code](https://docs.squarecloud.app/en/vscode-extension/installation.md), which manages your applications from the side bar. You can use both.

## Cursor

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

```json .cursor/mcp.json theme={"system"}
{
  "mcpServers": {
    "squarecloud": {
      "url": "https://mcp.squarecloud.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SQUARECLOUD_API_KEY}"
      }
    }
  }
}
```

Set `SQUARECLOUD_API_KEY` in your environment before opening Cursor. Turn the server on in Cursor's **Customize** menu; if it doesn't connect, the **MCP Logs** channel of the Output panel shows why.

## Other clients

Any client that supports remote MCP servers over Streamable HTTP with a custom header works the same way: use the address `https://mcp.squarecloud.app/mcp` and send the API key in the `Authorization` header. The `Bearer ` prefix is optional.

```http theme={"system"}
Authorization: Bearer <your API key>
```

## Create an API key

Create the key in your [account security settings](https://squarecloud.app/en/account/security):

* **Give it the `mcp` scope**, plus the scopes of the tools you want the client to use. A full-access key also works. See [Scopes](https://docs.squarecloud.app/en/mcp/permissions-and-safety.md#scopes).
* **For read-only access**, choose `mcp`, `apps:read`, `files:read`, `envs:read`, `snapshots:read` and `databases:read`.
* **To limit the client to some applications and databases**, restrict the key to them. See [Restricted keys](https://docs.squarecloud.app/en/mcp/permissions-and-safety.md#keys-restricted-to-applications-and-databases).

The secret is shown only once. Keep it in an environment variable or in your client's secret storage, never in a chat or a file you commit. Keys you create don't expire: revoke the key when you stop using it. An account holds up to 10 keys.

## How long a connection lasts

**Claude and ChatGPT (OAuth).** Authorizing creates an API key for that client, named after it (`Claude` or `ChatGPT`):

* It lasts **90 days** and has no refresh token. When it expires, the client asks you to sign in and authorize again.
* It only works on the MCP server. On the REST API it answers `403 MISSING_SCOPE`.
* **Connecting the same client again revokes its previous key.** Each account keeps one Claude connection and one ChatGPT connection, so connecting a second Claude account disconnects the first.

To keep several connections at once, give each extra one an API key of its own. In Claude, a custom connector can also send an API key: choose **No sign in** under **Authentication** and add the `Authorization` header under **Request headers**. On Team and Enterprise plans, everyone who uses that connector shares the key's access.

**API keys you create** don't expire. Whatever the way in, all MCP connections of an account share the same [limits](https://docs.squarecloud.app/en/mcp/limits-and-errors.md).

## Disconnect

Revoke the key in your [account security settings](https://squarecloud.app/en/account/security): the `Claude` or `ChatGPT` key for an OAuth connection, or the key you created. Access ends at the client's next request. Removing the connector or server in the client stops it from calling, but only revoking the key on Square Cloud invalidates it.


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