Connect an MCP client

Before you connect

Open Settings → MCP in rocketblue (API & MCP are available on all plans for non-viewer roles).
Copy the Server URL from the MCP Setup card.

The Server URL is unique per team so you can add one connector per organization, for example:

https://app.rocketblue.ai/api/mcp?484aa7033e56

The query string identifies the team. Claude registers an OAuth client automatically from that URL. Cursor and other header-based clients use the API key from Settings → API. If Claude cannot register automatically, expand Use your own OAuth client on the MCP Setup card and paste that Client ID and Client Secret. Keep the secret private. IT and security reviewers: see MCP security and the Security Overview.

Claude

Add a custom connector in Claude on the web or in Claude Desktop. The connector is per team.

In a Claude chat, click + → Connectors → Add connector → Add custom connector.
Name it rocketblue + the team name, and paste the Server URL from Settings → MCP into Remote MCP server URL.
Click Continue. Let Claude detect the settings, then click Add.
An authorization window opens. Click Continue, then Approve to allow access to this team’s rocketblue data.

The first time Claude uses a tool, approve the request. To stop those prompts, open Connectors → Manage connectors, select this connector, and choose Always allow.

Use the Server URL from Settings, including the team id in the query string. If registration fails, expand Use your own OAuth client on the MCP Setup card and choose that option in Claude instead.

ChatGPT

Yes — rocketblue MCP can be used from OpenAI products that support remote MCP servers (ChatGPT custom MCP apps / Developer mode, and the OpenAI Responses API MCP tool). ChatGPT connects over HTTPS to the same Server URL. Use OAuth. If ChatGPT detects automatic registration, keep that option. Otherwise expand Use your own OAuth client in Settings → MCP and paste the Client ID and Client Secret. Availability and write-tool permissions depend on the ChatGPT plan and workspace policy. Workspace admins typically enable Developer mode, create a custom app with your MCP URL, complete OAuth, then scan tools. Full MCP (including write/modify tools) is aimed at ChatGPT Business, Enterprise, and Edu; some personal plans may be limited to read/fetch. See OpenAI’s Developer mode documentation.

ChatGPT (workspace custom app)

Exact labels in ChatGPT change over time. The flow is:

A workspace admin enables Developer mode (Workspace settings → Apps / Connected Data, depending on plan).
Create a custom app and paste the rocketblue Server URL from Settings → MCP as the remote MCP endpoint.
Choose OAuth. Enter the Client ID and Client Secret from Settings → MCP — do not rely on dynamic registration.
Complete the rocketblue consent screen while signed in as a non-viewer member of that organization.
Scan tools, review the catalog, then create/publish the app according to your workspace policy.

rocketblue issues refresh tokens on the authorization-code grant (access tokens last 1 hour). If ChatGPT asks for an offline_access scope, our advertised scope is spotlight:mcp; refresh tokens are still returned after a successful authorization.

OpenAI’s developer APIs can also attach the same remote MCP URL as an MCP tool. Use the Server URL plus OAuth or an organization API key, matching whatever auth method that API supports.

Cursor

Cursor supports remote MCP servers over HTTP. Add rocketblue to your MCP configuration file.

Option A: Copy from the app

In rocketblue, go to Settings → MCP.
Under Cursor, click the copy button.
Paste the JSON into your Cursor MCP config (project .cursor/mcp.json or global settings, depending on your setup).
Replace YOUR_API_KEY with your real API key from Settings → API if the placeholder is still shown.

Option B: Manual config

Use a unique server name and the team-specific Server URL for each organization:

{
  "mcpServers": {
    "rocketblue-484aa7033e56": {
      "url": "https://app.rocketblue.ai/api/mcp?484aa7033e56",
      "headers": {
        "x-spotlight-api-key": "YOUR_API_KEY"
      }
    }
  }
}

After saving, restart Cursor or reload MCP servers. You should see the rocketblue server listed with tools such as list_brands and get_organization_context.

In Cursor, ask the agent to “list my rocketblue brands” as a quick connectivity test.

Other MCP clients

Any client that supports HTTP MCP with custom headers can connect using:

Setting	Value
URL	Team Server URL from Settings → MCP (includes the unique query id)
Auth header	`x-spotlight-api-key: YOUR_API_KEY`
Transport	HTTP

Clients that support OAuth 2.0 for remote MCP can use the same Server URL plus OAuth Client ID and Client Secret from Settings → MCP. Alternative header names accepted by the underlying API (if your client cannot set x-spotlight-api-key):

Header	Example
`x-api-key`	`x-api-key: YOUR_API_KEY`
`spotlight-api-key`	`spotlight-api-key: YOUR_API_KEY`
`Authorization`	`Authorization: Bearer YOUR_API_KEY`

Verify the connection

Once connected, ask your assistant to:

Call get_organization_context — confirms auth and returns plan/brand count.
Call list_brands — returns brand IDs for your organization.

If authentication fails, double-check the credentials in Settings → MCP (and Settings → API for header-based clients) and that you are signed into the correct rocketblue account for OAuth.

Troubleshooting

Symptom	Likely cause	Fix
Claude registration fails	Automatic registration could not bind the team, or the Server URL is missing the team id	Use the Server URL from Settings → MCP, including the query id. If it still fails, expand Use your own OAuth client and paste the Client ID and Secret
ChatGPT OAuth / Scan Tools fails	Dynamic registration attempted, or Developer mode not enabled	Paste the pre-issued Client ID and Secret; confirm a workspace admin enabled Developer mode
Stuck on rocketblue loading screen during OAuth	Browser session / consent page issue	Sign into `app.rocketblue.ai` first, then retry the connector
`401 Invalid API key`	Wrong or revoked key	Copy the current key from Settings → API
`429 Too Many Requests`	Rate limit exceeded	Wait and retry; default quota is 120 requests/minute
Tools not appearing	Client not reloaded	Restart the MCP client after config changes
Empty brand list / wrong team	Wrong Server URL or credentials for that org	Use the unique Server URL and credentials for the intended team
Rotating OAuth secret breaks teammates	Secret is shared per team	Share the new secret; anyone still using the old one must update

Security notes

Each team’s Server URL and OAuth credentials are scoped to one organization.
Viewers and guests cannot authorize MCP access or modify data via API or MCP.
Rotate the OAuth Client Secret from Settings → MCP if it may have been exposed. Rotating invalidates the previous secret for everyone using that team.
For Cursor and other header-based clients, rotate the API key from Settings → API if needed.

​Before you connect

​Claude

​ChatGPT

​ChatGPT (workspace custom app)

​Cursor

​Option A: Copy from the app

​Option B: Manual config

​Other MCP clients

​Verify the connection

​Troubleshooting

​Security notes

Before you connect

Claude

ChatGPT

ChatGPT (workspace custom app)

Cursor

Option A: Copy from the app

Option B: Manual config

Other MCP clients

Verify the connection

Troubleshooting

Security notes