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

Variable	Required	Description
PRIVACY_API_KEY	✅ Yes	Your Privacy.com API key from account settings
MCP_API_KEY	✅ Yes	Protects all endpoints — generate with secrets.token_hex(32)
PRIVACY_SANDBOX	No	true to target sandbox.privacy.com instead of production (default: false)
PORT	No	Port to listen on (default: 8001)

---

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.

Parameter	Type	Description
begin	YYYY-MM-DD	Filter cards created on or after this date
end	YYYY-MM-DD	Filter cards created on or before this date
page	integer	Page number (1-indexed)
page_size	integer	Results per page (default 50, max 50)

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"
}

Field	Required	Description
type	✅ Yes	SINGLE_USE, MERCHANT_LOCKED, UNLOCKED, DIGITAL_WALLET, or PHYSICAL
memo	No	Friendly card label
spend_limit	No	Integer cents (e.g., 1000 = $10.00)
spend_limit_duration	No	TRANSACTION, MONTHLY, ANNUALLY, or FOREVER
state	No	OPEN or PAUSED
funding_token	No	Funding source token

---

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.

Parameter	Type	Description
card_token	string	Filter to one card
result	string	APPROVED or DECLINED
begin	YYYY-MM-DD	Filter on or after date
end	YYYY-MM-DD	Filter on or before date
page	integer	Page number (1-indexed)
page_size	integer	Results per page (default 50, max 50)

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.

Parameter	Type	Default	Description
begin	YYYY-MM-DD	—	Filter cards created on or after this date
end	YYYY-MM-DD	—	Filter cards created on or before this date
page	integer	1	Page number (1-indexed)
page_size	integer	50	Results per page (max 50)

---

get_card

Return details for one virtual card by token.

Parameter	Type	Description
card_token	string	The Privacy.com card token

---

create_card

Create a new virtual card.

Parameter	Type	Required	Description
type	string	✅ Yes	SINGLE_USE, MERCHANT_LOCKED, UNLOCKED, DIGITAL_WALLET, or PHYSICAL
memo	string	No	Friendly card label
spend_limit	integer	No	Integer cents (e.g., 1000 = $10.00)
spend_limit_duration	string	No	TRANSACTION, MONTHLY, ANNUALLY, or FOREVER
state	string	No	OPEN or PAUSED
funding_token	string	No	Funding source token

---

update_card

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

Parameter	Type	Description
card_token	string	The card to update (required)
state	string	OPEN to resume, PAUSED to pause, CLOSED to permanently close
memo	string	Updated card label
spend_limit	integer	New limit in integer cents
spend_limit_duration	string	TRANSACTION, MONTHLY, ANNUALLY, or FOREVER

---

list_transactions

Return transactions with optional filters.

Parameter	Type	Description
card_token	string	Filter to one card
result	string	APPROVED or DECLINED
begin	YYYY-MM-DD	Filter on or after date
end	YYYY-MM-DD	Filter on or before date
page	integer	Page number (1-indexed)
page_size	integer	Results per page (default 50, max 50)

---

list_funding_sources

Return all linked funding sources.

No parameters.