BlueConic MCP enables AI tools to interact with your BlueConic tenant, so you can explore, retrieve, and analyze configuration and customer data in natural language.

Availability: The authorization code flow in this article requires BlueConic release 104.0 or later on your tenant. On earlier releases, use header-based authentication or the local MCP client.

Important: When you open your BlueConic tenant with MCP, you give the model access to your environment. Use a trusted MCP host that handles data responsibly, and confirm that the host doesn't use your data to train its models. If the host misuses the context, it could expose sensitive information.

Key features:

Connects your AI tool to your tenant's MCP endpoint: https://tenantname.blueconic.net/mcp.
Read access to configuration and customer data, based on the tenant's OpenAPI spec, plus a search and count capability.
Secured with OAuth 2.0. The recommended method is the authorization code flow, with a browser sign-in and consent screen. Tools that can't open a browser can send client credentials in headers.
The tenant MCP endpoint is read-only. It doesn't change configuration and doesn't expose delete operations.
No local installation for Claude, ChatGPT, VS Code, or Cursor.

Choose a connection method:

Authorization code flow (recommended): Claude, ChatGPT, VS Code, and Cursor.
Header-based authentication: tools that can't run a browser sign-in, such as n8n or Databricks.
Local MCP client: only when the tool can't use either method above, for example Gemini CLI.

Before you begin

Make sure you have the following:

An active BlueConic tenant on release 104.0 or later for the authorization code flow.
An MCP-compatible tool such as Claude, ChatGPT, Cursor, or VS Code Copilot.
Permission to create an application in Settings > Access management > Applications.
For ChatGPT: a plan that allows Developer mode. Some workplace accounts disable custom connectors, so an administrator might need to allow them first.

Create an OAuth2 application in your BlueConic tenant

Every connection method needs an application in your tenant.

Log in to your BlueConic tenant.
Go to Settings > Access management > Applications.
Select Add application.
Under OAuth 2.0 flow, select:
- Authorization code flow to connect with a browser sign-in: Claude, ChatGPT, VS Code, and Cursor.
- Client credentials flow to connect with headers or the local MCP client: n8n, Databricks, scripts, and Gemini CLI.
To use both methods, create one application for each.
Grant the read scopes for the object types you want the AI tool to query, such as segments, listeners, and profile properties.
- Grant a read scope for each type you'll ask about. A missing scope produces a refusal that names the scope it needed. It doesn't return a wrong count.
- To ask how many profiles are in a segment, grant both PROFILES and SEGMENTS.
- Trackers use the URL_MAPPINGS scope.
Set a Run as user. Client credentials connections always run as this user. Authorization code connections run as the person who signs in, still limited by the application's scopes.
For the authorization code flow, add the AI tool's redirect URL under Redirect URL(s), and set the Application website URL when the tool's section below names one.
Turn the application ON.
Select Save.
For the client credentials flow, copy the Client ID and Client secret.

Connect with the authorization code flow (recommended)

This is the simplest and most secure way to connect, and the one we recommend for every tool that supports it.

First, create an application with Authorization code flow selected. Then enter your tenant's MCP address in the AI tool: https://tenantname.blueconic.net/mcp
The tool discovers how to authenticate, then opens a browser sign-in and consent screen. Some tools also ask for the application's client ID and client secret. If they do, paste the values from the application you created.

The connection runs as the BlueConic user who signs in, not as a shared service account. That user's permissions apply on top of the application's scopes.

Confirm that it worked

Ask the tool to list its MCP tools. You should see BlueConic read tools, including searchObjects. If the list is empty, the tool didn't reach /mcp: the URL is wrong, the application is off, or the sign-in didn't complete.

Claude (desktop, web, and mobile)

In the application, add this redirect URL: https://claude.ai/api/mcp/auth_callback
Set the application website URL to https://claude.ai/
In Claude, go to Settings > Connectors > Add custom connector.
Enter your tenant's MCP address: https://tenantname.blueconic.net/mcp
Select Connect. Claude opens your tenant's sign-in and consent screen in a browser.
Sign in and approve access.

If Claude asks for a client ID and client secret, paste them from the application.

Note: Some Claude for Work organizations block custom connectors. That's an organization policy, not a BlueConic configuration error. A BlueConic connector in Claude's directory is in progress. When it's approved, you can connect from the directory instead of adding a custom connector.

Note: If your organization turns off "Always allow" for Cowork, Claude asks you to approve each call. That's expected.

ChatGPT

Custom MCP connectors in ChatGPT require Developer mode. Labels vary by plan: Apps, Plugins, or Connectors.

In ChatGPT on the web, turn on Developer mode. It's usually under Settings > Apps > Advanced settings, or Settings > Security and login.
Create a custom app, plugin, or connector, and enter your tenant's MCP address: https://tenantname.blueconic.net/mcp
The first attempt usually fails, because ChatGPT uses a unique redirect URL for each connector. Copy the redirect URL ChatGPT shows. It looks like https://chatgpt.com/connector/oauth/<id>.
In BlueConic, add that URL to the application's redirect URLs, and set the application website URL to https://chatgpt.com
Connect again, sign in, and approve access.

Note: Workplace ChatGPT accounts can hide Developer mode or block custom connectors until an administrator allows them. Custom MCP connectors are a ChatGPT web feature and aren't available in the mobile app.

VS Code

Add this to mcp.json:

{
  "servers": {
    "blueconic": {
      "name": "BlueConic MCP Server",
      "description": "BlueConic MCP Server",
      "type": "http",
      "url": "https://tenantname.blueconic.net/mcp"
    }
  }
}

