Skip to content

MCP Integration

Demo: Node/Python MCP servers with stdio, HTTP, and SSE transports.

  • Node Server
    stdio, HTTP, SSE transports.
    Open

  • Python Server
    stdio and SSE transports.
    Open

  • Transports
    Capabilities and limits across stdio/HTTP/SSE.
    Reference

Faxbot provides MCP servers in Node and Python with identical tools: - Tools: send_fax, get_fax_status - Transports: - stdio (local desktop assistants) - HTTP (Node streamable HTTP) - SSE + OAuth2 (Node and Python)

See also: Transports

Limits and file handling - stdio: use filePath to avoid base64 limits - HTTP/SSE: JSON limit is ~16 MB for Node; REST API raw file limit is 10 MB - Allowed types: PDF, TXT

Quick Start

Node — stdio (Claude Desktop / Cursor)

When to use

Best for local desktop assistants that can spawn a process. No network exposure required.

{
  "mcpServers": {
    "faxbot": {
      "command": "node",
      "args": ["src/servers/stdio.js"],
      "cwd": "/PATH/TO/faxbot/node_mcp",
      "env": { "FAX_API_URL": "http://localhost:8080", "API_KEY": "YOUR_API_KEY" }
    }
  }
}

Node — HTTP (Streamable)

# From repo root
docker compose up -d --build api
docker compose --profile mcp up -d --build faxbot-mcp

# Requests must include MCP HTTP API key
curl -s -H "Authorization: Bearer <MCP_HTTP_API_KEY>" http://localhost:3001/mcp

Node — SSE + OAuth2 (Production)

Security

SSE requires OAuth2/JWT. Configure issuer, audience, and JWKS. Terminate TLS in front of the server.

export OAUTH_ISSUER=https://YOUR_ISSUER
export OAUTH_AUDIENCE=faxbot-mcp
export OAUTH_JWKS_URL=https://YOUR_ISSUER/.well-known/jwks.json
docker compose --profile mcp up -d --build faxbot-mcp-sse

Python — stdio

# From repo root
docker compose up -d --build api
docker compose --profile mcp up -d --build faxbot-mcp

Python — SSE + OAuth2

export OAUTH_ISSUER=https://YOUR_ISSUER
export OAUTH_AUDIENCE=faxbot-mcp
export OAUTH_JWKS_URL=https://YOUR_ISSUER/.well-known/jwks.json
docker compose --profile mcp up -d --build faxbot-mcp-sse

Tools

  • send_fax
    Parameters: to, (filePath or fileContent+fileName+fileType)

  • get_fax_status
    Parameters: jobId

Node examples 
// send_fax with local file
const job = await tools.send_fax({ to: "+15551234567", filePath: "/path/to/file.pdf" });
// get_fax_status
const status = await tools.get_fax_status({ jobId: job.id });
Python examples 
# send_fax with local file
job = tools.send_fax({ "to": "+15551234567", "filePath": "/path/to/file.pdf" })
# get_fax_status
status = tools.get_fax_status({ "jobId": job["id"] })

Transports

TransportAuthWhen to use
stdioLocal processDesktop assistants; no network exposure
HTTP (Node)MCP_HTTP_API_KEYWeb clients or cloud AI that cannot spawn processes
SSE (Node/Python)OAuth2/JWT + TLSStreaming responses with enterprise auth controls

See Transports for capabilities and limits.

Security

API Keys

Use DB‑backed keys created via POST /admin/api-keys and send as X-API-Key to the Faxbot API. For SSE, validate OAuth2 tokens using your IdP’s JWKS.

OAuth2 configuration guidance: OAuth / OIDC Setup

Limits & File Handling

  • Allowed types: PDF, TXT
  • Max file size (Faxbot API): 10 MB
  • Node JSON payloads (HTTP/SSE): ~16 MB effective
  • Prefer filePath with stdio for large files
  • Convert images (PNG/JPG) to PDF before sending

Troubleshooting

  • 401/403: invalid API key or scopes; for SSE, invalid JWT or audience
  • 415: unsupported media type; only PDF/TXT accepted
  • 413: payload too large; switch to stdio with filePath
  • SSE fails: verify JWKS URL and TLS; check OAuth setup