MCP Server

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 instead. For backend write operations, use the REST API.

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):

{
  "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:

{
  "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:

{
  "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:

Open a Shopify theme or app project
Ask your assistant: “Find active subscriptions for customers with ‘Smith’ in their name”
The assistant calls search_subscriptions with query: "Smith" and status: "ACTIVE"
Results appear in the chat — the assistant can now reference contract IDs, billing dates, and customer details
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

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Invalid or revoked API key"
  }
}

403 Forbidden — Enterprise plan required

{
  "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.

Getting started

Merchant dashboard

Storefront

Settings

API Reference

What is MCP?

Use cases

Requirements

Endpoint

Configuration

Cursor

Claude Code

VS Code

Available tools

search_subscriptions

get_subscription

list_selling_plans

get_selling_plan

list_failed_billing

list_upcoming_renewals

Example workflow

Security

Error handling

Technical Details

Limitations

Comparison

Support

Next steps

Authentication

REST API

​What is MCP?

​Use cases

​Requirements

​Endpoint

​Configuration

​Cursor

​Claude Code

​VS Code

​Available tools

​search_subscriptions

​get_subscription

​list_selling_plans

​get_selling_plan

​list_failed_billing

​list_upcoming_renewals

​Example workflow

​Security

​Error handling

​Technical Details

​Limitations

​Comparison

​Support

​Next steps

Authentication

REST API

What is MCP?

Use cases

Requirements

Endpoint

Configuration

Cursor

Claude Code

VS Code

Available tools

search_subscriptions

get_subscription

list_selling_plans

get_selling_plan

list_failed_billing

list_upcoming_renewals

Example workflow

Security

Error handling

Technical Details

Limitations

Comparison

Support

Next steps