Connecting to the FreeWheel Buyer Cloud MCP Server

Step-by-step setup guides for connecting your AI assistant to our Model Context Protocol (MCP) server. Pick the tool you use below.

Not sure which guide to follow?

Claude — choose this if you use the Claude desktop app or claude.ai in a browser.

Gemini — Google offers several Gemini products. The setup differs for each, so this tab is split into three: the Gemini CLI (a terminal tool), Gemini Code Assist (the IDE extension), and the Gemini web/app. Use whichever you have.

Codex — choose this if you use the Codex desktop app and want to connect it to a hosted MCP server over OAuth.

ChatGPT — choose this if you connect through ChatGPT. Note that custom connectors require a paid plan and Developer Mode.

The MCP server URL for all tools is https://bcmcp.freewheel.com/mcp/oauth.

For a full reference of every tool available on the MCP server, see https://bcmcp.freewheel.com/reference.

Connecting with Claude

These steps cover the Claude desktop app and claude.ai. They connect Claude to a remote (hosted) MCP server via a URL.

Before you start: You need the Claude desktop app installed (download from claude.ai/download) or access to claude.ai in a browser, and a paid Claude plan (Pro, Max, Team, or Enterprise). Custom connectors are not available on the free plan.
Add the connector
  1. Open Claude and sign in to your account.
  2. Click Settings (the gear icon), then open the Connectors section.
  3. Click Add custom connector. You may find this under a Manage connectors button.
  4. Give the connector a name (for example, "FreeWheel Buyer Cloud") and paste the server URL: https://bcmcp.freewheel.com/mcp/oauth
  5. Click Add to save the connector.
  6. If the server uses OAuth sign-in, the FreeWheel Buyer Cloud login window opens. Fill in the form (see the field guide below), then approve the requested access. You complete this sign-in step yourself — it is not done for you.

    About the FreeWheel Buyer Cloud sign-in form

    EmailRequired
    The email address for your FreeWheel Buyer Cloud account.
    PasswordRequired
    Your account password. It is processed securely server-side and is not stored in the browser.
    Buzz KeyRequired
    The identifier for your Buyer Cloud environment — for example, dsp or demosbx. If you are unsure which value to use, ask your FreeWheel contact.
    Account IDOptional
    Leave this blank unless you need to sign in to a specific account. When blank, your default account is used.
    Recommended: When you first connect, sign in with a read-only account until you are comfortable with the tools. This prevents accidental changes while you are still getting familiar with what each tool does. Once you are confident, you can switch to an account with full permissions. If you do not have a read-only account, you can create one in the Buyer Cloud UI.
Verify it works
  1. Open any conversation and look for the tools / connector icon in the message input area.
  2. Click it and confirm your server's tools appear in the list.
  3. Try a prompt that uses one of the tools. Claude asks you to approve each tool call before it runs — you can approve once, approve for the session, or deny.
Success looks like: Your connector appears in the Connectors list, and its tools show up when you click the tools icon inside a chat.

Connecting with Gemini

"Gemini" refers to several different Google products. Find the one you use among the three below and follow that variant.

Recommended: The first time a tool runs, Gemini opens the FreeWheel Buyer Cloud sign-in page in your browser. When you sign in, use a read-only account until you are comfortable with the tools — this prevents accidental changes while you are still getting familiar with what each tool does. Once you are confident, you can switch to an account with full permissions. If you do not have a read-only account, you can create one in the Buyer Cloud UI.

Variant A — Gemini CLI

The command-line tool you run in a terminal. Configured through a settings.json file.

Before you start: Gemini CLI must be installed and working in a terminal. MCP servers are defined in a settings.json file.
Method 1 — the quick command
  1. Open your terminal.
  2. Run the following. You can change "Buyer Cloud MCP" to any name you like for the server: 
    # adds a remote MCP server over HTTP
gemini mcp add --transport http "Buyer Cloud MCP" https://bcmcp.freewheel.com/mcp/oauth
  3. Restart Gemini CLI so it picks up the new server.