VS Code discovers the OAuth flow from the URL and opens a browser the first time you use the connection.

In the application's redirect URLs, add:

https://vscode.dev/redirect
http://127.0.0.1:33418/

If the error names a different local port, add that URL and try again.

Cursor

Add this to .cursor/mcp.json:

{
  "mcpServers": {
    "blueconic": {
      "name": "BlueConic MCP Server",
      "description": "BlueConic MCP Server",
      "type": "http",
      "url": "https://tenantname.blueconic.net/mcp"
    }
  }
}

The first connection opens a browser sign-in. Add the redirect URL that Cursor shows to the application's redirect URLs. It's often a local address, similar to VS Code. If Cursor asks for a client ID and client secret, paste them from the application.

Connect with header-based authentication

Use this when the tool can't run a browser sign-in: a script, an automation platform, n8n, or Databricks.

Create an application with Client credentials flow selected, and copy its Client ID and Client secret. This connection always runs as the application's Run as user, limited by the application's scopes. If no Run as user is set, calls that need a user fail.

One custom header

Several MCP tools allow only one custom header. Combine the client ID and client secret with ##:

X-BlueConic-Client-ID-Secret: <client-ID>##<client-secret>

Don't add spaces around ##.

Two custom headers

If the tool can send two headers:

X-BlueConic-Client-ID: <client-ID>
X-BlueConic-Client-Secret: <client-secret>

VS Code (header-based)

{
  "servers": {
    "blueconic": {
      "name": "BlueConic MCP Server",
      "description": "BlueConic MCP Server",
      "type": "http",
      "url": "https://tenantname.blueconic.net/mcp",
      "headers": {
        "X-BlueConic-Client-ID": "${input:blueconic-oauth2-client-id}",
        "X-BlueConic-Client-Secret": "${input:blueconic-oauth2-client-secret}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "blueconic-oauth2-client-id",
      "description": "BlueConic OAuth2.0 Client ID",
      "password": true
    },
    {
      "type": "promptString",
      "id": "blueconic-oauth2-client-secret",
      "description": "BlueConic OAuth2.0 Client secret",
      "password": true
    }
  ]
}

Cursor (header-based)

Don't commit client secrets to a shared repository. Use environment variables or a local configuration file that's excluded from version control.

{
  "mcpServers": {
    "blueconic": {
      "name": "BlueConic MCP Server",
      "description": "BlueConic MCP Server",
      "type": "http",
      "url": "https://tenantname.blueconic.net/mcp",
      "headers": {
        "X-BlueConic-Client-ID": "client-id-here",
        "X-BlueConic-Client-Secret": "client-secret-here"
      }
    }
  }
}

Use a token directly

{
  "servers": {
    "blueconic": {
      "name": "BlueConic MCP Server",
      "description": "BlueConic MCP Server",
      "type": "http",
      "url": "https://tenantname.blueconic.net/mcp",
      "headers": {
        "Authorization": "Bearer ${input:blueconic-oauth2-api-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "blueconic-oauth2-api-token",
      "description": "BlueConic Server OAuth2.0 Token",
      "password": true
    }
  ]
}

If header-based authentication fails

401 error: The application is off, the client ID or secret is wrong, or a header name is misspelled. Check Settings > Access management > Applications.
The tool says it needs a user: Set a Run as user on the application.
A prompt is refused and names a scope: Grant that read scope and try again.

Local MCP client

Use this only when the tool can't use the authorization code flow or header-based authentication.

Gemini CLI is the usual case. For Claude, ChatGPT, VS Code, and Cursor, use the authorization code flow instead: there's no local process to keep updated, and you sign in through a browser instead of keeping a secret in a configuration file.The local client is the npm package @blueconic/blueconic-mcp. It connects to your tenant with the client ID and secret of an application with Client credentials flow selected. Unlike the tenant MCP endpoint, this client can make a limited set of changes, with extra confirmation for high-impact changes. It can't delete anything.

Set BLUECONIC_TENANT_URL to the tenant address without /mcp, for example https://tenantname.blueconic.net

Gemini CLI

Add this to your project settings in .gemini/settings.json, or to your user settings in ~/.gemini/settings.json:

{
  "mcpServers": {
    "blueconic": {
      "command": "npx",
      "args": [
        "@blueconic/blueconic-mcp"
      ],
      "env": {
        "BLUECONIC_TENANT_URL": "https://tenantname.blueconic.net",
        "OAUTH_CLIENT_ID": "client-id-here",
        "OAUTH_CLIENT_SECRET": "client-secret-here"
      },
      "trust": true
    }
  }
}

Restart Gemini CLI and run /mcp. Gemini CLI shows the blueconic server as connected and lists the available tools.

Note: If you installed the older Claude Desktop .mcpb extension, it still works, but we recommend switching to the authorization code flow.

Example prompts

Once connected, use natural language to query your tenant:

"Get all segments from my BlueConic tenant and show me the commonalities."
"Show me profiles in the 'high-value-customers' segment."
"How many listeners, dialogues, and segments are in my tenant?"
"How many profile properties have had no value set in the last 365 days?"
"Retrieve 1000 profiles from the all visitors segment and summarize key insights."

Tip: To get an exact total instead of a count of one page of results, ask the tool to use the search and count tool.

Next steps

Run the same kind of question on a schedule inside BlueConic with the AI Agent Connection.
Connect from Databricks with client credentials: Using the BlueConic MCP Server on Databricks.

BlueConic Model Context Protocol (MCP)