FastSpring MCP Server

Production-ready Model Context Protocol (MCP) server for the FastSpring API. Exposes FastSpring orders, subscriptions, and accounts as MCP tools for use with Claude, Cursor, and any other MCP-compatible client.

Supports two transport modes:

• STDIO — default; for local MCP clients (Claude Desktop, Cursor, MCP Inspector)
• Streamable HTTP — for remote clients, hosted deployments, and Docker

Table of Contents

1. Stack
2. Environment Variables Reference
3. Sensitive Information — How to Handle Credentials
4. Running Locally

• Prerequisites
• STDIO transport (default)
• Streamable HTTP transport

1. Running in Docker

• Prerequisites
• Docker Compose (recommended)
• Plain Docker run

1. CI/CD Deployments
2. Connecting MCP Clients

• Cursor / Claude Desktop (STDIO)
• Cursor / Claude Desktop (HTTP)
• Claude.ai (remote HTTP)

1. Testing & Inspection
2. Tools Reference
3. Logging
4. Scripts Reference

Stack

Environment Variables Reference

Required — FastSpring credentials

Credentials are created in the FastSpring dashboard: Developer Tools → APIs → Create.

Optional — FastSpring settings

Optional — Transport & HTTP server

Optional — HTTP authentication

Note: Authentication only applies to the HTTP transport. The STDIO transport is secured by the OS process model and needs no auth configuration.

Sensitive Information — How to Handle Credentials

Rule: credentials (FS_API_USERNAME, FS_API_PASSWORD, FS_COMPANY_ID) are never stored inside the container image or committed to source control. They are always injected at runtime as environment variables.

What is safe and what is not

Local development

Use a .env file — it is loaded automatically by the server at startup (via dotenv) and by Docker Compose for variable substitution:

cp .env.example .env
# Edit .env and fill in your credentials

The .env file is excluded from git and Docker builds:

• .gitignore → never committed
• .dockerignore → never copied into the image

CI/CD and production

Do not use a .env file. Inject credentials as environment variables from your platform's secret store:

GitHub Actions

env:
  FS_API_USERNAME: ${{ secrets.FS_API_USERNAME }}
  FS_API_PASSWORD: ${{ secrets.FS_API_PASSWORD }}
  FS_COMPANY_ID:   ${{ secrets.FS_COMPANY_ID }}

AWS ECS

{
  "secrets": [
    { "name": "FS_API_USERNAME", "valueFrom": "arn:aws:secretsmanager:..." },
    { "name": "FS_API_PASSWORD", "valueFrom": "arn:aws:secretsmanager:..." }
  ]
}

Kubernetes

env:
  - name: FS_API_USERNAME
    valueFrom:
      secretKeyRef:
        name: fastspring-credentials
        key: username

Render / Railway / Fly.io / Heroku — use the platform's "Environment Variables" or "Secrets" UI dashboard.

Running Locally

Prerequisites

node --version   # must be ≥ 20
npm --version

Install and build:

npm install
npm run build

Configure credentials:

cp .env.example .env
# Edit .env — set FS_API_USERNAME and FS_API_PASSWORD at minimum

STDIO transport (default)

STDIO is the standard transport for local MCP clients. The client (Cursor, Claude Desktop, MCP Inspector) spawns the server as a child process and communicates over stdin/stdout.

npm start
# or explicitly:
npm run start:stdio

The server produces no console output on startup (MCP protocol runs over stdio — any stdout/stderr would corrupt the stream). All logs go to the logs/ directory.

Streamable HTTP transport

HTTP mode starts a local web server. Use this when you want to call the server from a script, another process, or a remote MCP client.

npm run start:http

Default endpoint: http://localhost:3000/mcp

Custom port or path:

MCP_HTTP_PORT=8080 MCP_HTTP_PATH=/api/mcp npm run start:http

Verify it is running:

curl http://localhost:3000/health
# → {"status":"ok","transport":"streamable-http","mode":"stateful","sessions":0}

Stateless mode (new server instance per request — useful for scripts or one-shot callers):

MCP_HTTP_STATELESS=true npm run start:http

Test with the MCP Inspector UI (HTTP mode):

npm run test:inspector:http
# Starts the server in HTTP mode, then opens the Inspector UI pointing at it

Running in Docker

The Docker image defaults to HTTP transport (MCP_TRANSPORT=http) and binds to 0.0.0.0 so it is reachable from outside the container. Credentials are never baked into the image — they are always passed at runtime.

