Skip to main content
The Colossal MCP server connects an AI client to your project. A client can read your commerce data without leaving your editor. It can also build automations and run actions on a connection.
MCP is a protocol that connects AI clients to external systems. The Colossal MCP server is the bridge between your client and your project.

​
Prerequisites

  • An AI client that supports MCP and its authorization spec (Claude Code, Codex, 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.
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.
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.

​
What you can do

The server exposes 19 tools in three groups. Your role decides which ones work.

​
Read your project

  • query_graphql runs any read query against the admin API. Mutations are rejected.
  • search_schema finds the types and fields the API exposes.
  • list_projects, list_connections and list_automations list what exists.
  • get_automation returns one automation in full.
  • list_automation_runs and get_automation_run show what an automation did.
  • search_docs and get_doc search this documentation.
Reads follow your role. You see the records the dashboard already shows you, and nothing more.

​
Build and change automations

  • create_automation adds an automation from a definition.
  • update_automation edits one that already exists.
  • check_automation_definition validates a definition before you save it.
  • toggle_automation enables or disables one.
  • delete_automation removes one.
These need the builder role or above.

​
Run automations and actions

  • run_automation triggers an automation and returns a run id.
  • run_connection_action calls an action on a connection, such as refunding a Shopify order.
  • search_connection_actions and describe_connection_action find an action and show the arguments it takes.
run_automation needs the builder role or above. run_connection_action needs the owner role.
An automation you cannot run through MCP is one you cannot run in the dashboard either. MCP applies the same permissions, not a second set.

​
What your role allows

Your access appears in the dashboard under MCP, alongside the calls made through the server.

​
Connection details

For other MCP-compatible clients:

​
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