Method 2 — edit settings.json directly
  1. Locate your settings file. For a setup that applies everywhere, use ~/.gemini/settings.json (the ~ is your home folder). For a single project, use .gemini/settings.json inside that project folder. Create the file or the .gemini folder if it does not exist.
  2. Add an mcpServers block with the Buyer Cloud MCP server: 
    {
  "mcpServers": {
    "Buyer Cloud MCP": {
      "url": "https://bcmcp.freewheel.com/mcp/oauth"
    }
  }
}
  3. Save the file. Make sure the JSON is valid — a stray comma or missing bracket is the most common mistake.
  4. Restart Gemini CLI.
Verify it works
  1. Inside Gemini CLI, type /mcp.
  2. Your server should be listed with a green status indicator and the tools it provides.
Success looks like: /mcp shows your server as "Ready" with a green dot and a list of tools. If it shows disconnected, check the startup logs for a wrong URL, an expired token, or invalid JSON.

Variant B — Gemini Code Assist (IDE extension)

The Gemini extension inside VS Code. It uses the same settings.json file as the CLI.

Before you start: The Gemini Code Assist extension must be installed in your IDE, with agent mode available. MCP support in JetBrains IDEs is limited — VS Code is the supported path.
  1. Open your Gemini settings file at ~/.gemini/settings.json (the ~ is your home folder). Create it if it does not exist.
  2. Add the same mcpServers block shown in Variant A above (Buyer Cloud MCP with its url).
  3. Save the file.
  4. Restart your IDE, or reload the Gemini Code Assist extension, so the change is picked up.
  5. Open Gemini's agent mode in the IDE and confirm the server's tools are available.
Heads up: MCP servers can run code with your user account's permissions. Only connect servers you trust the source of.

Variant C — Gemini web & mobile app

The Gemini assistant at gemini.google.com and the mobile apps.

Important: The consumer Gemini web and mobile apps do not currently support adding custom MCP servers the way the CLI and Code Assist do. If you only use the Gemini app, you cannot connect directly to a custom MCP server today.

If you need to use a FreeWheel MCP server with Gemini, use the Gemini CLI (Variant A) instead. If you believe your organization has a setup that exposes MCP tools to the Gemini app, contact your FreeWheel representative — that would be a custom arrangement, and the steps above will not apply.

Connecting with Codex Desktop

Use these steps to connect the Codex desktop app to the hosted FreeWheel Buyer Cloud MCP server over OAuth.

Before you start: Make sure you are signed in to the Codex desktop app and can access MCP server settings. In some versions this appears under Settings and then Tools, Integrations, or MCP.
Add the MCP server
  1. Open Codex Desktop and go to Settings.
  2. Open the MCP / Tools / Integrations section.
  3. Click Add server (or Add MCP server).
  4. Set the server URL to: https://bcmcp.freewheel.com/mcp/oauth
  5. Choose OAuth authentication if Codex asks for an auth method.
  6. Save the server, then complete the browser sign-in flow when prompted.

    About the FreeWheel Buyer Cloud sign-in form

    EmailRequired
    The email address for your FreeWheel Buyer Cloud account.
    PasswordRequired
    Your account password. It is processed securely server-side and is not stored in the browser.
    Buzz KeyRequired
    The identifier for your Buyer Cloud environment — for example, dsp or demosbx. If you are unsure which value to use, ask your FreeWheel contact.
    Account IDOptional
    Leave this blank unless you need to sign in to a specific account. When blank, your default account is used.
    Recommended: When you first connect, sign in with a read-only account until you are comfortable with the tools. This prevents accidental changes while you are still getting familiar with what each tool does. Once you are confident, you can switch to an account with full permissions. If you do not have a read-only account, you can create one in the Buyer Cloud UI.
Verify it works
  1. Open a new Codex chat/session.
  2. Check that the MCP server appears as connected in Codex's server/tool list.
  3. Run a simple prompt that should use a Buyer Cloud tool (for example: "List available tool categories").
Success looks like: Codex shows the server as connected and can run Buyer Cloud tools after OAuth sign-in.

Connecting with ChatGPT

