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

# Model Context Protocol (MCP)

> Connect AI coding assistants to your Colossal project over MCP: query commerce data and build automations, with browser-based sign-in.

The Colossal MCP server gives AI coding assistants direct access to your project's GraphQL API. Your assistant can query products, customers, orders, and analytics without leaving your editor.

<Note>
  MCP is a protocol that connects AI assistants to external data sources. The Colossal MCP server acts as a bridge between your AI tools and your project.
</Note>

## Prerequisites

* An AI assistant that supports MCP and its authorization spec (Claude Code, Cursor, VS Code)

## Connect

The server uses OAuth, so there is no token to copy. Your client opens a browser the
first time it connects, you sign in to Colossal and approve the client, and it stores
the token itself.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http colossal https://mcp.colossal.sh/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "colossal": {
          "url": "https://mcp.colossal.sh/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to VS Code settings:

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "colossal": {
            "type": "http",
            "url": "https://mcp.colossal.sh/mcp"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Run `/mcp` in Claude Code to check the connection or sign in again.

Any MCP client that implements the authorization spec works the same way: point it at
`https://mcp.colossal.sh/mcp` and let it discover the rest. The server advertises its
authorization server at `/.well-known/oauth-protected-resource/mcp`.

<Note>
  Tokens are issued for this server specifically and cannot be replayed against the
  Colossal API. If you want a credential for direct REST or GraphQL calls, create an API
  token in the dashboard instead; the MCP server does not accept those.
</Note>

## What you can do

Once connected, ask your AI assistant to work with your project data:

* Query products, customers, and orders
* Analyze sales and customer behavior
* Generate reports from commerce data
* Build apps using real project data

## Available data

The MCP server provides read access to:

| Entity    | Examples                                   |
| --------- | ------------------------------------------ |
| Products  | Name, pricing, variants, inventory, status |
| Customers | Contact info, order history                |
| Orders    | Line items, payment status, totals         |
| Payments  | Transaction history, payment methods       |
| Projects  | Organization structure, configuration      |

## Connection details

For other MCP-compatible clients:

| Setting       | Value                                                                  |
| ------------- | ---------------------------------------------------------------------- |
| Endpoint      | `https://mcp.colossal.sh/mcp`                                          |
| Transport     | Streamable HTTP                                                        |
| Authorization | OAuth 2.1, discovered from `/.well-known/oauth-protected-resource/mcp` |

## Troubleshooting

* **Can't connect** -- run `/mcp` in Claude Code to re-run the sign-in
* **401 after a while** -- the token expired; your client refreshes it on the next call, or sign in again
* **Field not found** -- use `search_schema` to check the fields a type actually has
* **Rate limiting** -- wait between requests and retry