# Using the API with AI agents (MCP)

If you'd rather not write integration code yourself, you can let an AI agent — Claude, ChatGPT, Cursor, or any tool that supports the [Model Context Protocol](https://modelcontextprotocol.io) — do it for you.

The recommended way is to **connect your agent to this documentation site through the GitBook MCP**. The agent then has live, searchable access to every page you see here — the Payments and Customers references, the error catalogue, idempotency rules, test cards, the lot. When you ask the agent to do something, it pulls the relevant page first and then constructs the right request.

You don't paste any URLs or schemas into your prompts. Everything the agent needs comes from the GitBook MCP.

## Option 1 — Connect to the SwissPay docs via GitBook MCP (recommended)

GitBook publishes an MCP endpoint for this site. Adding it to your agent's MCP configuration gives the agent two tools — `searchDocumentation` and `getPage` — pointed at the SwissPay docs.

### Find your MCP endpoint

In the SwissPay GitBook (the site this documentation is published on):

1. Open **Site settings → Integrations**.
2. Enable **Model Context Protocol (MCP)**.
3. Copy the MCP endpoint URL shown there.

The URL is stable; you only do this once.

### In Claude Desktop / Claude Code

Add an entry to your Claude MCP config:

```json
{
  "mcpServers": {
    "swisspay-docs": {
      "url": "<your SwissPay GitBook MCP endpoint>"
    }
  }
}
```

Restart Claude. The new MCP server appears in the tools panel with `searchDocumentation` and `getPage`.

Now ask:

> Using the SwissPay docs, take a 29.99 CHF test payment with the Visa success card. My test key is in `$SWISSPAY_API_KEY` and the base URL is `https://staging.swisspay.ai`. Use a fresh UUID for the Idempotency-Key.

The agent:

1. Searches the SwissPay docs for "payment" and "test cards".
2. Reads the **Payments**, **Authentication**, **Idempotency**, and **Test cards** pages.
3. Constructs the curl / fetch request with the right headers, body shape, and validation rules.
4. Executes it and walks you through the response.

### In ChatGPT (with Connectors)

ChatGPT supports MCP via the Connectors interface in business and enterprise plans:

1. **Settings → Connectors → Add connector**.
2. Paste the SwissPay GitBook MCP endpoint.
3. Save.

The custom GPT can now pull from the SwissPay docs in any conversation. Combine it with a code-execution tool (or your local HTTP client) to actually call the API.

### In Cursor or other MCP-capable IDEs

Cursor, Windsurf, Zed, and other MCP-capable IDEs all accept a remote MCP server URL in the same shape:

```json
{
  "mcp": {
    "servers": {
      "swisspay-docs": {
        "url": "<your SwissPay GitBook MCP endpoint>"
      }
    }
  }
}
```

Once configured, you can ask the IDE to scaffold a client, generate test fixtures from the documented error codes, or write integration code grounded in the actual API surface — not what the model thinks the API should look like.

### What the agent can build for you

With the docs available as live context, the agent can produce:

* **Integration code in your language of choice.** "Write a Python module that creates a SwissPay payment with idempotency and proper decline handling."
* **A typed API client.** "Generate a TypeScript client based on the documented Payments and Customers endpoints."
* **Test fixtures.** "Generate request/response fixtures that hit every documented error code."
* **A self-onboarding script.** "Write a Bash script that creates a customer, charges 50 CHF, retrieves the payment, and lists my last five payments."
* **Help articles for your own product.** "Draft a one-pager for our support team explaining how the 3-D Secure challenge flow appears to the shopper, grounded in the SwissPay docs."

Because the agent reads the published docs (and not a model hallucination of an API), the code it produces matches the actual endpoint shape, field names, and validation rules.

## Option 2 — Run an MCP bridge in front of the API itself

GitBook MCP gives the agent the **docs**. If you also want the agent to call the API as **typed tools** — `swisspay.createPayment`, `swisspay.retrievePayment`, etc., with the input schema enforced by the MCP layer — run an OpenAPI-to-MCP bridge.

Two open-source options:

* [`mcp-openapi`](https://github.com/janwilmake/mcp-openapi) — generic OpenAPI → MCP bridge.
* [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) — build your own with a few lines of TypeScript.

A minimal `mcp-openapi` config for SwissPay:

```json
{
  "name": "swisspay",
  "openapi_url": "https://swisscrm.gitbook.io/swisspay/api-reference/openapi.yaml",
  "server_url": "https://staging.swisspay.ai",
  "auth": {
    "type": "bearer",
    "token_env": "SWISSPAY_API_KEY"
  }
}
```

Run it, register it as an MCP server in your client alongside `swisspay-docs`, and the agent will see tools like:

* `swisspay.createPayment`
* `swisspay.retrievePayment`
* `swisspay.listPayments`
* `swisspay.createCustomer`
* `swisspay.retrieveCustomer`
* `swisspay.listCustomers`

Each tool's input schema and example responses are picked up from the published OpenAPI spec.

Combine the two: `swisspay-docs` (read the docs) plus the OpenAPI bridge (call the API as tools). The agent has both context and capability.

## What an agent should **not** do

* **Hold your secret key in plaintext context.** Pass it through an environment variable on the MCP server side, not in the prompt.
* **Make irrevocable changes without your confirmation.** Refunds and customer deletions should require a confirmation step in the agent's instructions.

A reasonable system prompt for an agent operating against a SwissPay account:

```
Before making any POST request, summarise the request and ask for human confirmation.
Always include a fresh Idempotency-Key on POST /api/v1/payments.
Quote the Swisspay-Request-Id from any failed response.
Cite the SwissPay docs page you used.
```

## Examples

### "Write me a Stripe-to-SwissPay migration cheat sheet"

```
You: Using the SwissPay docs, write a one-page cheat sheet mapping the Stripe
     Payment Intents API to the SwissPay Payments API for our team.
Agent: (searches "Payments", "errors", "idempotency", "test cards") ... here
       is the mapping table you asked for, grounded in the SwissPay reference.
```

### "Build me a quickstart script"

```
You: Generate a Node.js script that takes a 29.99 CHF test payment, prints
     the result, and handles all documented failure codes.
Agent: (reads Errors and Payments pages) ... here's index.js with an
       exponential-backoff retry that respects the documented retry rules,
       and a switch statement covering every failure code in the catalogue.
```

### "Draft a customer-facing help article"

```
You: Using the SwissPay docs, draft an article called "What happens when a
     card is declined" for our merchants. Plain language. Include the
     decline failure codes.
Agent: (reads Errors → Decline handling) ... draft article attached.
```

## Feedback

If you'd like a SwissPay-published MCP server (covering the API as tools out of the box, without you running the bridge yourself), tell us — email <support@swisspay.ai>.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.swisspay.ai/api-reference/using-with-ai-agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.