FastSpring MCP Server

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

| Concern | Choice | |---|---| | Runtime | Node.js 22 (≥ 20 required) | | Language | TypeScript — strict mode | | MCP SDK | @modelcontextprotocol/sdk v1.26+ | | HTTP transport | StreamableHTTPServerTransport (MCP spec) | | HTTP client | Axios (Basic auth + interceptors) | | Testing | Vitest — mocked HTTP, 80 %+ coverage | | Logging | Winston — daily rotation, structured JSON | | Container | Docker / Docker Compose |

---

Environment Variables Reference

Required — FastSpring credentials

| Variable | Description | |---|---| | FS_API_USERNAME | FastSpring API username | | FS_API_PASSWORD | FastSpring API password |

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

Optional — FastSpring settings

| Variable | Default | Description | |---|---|---| | FS_COMPANY_ID | — | Classic (legacy) API company ID. Required only for order-reference lookups via find_orders_by_reference / get_order_by_reference. | | FS_BASE_URL | https://api.fastspring.com | Override if your account uses a company-scoped base URL. | | FS_DEBUG | false | Set to true to log every API request and response body. | | FS_LOG_LEVEL | debug | Log verbosity: debug info warn error fatal. | | FS_LOG_DIR | logs | Directory for daily log files. |

Optional — Transport & HTTP server

| Variable | Default | Description | |---|---|---| | MCP_TRANSPORT | stdio | Transport mode: stdio or http. | | MCP_HTTP_PORT | 3000 | Port the HTTP server listens on. | | MCP_HTTP_HOST | 0.0.0.0 | Interface to bind to (0.0.0.0 = all interfaces). | | MCP_HTTP_PATH | /mcp | URL path for the MCP endpoint. | | MCP_HTTP_STATELESS | false | true = create a new server per request (no session tracking). Suitable for serverless/ephemeral callers. |

Optional — HTTP authentication

| Variable | Default | Description | |---|---|---| | MCP_AUTH_ENABLED | false | Set to true to require Bearer token auth on all MCP endpoints. GET /health is always exempt. | | MCP_API_KEYS | — | Comma-separated list of valid API keys. Required when MCP_AUTH_ENABLED=true. Any single key grants full access. |

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

| Location | Safe? | Notes | |---|---|---| | .env file on your local machine | ✅ | Never committed (.gitignore), never copied into the image (.dockerignore) | | Baked into Dockerfile via ENV | ❌ | Would be visible in every layer of the image | | Committed to git | ❌ | Permanent, hard to rotate | | Docker image layers | ❌ | docker history / docker inspect exposes them | | Runtime environment variable (-e, env:) | ✅ | The correct approach for all environments |

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 ``yaml env: FS_API_USERNAME: ${{ secrets.FS_API_USERNAME }} FS_API_PASSWORD: ${{ secrets.FS_API_PASSWORD }} FS_COMPANY_ID: ${{ secrets.FS_COMPANY_ID }} ``

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

Kubernetes ```yaml 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.

| Action | Command | |--------|--------| | Start (persistent, restarts on reboot) | npm run docker:start or docker compose up -d --build | | Start (foreground, see logs in terminal) | npm run docker:up or docker compose up | | Stop | npm run docker:stop or npm run docker:down | | Logs | npm run docker:logs |

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): ``json { "mcpServers": { "fastspring": { "command": "npx", "args": [ "mcp-remote", "http://localhost:3000/mcp" ] } } } ``

With authentication (MCP_AUTH_ENABLED=true): ``json { "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

| Tool | Description | Inputs | |---|---|---| | get_order | Fetch a single order by internal FastSpring order ID. | orderId (string) | | find_orders_by_email | List all orders for a customer by email. | email (string) | | find_orders_by_reference | Look up orders by reference (e.g. VI8201014-6538-11102S). | reference (string) | | get_order_by_reference | Fetch full order detail by reference via the Classic API. | reference (string) |

Subscriptions

| Tool | Description | Inputs | |---|---|---| | get_subscription | Fetch a subscription by internal subscription ID. | subscriptionId (string) | | get_subscription_by_reference | Look up a subscription by reference. | reference (string) | | list_subscriptions | List subscriptions with optional filters. | status (optional), product (optional), email (optional) | | get_subscription_entries | Get line items for a subscription. | subscriptionId (string) |

Accounts

| Tool | Description | Inputs | |---|---|---| | get_account | Fetch a customer account by ID. | accountId (string) | | find_account_by_email | Look up an account by customer email. | email (string) | | get_account_orders | Get all orders for an account. | accountId (string) |

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

| Script | Description | |---|---| | npm run build | Compile TypeScript → dist/ | | npm start | Start server in STDIO mode (default) | | npm run start:stdio | Start server explicitly in STDIO mode | | npm run start:http | Start server in Streamable HTTP mode (port 3000) | | npm run typecheck | Type-check without emitting | | npm run lint | ESLint on src/ |

Testing

| Script | Description | |---|---| | npm test | Vitest unit tests with coverage | | npm run test:watch | Vitest in watch mode | | npm run test:smoke | Smoke test over STDIO — no browser required | | npm run test:integration | Integration test against real FastSpring API | | npm run test:inspector | MCP Inspector UI — STDIO mode | | npm run test:inspector:http | MCP Inspector UI — HTTP mode (starts server + opens Inspector) |

Docker

| Script | Description | |---|---| | npm run docker:start | Start persistent container (detached; restarts on reboot) — recommended | | npm run docker:stop | Stop and remove containers (Compose) | | npm run docker:build | Build the Docker image only | | npm run docker:run | Same as docker:start (Compose up -d) | | npm run docker:up | Start in foreground (logs in terminal; Ctrl+C stops container) | | npm run docker:down | Same as docker:stop | | npm run docker:logs | Tail container logs (Compose v2) | | npm run docker:run:env | Plain docker run with .env, persistent (--restart unless-stopped) | | npm run docker:up:v1 / docker:down:v1 / docker:logs:v1 | Compose v1 (docker-compose) |

---

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: help@gotmo.co.uk