Shift MCP Query API

Overview

The Shift MCP server connects to the ByteBrew suite to enable your AI assistant to retrieve analytics for the apps in your studio, and to operate your Remote Configs and A/B Tests. Authenticate once with a Shift API Key to answer questions like "what is the D30 LTV of my apps in US, CA, and UK?", "show me the journey of users completing my tutorial for the last 2 app versions." or "which step of my onboarding funnel drops the most players?" and the assistant will call the correct Shift tool, resolve your filters, and return the data. You can then act on it in the same session with prompts such as "lower the starting lives remote config to 3" or "roll out Group B of my difficulty test."

Server Details

The Shift MCP is a remote MCP server over Streamable HTTP. There is nothing to install or run locally. Point your tool at the server URL below and attach your Shift API Key.

Authentication

The Shift MCP authenticates every request with a Shift API Key. Generate a key from your Studio Settings, then attach it to your MCP client as a Bearer token. There is no separate token-generation call. The key itself is the credential, and it is scoped to the apps owned by your studio account.

Every request to the server must include an Authorization header. See the expected header format below:

                                


                                Authorization: Bearer YOUR_SHIFT_API_KEY


                                
                            

Create API Key

To create a Shift API Key, navigate to the API Key tab in the Shift Settings and hit the create button.

Delete API Key

To delete a Shift API Key, navigate to the API Key tab in the Shift Settings and hit the delete button next to the key you want to delete.

Claude Desktop

Add the server by editing the claude_desktop_config.json file (Settings → Developer → Edit Config). Claude Desktop connects to remote servers through the mcp-remote bridge, and your Shift API Key is passed via the Authorization header. Place your key in the AUTH_TOKEN environment variable so it is not inlined into the arguments:

{
  "mcpServers": {
    "bytebrew-shift-mcp-query-api": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://shift-mcp.bytebrew.io/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "Bearer YOUR_SHIFT_API_KEY"
      }
    }
  }
}

Fully quit and restart Claude Desktop, then check Settings → Developer to confirm the bytebrew-shift-mcp-query-api server is connected and its tools are listed.

Claude Code

Add the server with the claude mcp add command using the HTTP transport, passing your key with --header:

claude mcp add --transport http bytebrew-shift-mcp-query-api https://shift-mcp.bytebrew.io/mcp --header "Authorization: Bearer YOUR_SHIFT_API_KEY"

Or add it to a project's .mcp.json file to share it with your team (keep real keys out of shared files, use an environment variable):

{
  "mcpServers": {
    "bytebrew-shift-mcp-query-api": {
      "type": "http",
      "url": "https://shift-mcp.bytebrew.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SHIFT_API_KEY"
      }
    }
  }
}

Run /mcp inside Claude Code to confirm the bytebrew-shift-mcp-query-api server is connected.

Cursor

Add the server to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project root. Cursor uses the url field for remote Streamable HTTP servers and a headers object for authentication:

{
  "mcpServers": {
    "bytebrew-shift-mcp-query-api": {
      "url": "https://shift-mcp.bytebrew.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SHIFT_API_KEY"
      }
    }
  }
}

Then open Settings → MCP & Integrations and verify bytebrew-shift-mcp-query-api shows a green status with its tools listed.

OpenAI Codex

Add the remote server to ~/.codex/config.toml. Codex connects to Streamable HTTP servers with a url and passes the Shift API Key through http_headers:

[mcp_servers.bytebrew-shift-mcp-query-api]
url = "https://shift-mcp.bytebrew.io/mcp"
http_headers = { "Authorization" = "Bearer YOUR_SHIFT_API_KEY" }

Start a Codex session and run /mcp to confirm the server is connected and its tools are listed.

Google Antigravity

In Antigravity, open Settings → Customizations and click Open MCP Config to edit mcp_config.json. Antigravity uses the serverUrl field for remote servers and a headers object for the Bearer token:

{
  "mcpServers": {
    "bytebrew-shift-mcp-query-api": {
      "serverUrl": "https://shift-mcp.bytebrew.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SHIFT_API_KEY"
      }
    }
  }
}

Save the file, then open the MCP Servers panel and refresh to load the bytebrew-shift-mcp-query-api tools.

Cursor Agent (CLI)