ChatGPT connects to MCP servers as a "custom connector." This requires Developer Mode, which is only on paid plans.

Plan requirements — read first: Custom MCP connectors need Developer Mode. This is available on ChatGPT Plus and Pro (personal accounts) and on Business, Enterprise, and Edu (organization accounts). On organization plans, a workspace admin must enable Developer Mode — a regular member cannot turn it on themselves. If you are on a free plan, this is not available to you.
Step A — Enable Developer Mode
  1. In ChatGPT, open Settings.
  2. Go to Apps & Connectors, then open Advanced settings.
  3. Toggle Developer Mode to ON.
  4. A warning appears noting that custom connectors are not verified by OpenAI and could modify or delete data. Read it, then confirm to continue.

On Business / Enterprise / Edu plans, the admin enables this under Workspace Settings → Permissions & Roles → Connected Data, rather than in personal Settings.

Step B — Add the connector
  1. Return to Settings → Apps & Connectors and click Add new connector (it may say Create).
  2. Enter a name and a short description for the connector.
  3. Paste the MCP server URL: https://bcmcp.freewheel.com/mcp/oauth
  4. For authentication, ChatGPT connectors use OAuth (API-key authentication is not supported). You will be sent to the FreeWheel Buyer Cloud sign-in page — fill in the form (see the field guide below) and approve access.

    About the FreeWheel Buyer Cloud sign-in form

    EmailRequired
    The email address for your FreeWheel Buyer Cloud account.
    PasswordRequired
    Your account password. It is processed securely server-side and is not stored in the browser.
    Buzz KeyRequired
    The identifier for your Buyer Cloud environment — for example, dsp or demosbx. If you are unsure which value to use, ask your FreeWheel contact.
    Account IDOptional
    Leave this blank unless you need to sign in to a specific account. When blank, your default account is used.
    Recommended: When you first connect, sign in with a read-only account until you are comfortable with the tools. This prevents accidental changes while you are still getting familiar with what each tool does. Once you are confident, you can switch to an account with full permissions. If you do not have a read-only account, you can create one in the Buyer Cloud UI.
  5. Save. The connector now appears in your Apps & Connectors list with a custom label.
Step C — Use it in a chat
  1. Start a new chat.
  2. Use the connector / tools picker in the message box (the + menu) to enable your connector for that conversation.
  3. Try a prompt that uses one of its tools.
Success looks like: Your connector shows in Apps & Connectors with a "custom" label, and you can switch it on inside a chat from the + menu.

OAuth Callback URL Restrictions

When your AI client registers with this server it must provide a callback URL (also called a redirect URI) where the authorization code is delivered after you sign in. For security, the server only accepts callback URLs from a pre-approved allowlist.

Using a custom callback URL? If your client uses a callback URL that is not in the table below, registration will fail with a 400 Bad Request. Contact us before connecting so we can add your URL to the allowlist.
Pre-approved callback URLs

The following clients and patterns are supported out of the box — no action required:

Client / Platform Callback URL pattern Notes
Claude Desktop (Anthropic) https://claude.ai/…callback… Standard Claude MCP connector
ChatGPT (OpenAI) https://chatgpt.com/…oauth… Standard ChatGPT connector
N8N https://n8n.*/… N8N automation nodes
Azure API Management https://*.azure-apim.net/… APIM OAuth integration
Native / desktop apps http://127.0.0.1:<any-port>/… RFC 8252 loopback standard for installed apps
Native / desktop apps http://localhost:<any-port>/…

Loopback addresses (127.0.0.1 / localhost) are allowed on any port per RFC 8252 §7.3, which is the standard for native and desktop MCP clients that start a temporary local HTTP listener during the OAuth flow.

Requesting a custom callback URL

If your platform requires a different callback URL, contact the FreeWheel team with the following information:

Once approved, the URL will be added to the allowlist and your client registration will succeed.

Error you will see

If your callback URL is not on the allowlist, /oauth/register returns:

{"detail": "redirect_uri not allowed: <your-uri>"}

HTTP status: 400 Bad Request.