Privacy.com MCP Server

A portable Docker-based server that exposes Privacy.com virtual card and transaction data via two protocols simultaneously:

• /mcp — FastMCP streamable-HTTP for AI assistants that support the MCP protocol (Claude Desktop, etc.)

• /api/* — Plain REST endpoints for automation tools like n8n, Zapier, or custom scripts

• /health — Unauthenticated health check

Getting Started

Step 1 — Prerequisites

• Docker and Docker Compose installed

• A Privacy.com account with developer access

Step 2 — Get your Privacy API key

Get your API key from Privacy.com Account Settings.

Step 3 — Generate your MCP API key

This key protects all /mcp and /api/* endpoints. Generate one now and keep it handy:

python -c "import secrets; print(secrets.token_hex(32))"

Copy the output — you'll use it as MCP_API_KEY in the next step.

Step 4 — Configure environment

Copy .env.example to .env and fill it in:

PRIVACY_API_KEY=your-privacy-api-key-here
MCP_API_KEY=your-generated-key-here
PRIVACY_SANDBOX=false
PORT=8001

For Coolify, set these values in Coolify Secrets instead of committing a real .env file.

Step 5 — Start the server

docker compose up -d

Step 6 — Verify it's working

# Health check (no auth needed)
curl http://localhost:8001/health

# Fetch your cards (replace with your MCP_API_KEY)
curl -H "Authorization: Bearer your-generated-key-here" http://localhost:8001/api/cards

You should see {"status": "ok", "sandbox": false} and a JSON list of your cards. If you do, you're good to go.

Environment Variables

Coolify Deployment

1. Create a new application in Coolify using this repository.

2. Deploy using Docker Compose.

3. Set environment variables in Coolify Secrets:

   • PRIVACY_API_KEY

   • MCP_API_KEY

   • PRIVACY_SANDBOX (false for production, true for sandbox)

   • PORT (optional, defaults to 8001)

4. Deploy and verify https://<your-domain>/health returns {"status": "ok"}.

Claude Desktop MCP Entry

"privacy-com": {
  "command": "uvx",
  "args": ["mcp-proxy", "--transport", "streamablehttp", "http://localhost:8001/mcp"],
  "env": { "API_ACCESS_TOKEN": "YOUR_MCP_API_KEY" }
}

REST API Endpoints

All endpoints require: Authorization: Bearer {MCP_API_KEY} except /health.

GET /health

Unauthenticated health check.

{ "status": "ok", "sandbox": false }

GET /api/cards

Return all virtual cards on the account with optional filtering.

Example:

curl -H "Authorization: Bearer YOUR_MCP_API_KEY" "http://localhost:8001/api/cards?page=1&page_size=25"

GET /api/cards/{card_token}

Return details for a single card.

Path parameter: card_token — the Privacy.com card token

Example:

curl -H "Authorization: Bearer YOUR_MCP_API_KEY" "http://localhost:8001/api/cards/crd_123"

POST /api/cards

Create a new virtual card.

JSON body:

{
  "type": "SINGLE_USE",
  "memo": "Test card",
  "spend_limit": 1000,
  "spend_limit_duration": "FOREVER",
  "state": "OPEN",
  "funding_token": "fsrc_123"
}

PATCH /api/cards/{card_token}

Update a card's state, memo, or spend limits.

Path parameter: card_token — the Privacy.com card token

JSON body (all fields optional):

{
  "state": "PAUSED",
  "memo": "Paused for testing"
}

GET /api/transactions

Return transactions across all cards or for a specific card.

Example:

curl -H "Authorization: Bearer YOUR_MCP_API_KEY" "http://localhost:8001/api/transactions?result=APPROVED&page=1&page_size=50"

GET /api/funding_sources

Return all linked funding sources.

Example:

curl -H "Authorization: Bearer YOUR_MCP_API_KEY" "http://localhost:8001/api/funding_sources"

MCP Tools

list_cards

Return all virtual cards with optional date and pagination filters.

get_card

Return details for one virtual card by token.

create_card

Create a new virtual card.

update_card

Update a card's state, memo, or spend limits.

list_transactions

Return transactions with optional filters.

list_funding_sources

Return all linked funding sources.

No parameters.