The cursor-agent CLI automatically discovers the same mcp.json configuration used by the Cursor editor. Add the server to ~/.cursor/mcp.json or your project's .cursor/mcp.json with your key in the headers object:

{
  "mcpServers": {
    "bytebrew-shift-mcp-query-api": {
      "url": "https://shift-mcp.bytebrew.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SHIFT_API_KEY"
      }
    }
  }
}

In an interactive cursor-agent session, enable the server with the slash command:

/mcp enable bytebrew-shift-mcp-query-api

Gemini CLI

Add the server to your Gemini CLI settings.json (global at ~/.gemini/settings.json or project-scoped at .gemini/settings.json). Gemini CLI uses the httpUrl field for Streamable HTTP servers and a headers object for authentication:

{
  "mcpServers": {
    "bytebrew-shift-mcp-query-api": {
      "httpUrl": "https://shift-mcp.bytebrew.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SHIFT_API_KEY"
      }
    }
  }
}

Launch gemini and run the /mcp command to list the discovered server and its tools.

JetBrains AI Assistant

In your JetBrains IDE, go to Settings → Tools → AI Assistant → Model Context Protocol (MCP) and click Add. Choose As JSON and paste the following. AI Assistant connects to remote servers over Streamable HTTP using the url field, with a headers object for the Bearer token:

{
  "mcpServers": {
    "bytebrew-shift-mcp-query-api": {
      "url": "https://shift-mcp.bytebrew.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SHIFT_API_KEY"
      }
    }
  }
}

Apply the settings. The server's tools appear in the MCP section once the connection succeeds.

Visual Studio Code

Create a .vscode/mcp.json file in your workspace. VS Code uses the servers root key, requires "type": "http" for remote servers, and accepts a headers object for authentication:

{
  "servers": {
    "bytebrew-shift-mcp-query-api": {
      "type": "http",
      "url": "https://shift-mcp.bytebrew.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SHIFT_API_KEY"
      }
    }
  }
}

Available Tools

Once connected, the Shift MCP exposes the tools below. Your assistant selects the right tool automatically based on your prompt. Tools are split into discovery tools (which resolve app IDs, filter values, custom events, and AB tests), query tools for mobile and web apps, and Live Ops management tools that read and write your Remote Configs and A/B Tests.

Discovery Tools

Mobile Query Tools

Web Query Tools

Live Ops Management Tools

These tools operate on your live game configuration and work for both mobile and web apps. See Live Ops Management for their full parameters and examples, and the Remote Configs and A/B Tests dashboard docs for managing the same objects in ByteBrew.

Filters & Parameters

Every query tool takes a date range, and most take the shared filter dimensions below. Filter values that accept lists are passed as comma-separated strings.

Common Parameters

Mobile Filter Dimensions

Web Filter Dimensions

Retention Scale (retention & retained tools)

Funnel Parameters

The funnel tools measure how many users progress through an ordered sequence of events, in strict order. They accept the common parameters and the platform filter dimensions above, plus the following.

A funnel request looks like this:

{
  "gameId": "YOUR_GAME_ID",
  "startDate": "2026-08-01",
  "endDate": "2026-09-01",
  "funnel_events": "[{\"event\": \"User Install\"}, {\"event\": \"tutorial_complete\"}, {\"event\": \"level_complete\", \"level\": \"1\"}, {\"event\": \"level_complete\", \"level\": \"5\"}]",
  "breakdown": "geo",
  "country": "US,GB"
}

Each returned row is one funnel step:

Live Ops Management

Shift's Live Ops tools let your assistant read and operate the Remote Configs and A/B Tests of any app in your studio, for both mobile and web platforms. This closes the loop on analysis: query the data, pick the change, then ship it without leaving your AI workflow.

Shift operates on the same Live Ops objects you manage on the ByteBrew dashboard. See the Remote Configs and A/B Tests dashboard docs for the full feature reference.

Remote Configs List

Returns a game's live remote config values and its saved conditions. Requires gameId. The response has two parts:

Create Remote Config

Creates a new remote config value for a game. Fails if the config_key already exists; update it instead.

A conditional config with two segment overrides:

{
  "gameId": "YOUR_GAME_ID",
  "config_key": "starting_lives",
  "config_name": "Starting Lives",
  "config_type": "conditional",
  "config_value": "5",
  "conditional_values": "[{\"conditionID\": \"cond_us_whales\", \"value\": \"3\"}, {\"conditionID\": \"cond_new_installs\", \"value\": \"7\"}]",
  "end_date": "never"
}

Update Remote Config

Updates an existing remote config, matched by config_key. Only the fields you provide change; everything else keeps its stored value. Fails if no config with that key exists.

AB Tests List

Lists a game's A/B tests with full details and lifecycle status. Requires gameId. Use this to review tests before ending, archiving, or rolling one out; use the AB Tests discovery tool when you only need filter keys for an analytics query.

Create AB Test

Creates a new A/B test on a game. The SDK starts enrolling players from start_date. The parameters below map to the dashboard's test setup panels. See Create A/B Tests for the details, filters, groups, and goals in full.

Goal presets. Mobile apps support retention:1, retention:3, retention:7, retention:14, retention:30, playtime, sessions, sessionlength, arpdau, arppu, ads, purchases, and eventsTracked. Web apps support only retention:*, playtime, sessions, sessionlength, and eventsTracked.

{
  "gameId": "YOUR_GAME_ID",
  "ab_name": "Starting Lives Test",
  "ab_key": "starting_lives_test",
  "groups": "{\"Control Group\": {}, \"Group A\": {\"starting_lives\": \"5\"}, \"Group B\": {\"starting_lives\": \"10\"}}",
  "start_date": "2026-09-05",
  "ab_goal": "retention:7",
  "extra_goal_presets": "[\"arpdau\", \"sessions\"]",
  "ab_percentage": "50",
  "ab_geo": "US,GB"
}

Update AB Test Status

Changes the lifecycle status of a test. Requires gameId, the ab_key from AB Tests List, and a status. To edit a running test's details or configs instead of its status, use the dashboard. See Manage A/B Tests:

Rollout AB Test

Promotes the winning group of a test into the game's live remote config, then archives the test. Requires gameId, ab_key, and group, the winning group name (e.g. Group A), which must be one of the test's groups.

For every config key in the chosen group: if no remote config with that key exists it is created (as a single config with end_date of never); if one already exists its config_value is updated to the group's value. The response lists exactly which configs were created and which were updated.

This is the same operation as a Full Rollout on the dashboard. See Manage A/B Tests for Full Rollouts and for Staged Rollouts, which promote a single winning group to run against the control group and are only available from the dashboard. The promoted values then appear on your Remote Configs dashboard.

Full Live Ops Loop

The tools are designed to chain. A typical session runs:

Using the Assistant

After connecting the server, prompt your AI assistant with data questions in natural language. The assistant resolves your app and filters using the discovery tools, then calls the right query tool. Use prompts such as:

Live Ops prompts work the same way:

Token Usage

Usage of Shift is calculated by tokens. Each request you make using Shift utilizes tokens. The number of tokens consumed by the request varies based on the time the query takes to execute. The more complex the query, the more time/tokens it takes to complete.

Each pricing tier contains a set of tokens included in the monthly subscription. If you surpass the allotted tokens in your plan, you will be charged overage per token over your subscription's plan. For overage pricing, see your relevant plan on the Shift Settings page.

Turn Off Overage

To stop overage token spend, toggle off the Overage Billing setting in your Shift Settings. Enabling this setting will stop your AI assistant from querying Shift after you've reached the monthly token threshold in your plan.

Set Overage Budgets

To control overage spend, you can select the "Set Overage Budget" button to input a max overage spend per API Key.

Manage Usage

You can view and manage your token usage on the ByteBrew by navigating to the Shift page in your Studio Settings. Under the dashboard you can see how many tokens have been used, and manage Shift API Keys.

Manage Subscription

Manage your Shift plan from your Shift Settings. You can upgrade, downgrade, or cancel your subscription at any time.

Upgrade Plan

To upgrade your plan, go to the Shift Settings and hit "Upgrade".

Downgrade Plan

To downgrade your plan, go to the Shift Settings and hit "Downgrade" to your preferred plan.

Cancel Plan

To cancel your plan, go to your Shift Settings and hit "Cancel".

FAQs