Persistent container (recommended) — runs in the background and restarts automatically after a machine reboot:

npm run docker:start

Stop it with npm run docker:stop. Ensure .env exists with FS_API_USERNAME and FS_API_PASSWORD (see Environment variables).

Prerequisites

You need both the Docker daemon and the Compose plugin. The easiest way to get both together is Docker Desktop.

#### Option A — Docker Desktop (recommended for Mac/Windows)

Download and install from https://www.docker.com/products/docker-desktop/

Docker Desktop bundles the Docker daemon, the docker CLI, and the docker compose plugin (v2). After installing and starting Docker Desktop:

docker --version          # Docker version 29.x or later
docker compose version    # Docker Compose version v2.x or later

#### Option B — Docker CLI + Compose plugin via Homebrew (Mac)

If you already have the Docker CLI installed via Homebrew (brew install docker) but without Docker Desktop, install the standalone Compose plugin separately:

brew install docker-compose

Then use the hyphenated docker-compose command (v1) or the :v1 npm script variants:

docker-compose --version  # docker-compose version 1.x or 2.x

How to tell which you have: Run docker compose version (with a space). If it says unknown command, you have the CLI only and need Option A or B above.

Docker Compose (recommended)

Docker Compose reads your .env file automatically for variable substitution and passes each credential as a runtime environment variable into the container. The .env file itself is never copied into the image. The Compose file sets restart: unless-stopped, so the container survives reboots when run in detached mode.

Compose v1 (Homebrew docker-compose): use npm run docker:up:v1, npm run docker:down:v1, npm run docker:logs:v1.

Verify:

curl http://localhost:3000/health

Custom port — set MCP_HTTP_PORT in your .env or shell before starting:

MCP_HTTP_PORT=8080 npm run docker:start

What Docker Compose does with your `.env`:

Docker Compose reads .env from the project directory and substitutes ${VAR} placeholders in docker-compose.yml. The result is that each variable is passed to the container as a standard environment variable. The .env file stays on your machine — it is not mounted into the container, and .dockerignore prevents it from entering the build context.

Plain Docker run

Build the image once, then run with env from a file. For a persistent container (restarts on reboot), use docker:run:env which uses --restart unless-stopped and a named container (no --rm).

Build:

npm run docker:build

Run persistent (loads .env, container survives reboot; stop with docker stop fastspring-mcp):

npm run docker:run:env

Run one-off (container removed when it stops; credentials from shell):

export FS_API_USERNAME=your_username FS_API_PASSWORD=your_password
docker run --rm --env-file .env -p 3000:3000 fastspring-mcp

CI/CD Deployments

For CI/CD pipelines, there is no .env file. Inject all variables as secrets provided by your platform.

Generic pattern:

# 1. Build the image (no secrets needed at build time)
docker build -t fastspring-mcp .

# 2. Push to a registry
docker tag fastspring-mcp registry.example.com/fastspring-mcp:latest
docker push registry.example.com/fastspring-mcp:latest

# 3. Deploy — pass secrets as environment variables at runtime
docker run -d --restart unless-stopped --name fastspring-mcp \
  -e FS_API_USERNAME="$FS_API_USERNAME" \
  -e FS_API_PASSWORD="$FS_API_PASSWORD" \
  -e FS_COMPANY_ID="$FS_COMPANY_ID" \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_PORT=3000 \
  -p 3000:3000 \
  registry.example.com/fastspring-mcp:latest

The --restart unless-stopped and --name fastspring-mcp flags make the container persistent and restart automatically after a reboot.

The server performs fail-fast validation at startup: if FS_API_USERNAME or FS_API_PASSWORD are missing, the process exits immediately with a clear error. Misconfiguration is caught at boot, not at the first API call.

Connecting MCP Clients

Cursor / Claude Desktop (STDIO)

Add to your MCP config file (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "fastspring": {
      "command": "node",
      "args": ["/absolute/path/to/fs-mcp/dist/index.js"],
      "env": {
        "FS_API_USERNAME": "your_username",
        "FS_API_PASSWORD": "your_password",
        "FS_COMPANY_ID":   "your_company_id"
      }
    }
  }
}

The client spawns the server as a subprocess. The env block passes credentials directly — no .env file required when using this approach.

Cursor / Claude Desktop (HTTP)

Start the server in HTTP mode first (locally or via Docker), then configure your client to connect by URL.

Claude Desktop only supports stdio transport natively. To connect it to an HTTP MCP server, use mcp-remote as a proxy bridge — npx fetches it automatically, no install required.

