> ## Documentation Index > Fetch the complete documentation index at: https://subscriptions-docs.getappfox.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Connect IDEs to subscription data with Model Context Protocol The Appfox Subscriptions MCP server lets store/theme/agency developers connect Cursor, Claude Code, and VS Code to subscription data through natural language. Ask your AI coding assistant to find subscriptions, list plans, or check upcoming renewals — the assistant queries your shop in real time. ## What is MCP? Model Context Protocol (MCP) is an open protocol that connects AI assistants to external data sources. Instead of copying subscription details into your IDE chat, your assistant queries Appfox directly and gets live results. The MCP server is read-only in v1 — no pause/resume/cancel operations yet. ## Use cases * Store/theme developers building custom subscription features * Agency developers auditing or debugging subscription setups * IDE-based data inspection without opening the Shopify admin For merchant-facing AI assistance directly in the Shopify admin, use [Sidekick](/sidekick) instead. For backend write operations, use the [REST API](/api/contracts). ## Requirements * **Enterprise plan** — MCP uses the same authentication and plan gate as the REST API * **Appfox API key** — Generated from the API screen in the app * **Supported IDE** — Cursor, Claude Code, or VS Code with MCP support ## Endpoint The MCP server is hosted at: ``` https://subscriptions-app-new.getappfox.com/mcp ``` It implements the **MCP Streamable HTTP** transport protocol using the official `@modelcontextprotocol/sdk`. The server runs in **stateless mode** (no session management), making it compatible with serverless/edge deployments. Both GET and POST requests are supported for MCP protocol operations. ## Configuration Add the MCP server to your IDE configuration. The server requires your `afx_live_` API key in the `Authorization` header. ### Cursor Add this to your Cursor `mcp.json` (create it if it doesn't exist): ```json theme={null} { "mcpServers": { "appfox-subscriptions": { "url": "https://subscriptions-app-new.getappfox.com/mcp", "headers": { "Authorization": "Bearer afx_live_..." } } } } ``` Replace `afx_live_...` with your actual API key. ### Claude Code Add the server in Claude Code's MCP settings: ```json theme={null} { "mcpServers": { "appfox-subscriptions": { "url": "https://subscriptions-app-new.getappfox.com/mcp", "headers": { "Authorization": "Bearer afx_live_..." } } } } ``` ### VS Code If using an MCP extension for VS Code, configure the server URL and header: ```json theme={null} { "mcp.servers": [ { "name": "appfox-subscriptions", "url": "https://subscriptions-app-new.getappfox.com/mcp", "headers": { "Authorization": "Bearer afx_live_..." } } ] } ``` ## Available tools The MCP server exposes six read-only tools: ### search\_subscriptions Search and list subscription contracts by customer name, email, status, or billing interval. **Parameters:** * `query` (string, optional) — Customer name or email to search for * `status` (string, optional) — Filter by status: `ACTIVE`, `PAUSED`, `CANCELLED`, `EXPIRED`, `FAILED` * `billingInterval` (string, optional) — Filter by interval: `MONTH`, `WEEK`, `DAY`, `YEAR` * `limit` (integer, optional) — Max results (default 10, max 20) **Example prompt:** > Find all active monthly subscriptions ### get\_subscription Get detailed information about a specific subscription contract. **Parameters:** * `id` (string, required) — Contract ID (numeric or full GID) **Example prompt:** > Show me subscription contract 123456789 ### list\_selling\_plans List available selling plans (subscription plan templates). **Parameters:** * `limit` (integer, optional) — Max results (default 10, max 20) **Example prompt:** > What subscription plans does this store offer? ### get\_selling\_plan Get details about a specific selling plan. **Parameters:** * `id` (string, required) — Selling plan group ID (numeric or full GID) **Example prompt:** > Show me details for selling plan 987654321 ### list\_failed\_billing List subscription contracts with recent billing failures. **Parameters:** * `limit` (integer, optional) — Max results (default 10, max 20) **Example prompt:** > Which subscriptions have billing issues? ### list\_upcoming\_renewals List subscription contracts with upcoming billing dates in the next 7 days. **Parameters:** * `days` (integer, optional) — Days ahead to look (default 7, max 30) * `limit` (integer, optional) — Max results (default 10, max 20) **Example prompt:** > Show me subscriptions renewing in the next 14 days ## Example workflow After configuring the MCP server in Cursor: 1. Open a Shopify theme or app project 2. Ask your assistant: *"Find active subscriptions for customers with 'Smith' in their name"* 3. The assistant calls `search_subscriptions` with `query: "Smith"` and `status: "ACTIVE"` 4. Results appear in the chat — the assistant can now reference contract IDs, billing dates, and customer details 5. Follow up: *"Show me the full details for contract 123456"* — the assistant calls `get_subscription` with that ID ## Security * Store your `afx_live_` key in a secure location (IDE keychains, secret managers) * Do not commit the key to source control * Revoke keys immediately from the API screen if compromised * Keys are server-side only — do not expose them in browser or mobile code ## Error handling The MCP server returns JSON-RPC errors for authentication and plan failures: **401 Unauthorized** — Invalid or revoked API key ```json theme={null} { "jsonrpc": "2.0", "id": 1, "error": { "code": -32000, "message": "Invalid or revoked API key" } } ``` **403 Forbidden** — Enterprise plan required ```json theme={null} { "jsonrpc": "2.0", "id": 1, "error": { "code": -32001, "message": "External API access requires the Enterprise plan" } } ``` Your IDE will typically surface these as tool call failures in the assistant's response. ## Technical Details The MCP server uses: * **Transport**: MCP Streamable HTTP (official SDK implementation) * **Mode**: Stateless (no session management, compatible with serverless) * **Protocol**: JSON-RPC 2.0 over HTTP with streaming support * **Methods**: Supports GET and POST for MCP operations * **CORS**: Enabled for browser-based IDE extensions ## Limitations * **Read-only** — No pause, resume, cancel, or create operations in v1 * **Rate limits** — Requests are not currently rate-limited per key, but abusive usage may be throttled * **Authentication** — Only API key authentication (no OAuth) in v1 * **Stateless** — No server-side session state; each request is independent ## Comparison | Feature | MCP Server | Sidekick | REST API | | ----------------------- | ------------------ | ----------------- | ------------------ | | **Use case** | IDE/dev tools | Merchant admin UI | Backend automation | | **Read subscriptions** | ✓ | ✓ | ✓ | | **Pause/resume/cancel** | ✗ (v1) | ✓ | ✓ | | **Authentication** | API key | Session token | API key | | **Plan requirement** | Enterprise | Free+ | Enterprise | | **Protocol** | MCP (JSON-RPC 2.0) | REST | REST | ## Support If you have questions or need help configuring the MCP server, email [support@getappfox.com](mailto:support@getappfox.com). ## Next steps Generate API keys for MCP and REST access Pause, resume, and cancel contracts via REST