MCP Integration

Overview

EmbiPay exposes fleet authority and economic operations through an MCP-compatible API. API keys are scoped to a single organization: each key can only access fleets that belong to that organization. Keys are created in the dashboard per org, with a configurable allowlist of tools.

Getting an API key

Sign in to the dashboard → Organizations → select your organization → MCP keys (or use Admin → MCP keys with the org selected). Create a key and choose which tools it can call. The plaintext key is shown only once; store it securely.

MCP server endpoint

https://mcp.embipay.com/mcp

Your MCP client or server calls this endpoint with your API key. The server validates the key and routes requests to EmbiPay fleet and economic APIs.

Key validation (Dashboard API)

To validate a key and get its allowed tools and organization scope, call the Dashboard API:

POST /api/mcp/validate-key (body: { "api_key": "<your_key>" })

Response (200): { "success": true, "allowed_tools": [...], "organization_id": "UUID", "key_id": "UUID" }. Use organization_id to ensure the key only accesses resources in that org. Revoked keys return 401.

Authentication

Use header: X-API-Key: <your_key>

When calling Dashboard APIs directly (e.g. fleet list, approve-overage), the same header is used. The key is never returned in responses; only allowed_tools, organization_id, and key_id are exposed via validate-key.

Example request

curl -X POST https://mcp.embipay.com/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "tool": "get_fleet_status",
    "input": { "fleet_id": "UUID" }
  }'

Available tools

• get_fleet_status — Fleet status and summary
• request_wallet_increase — Request a balance increase (may create overage request)
• request_reallocation — Move balance between wallets (same fleet or both non-fleet)
• approve_overage — Approve a pending overage request
• get_fleet_policies — Fleet policy and template info

Each key is created with a subset of these tools; only allowed tools can be invoked.

Organization scope and security

• Cross-org: A key cannot access fleets or resources in another organization. Requests for another org return 403.
• Audit: Actions performed with an MCP key are recorded in the organization audit log with actor_type: mcp_key and the key id.
• Revocation: Keys can be revoked in the dashboard; revoked keys are rejected immediately.

Rate limiting

Default: 60 requests per minute per API key (configurable via RATE_LIMIT_PER_MINUTE). Exceeding returns HTTP 429 with Retry-After.