Without authentication (MCP_AUTH_ENABLED=false, default):

{
  "mcpServers": {
    "fastspring": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

With authentication (MCP_AUTH_ENABLED=true):

{
  "mcpServers": {
    "fastspring": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header",
        "Authorization:Bearer <your-api-key>"
      ]
    }
  }
}

Claude.ai (remote HTTP)

Claude.ai connects to remote MCP servers over the Streamable HTTP transport. Deploy this server (via Docker or any Node host), then add the public URL in Claude.ai's MCP server settings:

https://your-server.example.com/mcp

If authentication is enabled, include the Authorization: Bearer <key> header in your client configuration. Ensure the server is behind HTTPS (e.g. a reverse proxy such as nginx or Caddy) for production use.

Generating API keys

Use Node.js to generate a cryptographically secure random key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Add one or more keys to your .env:

MCP_AUTH_ENABLED=true
MCP_API_KEYS=a3f8c2...,b7d1e9...

The server accepts any key in the list, so different clients can use different keys and be revoked independently by removing their key and restarting.

Testing & Inspection

Unit tests

Run the full test suite with coverage (thresholds: 80 % lines/statements/functions, 75 % branches). All HTTP calls are mocked — no real FastSpring API calls are made.

npm test

Watch mode:

npm run test:watch

Type-check only (no emit):

npm run typecheck

Smoke test (no browser)

Spawns the server, sends MCP initialize and tools/list over STDIO, and prints the JSON responses. Useful for verifying the server starts correctly without a browser or UI:

npm run test:smoke

Save output for sharing or debugging:

npm run test:smoke > logs/smoke.txt 2>&1

MCP Inspector — STDIO mode

The MCP Inspector provides a browser UI to list and invoke tools. In STDIO mode it spawns the server as a child process:

npm run test:inspector
# Opens Inspector UI at http://localhost:6274

Pass credentials if you are not using a .env file:

FS_API_USERNAME=xxx FS_API_PASSWORD=yyy npm run test:inspector

MCP Inspector — HTTP mode

In HTTP mode the Inspector connects to an already-running server by URL. This command starts the server in HTTP mode in the background, waits for it to be ready, then opens the Inspector:

npm run test:inspector:http
# Opens Inspector UI connected to http://localhost:3000/mcp

Custom port:

MCP_HTTP_PORT=8080 npm run test:inspector:http

Integration test (real API)

Calls the real FastSpring API with your credentials. Requires a valid .env with credentials and optionally TEST_CUSTOMER_EMAIL:

npm run test:integration

Tools Reference

All tools return JSON. Errors include an error field, and when available statusCode and responseBody from FastSpring. All string inputs are trimmed before calling the API.

Orders

Subscriptions

Accounts

ID vs reference — avoiding 400 errors

• get_order and get_subscription use FastSpring's internal ID in the URL path. Passing a human-readable reference (e.g. VI8201014-6538-11102S) will return 400 Bad Request.
• Use find_orders_by_reference or get_subscription_by_reference when you have a reference string.
• Internal IDs are available in the FastSpring dashboard or from list tools (find_orders_by_email, list_subscriptions, etc.) which return objects containing both id and reference.
• If you get 400 on valid-looking IDs, your account may use a company-scoped base URL. Set FS_BASE_URL=https://api.fastspring.com/company/yourcompany in .env.

Logging

• Daily rotation: one file per day under FS_LOG_DIR (default logs/), e.g. logs/fastspring-mcp-2026-02-19.log. Files are retained for 14 days.
• Levels: fatal error warn info debug — set via FS_LOG_LEVEL.
• DEBUG level: logs every FastSpring API request (method, URL) and response (status, body). Enable with FS_DEBUG=true or FS_LOG_LEVEL=debug.
• Format: pretty-printed lines with timestamp, level, message, and JSON metadata. Credentials are never logged.
• Docker: the logs/ directory is mounted as a volume (./logs:/app/logs) so logs persist across container restarts.

Scripts Reference

Development

Testing

Docker

License

This project is dual-licensed.

• AGPL v3 — Default. You may use, modify, and distribute the software under the terms of the GNU Affero General Public License v3. If you run a modified version as a service over a network, you must make the corresponding source available to users of that service.
• Commercial — Use in proprietary products or services without AGPL’s source-availability obligations requires a separate commercial license. See COMMERCIAL_LICENSE.md for details.

Commercial licensing enquiries: [email protected]