ZenShows MCP

Quickstart

Connect in five minutes.

ZenShows MCP requires authentication. A 401 response does not mean the server is down — it means you need to complete OAuth or add an API key.

0. Agents: call zenshows_guide first

No credentials needed. The MCP server exposes one public tool — zenshows_guide — that returns this document's connection steps. If you see "couldn't load MCP servers", call this tool or read this page before asking the human for an API key.

1. Choose your path

ClientRecommended auth
Claude Desktop / Claude.aiOAuth (browser login)
CursorAPI key (zs_)
Scripts / headlessAPI key (zs_)

2a. OAuth — Claude Desktop / Claude.ai

  1. In your MCP client, add a remote server with URL:
https://www.zenshows.com/mcp
  1. Leave auth empty. The client should open a browser when it receives HTTP 401.
  2. Sign in with your ZenShows email and password and click Allow.
  3. Confirm tools appear (e.g. get_account_info, query_data).
If your client supports OAuth (Claude Desktop, Claude.ai):
1. Add remote MCP URL: https://www.zenshows.com/mcp
2. Do not paste a placeholder API key.
3. When prompted, sign in at ZenShows and approve access.

2b. API key — Cursor and headless clients

  1. Log into ZenShows.
  2. Go to My Profile or Company Settings → API Access.
  3. Create or copy an API key (starts with zs_).
  4. Add to your MCP config:
{
  "mcpServers": {
    "zenshows": {
      "url": "https://www.zenshows.com/mcp",
      "headers": { "Authorization": "Bearer zs_…" }
    }
  }
}

Alternative if your client cannot set headers: embed the key in the URL path — https://www.zenshows.com/mcp/zs_YOUR_KEY.

3. Verify the connection

Ask your assistant to call get_account_info. You should see your vendor name and retailer list. Then try:

  • "How many events do we have scheduled next week?"
  • "Who is staffed on the Tustin Costco event? Preview assigning Maria."

4. First analytics query

Before writing SQL, the assistant should call get_data_lake_schema. Your enabled tables depend on your Data Hub configuration. Example:

SELECT rep_first_name, rep_last_name, SUM(daily_retail_attributed) AS retail
FROM llm_dl_rep_daily
WHERE work_date >= DATE_SUB(CURDATE(), INTERVAL 7 DAY)
  AND is_planned_day = 0
GROUP BY rep_user_id, rep_first_name, rep_last_name
ORDER BY retail DESC
LIMIT 20

vendor_id is injected automatically — do not filter on it.

Troubleshooting

SymptomFix
White box: "MCP servers couldn't be loaded"Complete OAuth or add a real zs_ key — not a placeholder URL only.
401 on every requestAuth missing or expired. Re-connect OAuth or regenerate key.
Tools list shows only zenshows_guideExpected before auth. Finish OAuth or add Bearer token.
Write refusedYour user lacks permission in ZenShows UI for that action.
SDK hangs after initializeForward ALB Set-Cookie headers on follow-up requests (headless SDK clients).

Learn more