# MCP Server

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) connects AI assistants to external tools and context. The [SumUp MCP server](https://github.com/sumup/sumup-mcp) provides tools for calling SumUp APIs and resources for reading developer documentation.

For client-specific installation and login steps, start with [Set up your AI assistant](/tools/llms/setup/).

## What You Can Do

Use the server to:

- Query your merchant profile and review transactions.
- Create checkouts and inspect their status.
- Build payment workflows with [Cloud API](/terminal-payments/cloud-api/).
- Read SumUp developer documentation and the OpenAPI specification through MCP resources.

## Documentation Resources

Clients that support MCP resources can read:

| Resource | URI |
| --- | --- |
| Developer documentation index | `https://developer.sumup.com/llms.txt` |
| API OpenAPI specification | `https://developer.sumup.com/openapi.json` |

The documentation index points to guides available as Markdown. Clients without resource support can read the [documentation index](/llms.txt) and the [OpenAPI specification from the SumUp OpenAPI repository](https://raw.githubusercontent.com/sumup/sumup-openapi/refs/heads/main/openapi.json) directly.

## Authentication

| Setup | Authentication | Requirements |
| --- | --- | --- |
| Hosted server at `https://mcp.sumup.com/mcp` | Sign in with SumUp through OAuth | A client that supports Streamable HTTP and OAuth |
| Local `@sumup/mcp` process | SumUp API key in `SUMUP_API_KEY` | Node.js 22 or later and a client that supports stdio |

### Connect the Hosted Server

The client discovers the SumUp authorization server through the endpoint's protected resource metadata and asks you to authorize access in your browser. Follow the login steps for your client in the [assistant setup guide](/tools/llms/setup/#choose-your-assistant).

The hosted server accepts OAuth access tokens issued for the MCP resource. SumUp API keys such as `sup_sk_...` are used by the local server and are not valid Bearer tokens for the hosted endpoint.

The hosted server supports Streamable HTTP at `/mcp` and the legacy SSE transport at `/sse`. Use `/mcp` for new connections.

## Verify the Connection

Follow the [setup verification steps](/tools/llms/setup/#verify-the-setup) to check that tools are available and make a read-only request. Before testing payment workflows, connect a [sandbox merchant account](/online-payments/#getting-a-sandbox-merchant-account).

For example, once your sandbox connection is ready:

```text
Using my sandbox merchant, create a checkout for 12.34 EUR with a unique
reference and return its ID. Do not process a payment.
```

## Run the Local Server

Use the [local MCP CLI](https://github.com/sumup/sumup-ai/tree/main/mcp) for clients that launch stdio servers or for workflows using a [SumUp API key](/tools/authorization/api-keys/). It requires Node.js 22 or later.

To start it from your terminal:

```bash
SUMUP_API_KEY='sup_sk_...' npx -y @sumup/mcp
```

For Codex, add a local server instead of the hosted URL:

```bash
codex mcp add sumup --env SUMUP_API_KEY=sup_sk_... -- npx -y @sumup/mcp
codex mcp list
```

For clients such as Cursor or Claude Desktop that accept `mcpServers` configuration, use:

```json
{
  "mcpServers": {
    "sumup": {
      "command": "npx",
      "args": ["-y", "@sumup/mcp"],
      "env": {
        "SUMUP_API_KEY": "sup_sk_..."
      }
    }
  }
}
```

Replace the placeholder with your API key in your client's private configuration. Keep credentials out of shared project files. For Claude Desktop, this goes in `claude_desktop_config.json`.

## Troubleshooting

- **Authorization fails:** use your client's OAuth login flow for the hosted server. If you configured a `sup_sk_...` Bearer token, remove it and reconnect through OAuth. For the local server, check `SUMUP_API_KEY`.
- **Tools are missing:** restart or refresh the MCP connection and check its status in your client. After installing a Codex plugin, start a new session.
- **Duplicate tools appear:** if the SumUp plugin already configures MCP, remove the separate manual entry for the same server.
- **The server cannot connect:** check the `/mcp` URL, outbound HTTPS access, and Streamable HTTP support. The hosted server also exposes the legacy `/sse` endpoint, but new connections should use `/mcp`.

For integration guidance alongside the tools, see [Agent Skills](/tools/llms/agent-skills/) and [Set up your AI assistant](/tools/llms/setup/).