Connecting to the FreeWheel Streaming Hub 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 Desktop — choose this if you use the Codex desktop app and want to add the Streaming Hub MCP server as a remote MCP connection.

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://shmcp.freewheel.com/mcp/oauth.

For a full reference of every tool available on the MCP server, see https://shmcp.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 Streaming Hub") and paste the server URL: https://shmcp.freewheel.com/mcp/oauth
  5. Click Add to save the connector.
  6. If the server uses OAuth sign-in, the FreeWheel Streaming Hub 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 Streaming Hub sign-in form

    EnvironmentRequired
    A drop-down with two choices: Production or Staging. Pick the environment you wish to connect against — choose Staging if you are testing.
    API UsernameRequired
    The API username for your FreeWheel Streaming Hub account. This may differ from your regular login username — if you are unsure, ask your FreeWheel account team.
    PasswordRequired
    The password for that API username. It is processed securely server-side and is not stored in the browser.
    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, ask your FreeWheel account team.
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 Streaming Hub 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, ask your FreeWheel account team.

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 "Streaming Hub MCP" to any name you like for the server: 
    # adds a remote MCP server over HTTP
gemini mcp add --transport http "Streaming Hub MCP" https://shmcp.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 Streaming Hub MCP server: 
    {
  "mcpServers": {
    "Streaming Hub MCP": {
      "url": "https://shmcp.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 (Streaming Hub 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 this guide to connect the Codex desktop app to the hosted FreeWheel Streaming Hub MCP server URL.

Before you start: You need the Codex desktop app installed and signed in. MCP support must be enabled in your app build.
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, ask your FreeWheel account team.
Add the MCP server
  1. Open Codex Desktop and go to Settings.
  2. Open the MCP or Tools / Connectors section.
  3. Choose Add MCP server (or similar), then enter:

    Server values

    NameRequired
    Use a friendly label such as FreeWheel Streaming Hub.
    Server URLRequired
    https://shmcp.freewheel.com/mcp/oauth
    TransportOptional
    If asked, choose HTTP.
  4. Save the server. If prompted for authentication, continue with OAuth sign-in.
  5. In the FreeWheel Streaming Hub sign-in page, complete the form and approve access:

    About the FreeWheel Streaming Hub sign-in form

    EnvironmentRequired
    A drop-down with two choices: Production or Staging. Pick the environment you wish to connect against — choose Staging if you are testing.
    API UsernameRequired
    The API username for your FreeWheel Streaming Hub account. This may differ from your regular login username — if you are unsure, ask your FreeWheel account team.
    PasswordRequired
    The password for that API username. It is processed securely server-side and is not stored in the browser.
Verify it works
  1. Open a new Codex conversation.
  2. Open the tools/MCP picker and confirm the FreeWheel Streaming Hub server is listed.
  3. Run a simple read-only request and confirm the tool call succeeds.
Success looks like: The Streaming Hub MCP server appears as connected, and Codex can run its tools inside a chat.

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://shmcp.freewheel.com/mcp/oauth
  4. For authentication, ChatGPT connectors use OAuth (API-key authentication is not supported). You will be sent to the FreeWheel Streaming Hub sign-in page — fill in the form (see the field guide below) and approve access.

    About the FreeWheel Streaming Hub sign-in form

    EnvironmentRequired
    A drop-down with two choices: Production or Staging. Pick the environment you wish to connect against — choose Staging if you are testing.
    API UsernameRequired
    The API username for your FreeWheel Streaming Hub account. This may differ from your regular login username — if you are unsure, ask your FreeWheel account team.
    PasswordRequired
    The password for that API username. It is processed securely server-side and is not stored in the browser.
    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, ask your FreeWheel account team.
  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.