API Reference

Introduction

The Meridian Cards API lets you create and manage virtual Visa cards programmatically — either through your AI agent via the MCP endpoint, or directly via the REST API from your application or dashboard.

Base URL

Authentication

All requests must be authenticated. Two methods are supported:

• Bearer token (OAuth 2.1 with PKCE) — the primary authentication method. Obtain tokens via the magic-link flow at /auth/magic-link and /auth/verify. Include in requests as Authorization: Bearer <token>.
• API key — coming soon. Will allow direct programmatic access without the OAuth flow.

Response Format

All API responses are JSON. The Content-Type header is always application/json. MCP tool responses follow the JSON-RPC 2.0 format used by the Model Context Protocol.

Rate Limits

Exceeding rate limits returns 429 Too Many Requests. Implement exponential back-off in your clients.

MCP Protocol

Meridian Cards exposes a Model Context Protocol (MCP) endpoint that allows AI agents — including Claude Desktop, Cursor, and any other MCP-compatible client — to create and manage virtual cards on your behalf.

Endpoint

This is a standard MCP-over-HTTP endpoint. You do not call it directly — your AI agent does. Simply add the URL to your agent's MCP server configuration.

Setup

To connect your AI agent, add the following to your MCP configuration:

// Claude Desktop config (claude_desktop_config.json)
{
  "mcpServers": {
    "meridian": {
      "url": "https://mcp.themeridian.cards/mcp",
      "type": "http"
    }
  }
}

For a full step-by-step walkthrough, see the setup tutorial on the main page. Authentication is handled via the browser-based OAuth 2.1 + PKCE flow the first time you connect.

Protocol Details

The MCP endpoint implements the Model Context Protocol specification. Requests and responses use JSON-RPC 2.0 framing. All tool operations are user-scoped: the server derives your identity from the OAuth token in the session and only operates on cards and data that belong to your account.

Available MCP Tools

The following tools are registered on the MCP server. Your AI agent can call them by name. All monetary amounts are in cents (e.g. 5000 = €50.00).

{
  "amount": 5000,
  "currency": "eur",
  "description": "OpenAI API key"
}

{
  "id": "ic_xxx",
  "last4": "7291",
  "brand": "Visa",
  "status": "active",
  "currency": "eur",
  "spending_limit_cents": 5000,
  "exp_month": 3,
  "exp_year": 2029
}

[
  {
    "available_cents": 150000,
    "currency": "eur"
  }
]

[
  {
    "id": "ic_xxx",
    "last4": "7291",
    "brand": "Visa",
    "status": "active",
    "currency": "eur",
    "spending_limit_cents": 5000,
    "description": "OpenAI API key",
    "created_at": "2026-03-29T14:00:00Z"
  }
]

{
  "id": "ic_xxx",
  "last4": "7291",
  "number": "4242 4242 4242 7291",
  "cvc": "123",
  "exp_month": 3,
  "exp_year": 2029,
  "status": "active"
}

{
  "id": "ic_xxx",
  "last4": "7291",
  "status": "canceled",
  "message": "Card ending in 7291 has been canceled."
}

{
  "id": "ic_xxx",
  "last4": "7291",
  "status": "active",
  "spending_limit_cents": 10000,
  "currency": "eur"
}

REST API (Dashboard)

The REST API powers the Meridian Cards dashboard and is available for direct integration. All endpoints require a valid Bearer token obtained via the magic-link authentication flow. Pass it in every request:

Authorization: Bearer <your_access_token>

Access tokens expire after 1 hour. Use the refresh endpoint to obtain a new one without re-authenticating.

Webhooks

Meridian Cards uses Stripe webhooks to stay in sync with card and billing events. If you are building on top of the platform, these are the events you should be aware of.

Stripe Webhook Endpoint

Configure the following URL in your Stripe dashboard as a webhook endpoint:

Handled Events

The following Stripe event types are processed by Meridian Cards:

Error Handling

Meridian Cards uses standard HTTP status codes. Errors always include a JSON body with a human-readable message. MCP tool errors additionally follow the JSON-RPC 2.0 error format.

HTTP Status Codes

REST Error Format

{
  "error": "Card not found"
}

MCP Error Format

MCP tool errors follow the JSON-RPC 2.0 format, wrapped in the MCP content block:

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\": true, \"message\": \"No such card\", \"code\": \"resource_missing\", \"http_status\": 404}"
    }
  ],
  "isError": true
}

Your AI agent will surface the message field in its response. The code and http_status fields are available for programmatic handling if you build custom MCP client logic.