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. Authenticate once with a Shift API Key to answer questions like "what is the D30 LTV of my apps in US, CA, and UK?" or "show me the journey of users completing my tutorial for the last 2 app versions." and the assistant will call the correct Shift tool, resolve your filters, and return the data.

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) and query tools for mobile and web apps.

Discovery Tools

Mobile Query Tools

Web Query Tools

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)

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:

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