Stream MCP Server

An MCP server for the Stream (streampay.sa) payment platform, built with FastMCP.

Exposes 27 tools across six resource domains — payment links, customers, products, coupons, invoices, and payments — plus a read-only OpenAPI documentation resource.

Quick Start

1. Install

# Clone & install in editable mode
git clone <repo-url> stream-mcp-server && cd stream-mcp-server
pip install -e ".[dev]"

2. Configure

cp .env.example .env
# Edit .env and set your Stream API key:
#   STREAM_API_KEY=sk_live_…

Variable	Default	Description
`STREAM_API_KEY`	(required for stdio mode)	Your Stream API key
`STREAM_BASE_URL`	`https://stream-app-service.streampay.sa`	API base URL
`STREAM_TIMEOUT`	`30`	Request timeout (seconds)
`STREAM_MAX_RETRIES`	`2`	Retry count for 429 / 5xx
`HOST`	`0.0.0.0`	Remote server bind host (`stream-mcp-remote`)
`PORT`	`8000`	Remote server bind port (`stream-mcp-remote`)

3. Run

Local stdio mode (recommended)

stream-mcp

Remote HTTP mode (URL clients)

# No STREAM_API_KEY needed on the server process in remote mode
HOST=0.0.0.0 PORT=8000 stream-mcp-remote

Endpoint:

http://localhost:8000/mcp

MCP Client Configuration (Claude Desktop / Cursor / VS Code)

Use one of these two patterns in your MCP config file (claude_desktop_config.json or mcp.json).

Option A: stdio

{
  "mcpServers": {
    "stream": {
      "command": "stream-mcp",
      "env": {
        "STREAM_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Option B: remote URL (`stream-mcp-remote`)

{
  "mcpServers": {
    "stream": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key_here"
      }
    }
  }
}

Available Tools

Payment Links

Tool	Description
`create_payment_link`	Create a new checkout / payment link
`list_payment_links`	Paginated list with optional status filter
`get_payment_link`	Get a single payment link by ID
`deactivate_payment_link`	Deactivate / archive a payment link

Customers

Tool	Description
`create_customer`	Create a customer with name, email, phone, metadata
`list_customers`	Paginated list of customers
`get_customer`	Get a single customer by ID
`update_customer`	Update customer fields
`delete_customer`	Soft-delete a customer

Products

Tool	Description
`create_product`	Create a one-time or recurring product
`list_products`	List products with optional type filter
`get_product`	Get a single product by ID
`update_product`	Update product name, description, or price
`archive_product`	Archive a product

Coupons

Tool	Description
`create_coupon`	Create a fixed or percentage discount coupon
`list_coupons`	List coupons with optional status filter
`get_coupon`	Get a single coupon by ID
`deactivate_coupon`	Deactivate a coupon

Invoices

Tool	Description
`create_invoice`	Create a ZATCA-compliant invoice
`list_invoices`	List invoices with filters
`get_invoice`	Get a single invoice by ID
`send_invoice`	(Re)send an invoice via email / SMS
`void_invoice`	Void / cancel an unpaid invoice

Payments

Tool	Description
`list_payments`	List payments with filters
`get_payment`	Get payment details
`refund_payment`	Issue a full or partial refund

Resources

Resource URI	Description
`stream://docs/openapi`	Full Stream OpenAPI spec (cached, auto-refreshed)

Remote Deployment (Hosted URL)

You can deploy the MCP server as a hosted URL so users connect to it remotely.

Each user passes their own Stream API key as a Bearer token.

1. Run locally (remote mode)

# No STREAM_API_KEY needed — each user provides their own
stream-mcp-remote
# → Listening on http://0.0.0.0:8000

# Custom host/port
HOST=0.0.0.0 PORT=3000 stream-mcp-remote

2. Deploy with Docker

docker build -t stream-mcp .
docker run --rm -p 8000:8000 stream-mcp

3. How users connect (remote)

Users add this to their MCP client config:

Claude Desktop / VS Code:

{
  "mcpServers": {
    "stream": {
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_STREAM_API_KEY"
      }
    }
  }
}

Each user passes their own Stream API key as the Bearer token. The server never stores keys — they are used only for the duration of the session.

Project Structure

src/stream_mcp/
├── server.py          # FastMCP app entry-point (local + remote modes)
├── config.py          # Settings from env vars
├── client.py          # Async HTTP client (auth, retries, errors)
├── auth.py            # Bearer token middleware (remote mode)
├── helpers.py         # get_client() — resolves per-request StreamClient
├── models/            # Pydantic v2 request/response models
│   ├── payment_links.py
│   ├── customers.py
│   ├── products.py
│   ├── coupons.py
│   ├── invoices.py
│   └── payments.py
└── tools/             # FastMCP tool definitions
    ├── __init__.py    # Registers all tools
    ├── payment_links.py
    ├── customers.py
    ├── products.py
    ├── coupons.py
    ├── invoices.py
    ├── payments.py
    └── docs.py        # OpenAPI resource

Adding a new resource domain = add one file in models/, one in tools/, and one import line in tools/__init__.py.

Error Handling

All tools catch StreamAPIError and return a structured dict instead of raising:

{
  "error": true,
  "code": 422,
  "message": "Validation failed: …"
}

This ensures the LLM agent always receives a usable response.

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

License

MIT

Stream