Developers MCP server

Surfboard Payments MCP server

The API reference, the webhook catalog and every integration guide, as tools an agent can call while it writes your integration. Hosted over Streamable HTTP with nothing to install, or run from npm if your client speaks stdio.

Agent instructions OpenAPI npm package

Point an agent at the hosted server

I The hosted endpoint

One URL. No install.

https://www.surfboardpayments.com/.well-known/mcp speaks the Model Context Protocol over Streamable HTTP. It is stateless and unauthenticated: POST a JSON-RPC message and the answer comes back as JSON rather than a stream. A GET returns the server card, so a client holding only the URL can find out what it has reached.

Open a session

curl -s https://www.surfboardpayments.com/.well-known/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"my-agent","version":"1.0.0"}}}'

Returns the protocol version, the server info, and the instructions the server wants an agent to follow.

Call a tool

curl -s https://www.surfboardpayments.com/.well-known/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"search_api_docs",
                 "arguments":{"query":"refund an order"}}}'

Returns the matching endpoints as markdown, each with the id to pass to read_doc.

The tools

search_api_docs
Locate API endpoints by keyword.
search_webhook_docs
Locate webhook events by keyword.
search_guides
Locate developer guides covering payment methods, SDKs, checkout flows, lifecycle, and onboarding.
read_doc
Retrieve the complete content of a documentation file.
list_api_sections
List all API sections with endpoint counts.

The same five tools whichever transport you use. The server card at /.well-known/mcp/server-card.json describes both.

II Connect your editor

Give your coding agent the docs.

The Surfboard docs run as an MCP server, so Claude Code, Codex or Cursor can read the API reference, the guides and the webhook payloads while it writes your integration. No copy-pasting from a browser tab, and no hallucinated field names. Wire it up below, or let your agent do it as part of the whole integration.

One command. Claude Code registers the server and starts it on demand.

claude mcp add surfboard-docs -- npx -y @surfboardpayments/surf-mcp

Then just ask. Claude Code will call the server whenever it needs the API reference.

Add the server to ~/.codex/config.toml.

[mcp_servers.surfboard_docs]
command = "npx"
args = ["-y", "@surfboardpayments/surf-mcp"]

Restart Codex and the Surfboard tools appear in its tool list.

Add it to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.

{
  "mcpServers": {
    "surfboard-docs": {
      "command": "npx",
      "args": ["-y", "@surfboardpayments/surf-mcp"]
    }
  }
}

Cursor picks it up on reload. Check Settings, MCP to confirm it is connected.

Commit .mcp.json at the root and every agent your team runs picks it up.

{
  "mcpServers": {
    "surfboard-docs": {
      "command": "npx",
      "args": ["-y", "@surfboardpayments/surf-mcp"]
    }
  }
}

This is the file this very website uses, so the setup is not hypothetical.

Or hand the whole job to your agent

One fetch, and your agent runs the whole integration: install the Surfboard skills, connect this server, take Demo credentials from you, write the code, then prove it against Demo with a real payment. Every command it follows is published and validated by us. Wiring up the docs is one of the steps it runs, so this page happens either way — just without you running it.

Then ask it something

Everything is also readable without MCP: llms.txt for the map, and the hosted endpoint and OpenAPI specs if you would rather call the server over HTTP than run it.

III OpenAPI

Surfboard Payments OpenAPI specifications

Two APIs answer to the Surfboard name, so there are two documents. Both are OpenAPI 3.1, both carry a unique operationId and a description on every operation, and both are served as JSON and YAML. /openapi/index.json says which is which.

Site API
Every public endpoint on this domain: the content JSON, the brand and kit endpoints, the discovery documents, this MCP server. No credentials, open CORS.
/openapi.json /openapi.yaml
Carbon payments API
The credentialed API behind orders, payments, terminals, merchants and reporting. Generated from the published reference, with an operationId, typed parameters and response schemas on every operation.
/openapi/carbon.json /openapi/carbon.yaml

The Carbon base URL is deliberately a server variable: it is issued with your credentials in the Developer Portal console and differs between accounts and between Demo and Live. Read it from configuration as SURFBOARD_API_URL rather than copying a host out of an example.

IV From the command line

Scriptable, not just clickable.

Everything above is reachable from a shell. The docs server runs from npm with one command, and the Surfboard skills install the same way, so a coding agent can set itself up without a browser.

Run the docs server from the command line

Starts the stdio server. This is what the editor configs below run for you.

Install the Surfboard skills

Ten skills: a router plus one per integration flow. Published and versioned by us.

Without a shell at all, the same corpus is plain HTTP: /llms.txt for the map, /api/ai/docs.json for the API reference, and /api/ai/guides.json for the guides. Start with /agent-instructions.md, which says which of these to reach for and in what order.