# Zuora MCP (Model Context Protocol) The **Zuora MCP Server** connects your AI applications directly to Zuora, giving you access to Zuora tools, resources, and prompts from within Codex, Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients. ## ⚠️ Breaking Changes in 1.0.0 **This release is a major change.** If you depend on previous behavior, pin to `zuora-mcp@1.0.0-beta.7` (see [Pinning a version](#pinning-a-version)). > **Zuora AI permission enforcement:** Executing AI-specific operations now requires tenant-level AI read/write permissions. Write operations are blocked for tenants without AI write access, and tool visibility and accessibility are governed by tenant-level AI permissions. To verify access, log in as a Zuora OneID admin and navigate to Admin Console > AI. | Change | Previous (≤ 1.0.0-beta.7) | Current (≥ 1.0.0) | |--------|---------------------------|--------------------------| | **Approval process** | `zuora_approval` tool enforced approval for mutating operations | **Removed.** All operations execute immediately. | | **Auth required** | `zuora_codegen` and `sdk_upgrade` worked without credentials | **All tools require** `ZUORA_BASE_URL`, `ZUORA_CLIENT_ID`, and `ZUORA_CLIENT_SECRET` | | **Zuora AI permissions** | Tools were not filtered by tenant-level AI read/write permissions | AI-specific operations require tenant-level AI read/write permissions; write operations, tool visibility, and accessibility now honor tenant-level AI access. | | **Tool availability** | Fixed set of tools | Dynamically discovered based on tenant context and permissions — tools update automatically | ### Pinning a version To keep using the previous behavior, specify the version in your MCP config: ```json { "mcpServers": { "zuora-developer-mcp": { "command": "npx", "args": ["-y", "zuora-mcp@1.0.0-beta.7"], "env": { "ZUORA_BASE_URL": "{baseUrl}", "ZUORA_CLIENT_ID": "{clientId}", "ZUORA_CLIENT_SECRET": "{clientSecret}" } } } } ``` --- ## 🔐 Prerequisites * **Node.js and npm** installed on your local machine. * Valid Zuora API credentials. * An AI application that supports MCP configuration (e.g. [Cursor](https://docs.cursor.com/en/context/mcp#installing-mcp-servers), [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp), [Claude Desktop](https://modelcontextprotocol.io/quickstart/user), [Codex](https://developers.openai.com/codex/mcp)). ## ⚙️ Environment Variables ### Required * `ZUORA_BASE_URL`: Your Zuora endpoint URL. Accepts either format: * MCP endpoint: `https://apisandbox.zuora.com/mcp` * REST base URL: `https://rest.apisandbox.zuora.com` Both formats resolve to the same internal MCP endpoint. Common values: * SBX: `https://apisandbox.zuora.com/mcp` * SBX NA: `https://sandbox.na.zuora.com/mcp` * SBX EU: `https://sandbox.eu.zuora.com/mcp` * CSBX: `https://test.zuora.com/mcp` * CSBX EU: `https://test.eu.zuora.com/mcp` * CSBX AP: `https://test.ap.zuora.com/mcp` * PROD: `https://zuora.com/mcp` * PROD NA: `https://na.zuora.com/mcp` * PROD EU: `https://eu.zuora.com/mcp` * PROD AP: `https://ap.zuora.com/mcp` For backward compatibility, `BASE_URL` is also supported but deprecated. * `ZUORA_CLIENT_ID`: Your Zuora API client ID. * `ZUORA_CLIENT_SECRET`: Your Zuora API client secret. ### Optional * `ZUORA_VERSION`: Zuora API version header. * `ZUORA_ENTITY_IDS`: Entity ID(s) for Zuora Multi-Entity setups (comma-separated). * `ZUORA_ORG_IDS`: Org ID(s) for Zuora Multi-Org environments (comma-separated). * `REMOTE_MCP_TIMEOUT_MS`: Per-request timeout in milliseconds (default: `120000`). ## 🚀 Quick Start [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=zuora-developer-mcp&config=eyJlbnYiOnsiWlVPUkFfQkFTRV9VUkwiOiJ7YmFzZVVybH0iLCJaVU9SQV9DTElFTlRfSUQiOiJ7Y2xpZW50SWR9IiwiWlVPUkFfQ0xJRU5UX1NFQ1JFVCI6IntjbGllbnRTZWNyZXR9In0sImNvbW1hbmQiOiJucHggLXkgenVvcmEtbWNwIn0%3D) Add the following to your MCP config: ```json { "mcpServers": { "zuora-developer-mcp": { "command": "npx", "args": ["-y", "zuora-mcp"], "env": { "ZUORA_BASE_URL": "{baseUrl}", "ZUORA_CLIENT_ID": "{clientId}", "ZUORA_CLIENT_SECRET": "{clientSecret}" } } } } ``` For detailed setup guides, see: - [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) - [Codex](https://developers.openai.com/codex/mcp) - [Cursor](https://docs.cursor.com/context/model-context-protocol) - [Windsurf](https://docs.codeium.com/windsurf/mcp) ## 📘 Changelog ### 1.1.0 * Improved OAuth2 client credentials authentication support. * Bug fixes and enhancements. ### 1.0.0 ⚠️ Breaking * Removed approval process — all operations execute immediately. * All tools now require Zuora credentials. * Enforced tenant-level Zuora AI permissions for AI-specific operations, including write-operation blocking and tool visibility/accessibility filtering based on AI access. * Tools, resources, and prompts update automatically based on tenant context and permissions. * OAuth tokens refresh automatically. ### 1.0.0-beta.7 * Added `manage_billing_previews` tool for previewing billing before invoice generation. * Added `manage_billing_documents` tool for managing billing document PDF and email operations. * Added org scoping support via the `ZUORA_ORG_IDS` environment variable. * Renamed tools to follow plural naming convention. * Renamed `BASE_URL` to `ZUORA_BASE_URL` (`BASE_URL` still supported but deprecated). ### 1.0.0-beta.6 * Added `renew_subscriptions` tool. * Added `get_account_summary` tool. * Added entity scoping support via the `ZUORA_ENTITY_IDS` environment variable. ### 1.0.0-beta.5 * Added `cancel_subscriptions` tool. * Added `manage_revenue_reports` tool for Zuora Revenue (RevPro) report management. ### 1.0.0-beta.4 * Internal improvements. ### 1.0.0-beta.3 * Split `zuora_workflow` tool into `run_workflows` and `manage_workflows`. ### 1.0.0-beta.2 * Added `run_reports`, `manage_reports`, and `run_workflows` tools. ### 1.0.0-beta.1 * Added `query_objects`, `create_products`, `create_product_rate_plans`, `create_product_rate_plan_charges`, `create_subscriptions`. ### Previous Alpha Versions * API knowledge base, SDK upgrades, Cursor workspace rules, and telemetry improvements.