---
name: sumup-mcp
description: Use the SumUp MCP server (https://mcp.sumup.com/mcp) from Cursor, Claude Code, Codex, or any MCP-capable client. Use when the user mentions SumUp MCP, needs to wire mcp.sumup.com, or wants tool-based access to SumUp APIs.
license: Apache-2.0
---

# SumUp MCP Server Guide

Use this skill when setup or usage of the SumUp MCP server is requested.

Canonical endpoint:

- `https://mcp.sumup.com/mcp`

## What this skill covers

- MCP server wiring in MCP-capable clients
- Auth handshake troubleshooting
- Prompt patterns for tool-driven SumUp API tasks
- Safe usage guardrails for production and sandbox contexts

## Choose a Setup

The SumUp plugin already carries the hosted SumUp MCP server; use it instead of adding a duplicate server. If the SumUp tools are not available, ask the user to connect the SumUp server in the plugin's Edit dialog, Connections tab, and complete the SumUp OAuth authorization in the browser when prompted.

The hosted endpoint uses OAuth access tokens issued for the MCP resource. Do not configure a SumUp API key (`sup_sk_...`) as its Bearer token. For API-key authentication or stdio-only clients, use the local `@sumup/mcp` package with Node.js 22 or later and `SUMUP_API_KEY`.

For another MCP client, consult https://developer.sumup.com/tools/llms/mcp-server/ and the client's current documentation. Use the client's actual configuration schema; field names differ between clients.

## Local Setup

For a local stdio server with API-key authentication:

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

Keep the actual key in the client's private configuration or environment. It is not a credential for the hosted OAuth endpoint.

## Prompt Patterns

- "Use the SumUp MCP tools to show my merchant profile." (Read-only verification.)
- "List my SumUp merchant checkouts from the last 24 hours."
- "Create a sandbox checkout for 12.34 EUR and return the checkout id."
- "Inspect this checkout id and summarize status transitions."
- "Show what data is needed to reconcile failed payments for this reference."

## Common Failure Modes

### Server not reachable

- Confirm exact URL and transport.
- Check client allows outbound HTTPS.
- Retry from a clean session.

### Auth loop or unauthorized

- Re-run auth handshake and ensure correct account/environment.
- For hosted connections, remove any API-key Bearer header and authenticate through OAuth. For local connections, check `SUMUP_API_KEY`.
- Confirm the token/session has required scopes.

### Tools not appearing

- Refresh/reload MCP server in client.
- Confirm server alias matches the expected name in prompts/config.

## Safety and Reliability Rules

- Never expose secrets or raw tokens in prompts or logs.
- Prefer sandbox for new workflows and regression tests.
- For payment-critical actions, verify final checkout status through deterministic reads.
- Record checkout ids/references for auditability and reconciliation.

## Required Response Contract

When answering MCP setup/use requests, include:

1. Where to connect the server: the plugin's Connections tab, or the exact configuration snippet for another client.
2. Authentication steps and where failures usually happen.
3. One verification command/prompt to confirm setup.
4. A safe first task in sandbox before production usage.