From 28e5fa9bed84dbb6c64d5b2abe08fb01d73bec0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Dzivjak?= Date: Wed, 7 Oct 2026 23:35:41 +0200 Subject: [PATCH 1/2] feat(docs): improve llms / MCP docs --- src/content/docs/tools/llms/agent-skills.mdx | 4 +- src/content/docs/tools/llms/index.mdx | 23 ++- src/content/docs/tools/llms/mcp-server.mdx | 172 ++++++++++++++++--- src/content/docs/tools/llms/plugins.mdx | 138 +++++++++++---- 4 files changed, 278 insertions(+), 59 deletions(-) diff --git a/src/content/docs/tools/llms/agent-skills.mdx b/src/content/docs/tools/llms/agent-skills.mdx index 45ca7d4a..a850d4fb 100644 --- a/src/content/docs/tools/llms/agent-skills.mdx +++ b/src/content/docs/tools/llms/agent-skills.mdx @@ -9,6 +9,8 @@ sidebar: ## Install Skills +For assistants that support SumUp's packaged integrations, [install the plugin](/tools/llms/plugins/) to get both skills and MCP configuration. Use the instructions below to install skills on their own; this does not configure an MCP connection or require SumUp credentials. + If your assistant supports standard Agent Skills folders, install the SumUp skills with: ```bash @@ -25,8 +27,6 @@ You can also clone the repository and copy the skill folders into your assistant | OpenAI Codex | `~/.codex/skills/` | | Pi | `~/.pi/agent/skills/` | -For packaged editor and assistant integrations, see [Plugins](/tools/llms/plugins/). - ## Discover Skills Agents and tools that support the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) can discover the SumUp skills from: diff --git a/src/content/docs/tools/llms/index.mdx b/src/content/docs/tools/llms/index.mdx index 7349947f..fbcf3616 100644 --- a/src/content/docs/tools/llms/index.mdx +++ b/src/content/docs/tools/llms/index.mdx @@ -1,11 +1,30 @@ --- title: Overview -description: Use LLMs to guide you through developing with SumUp SDKs. +description: Set up AI coding assistants with SumUp plugins, skills, and MCP tools. sidebar: order: 50 --- -You can use large language models (LLMs) to assist in the building of SumUp integrations. We provide a set of tools and best practices if you use LLMs during development. +Use your AI assistant to build SumUp payment integrations, troubleshoot checkout flows, or query your merchant account. SumUp provides integration guidance through Agent Skills and API access through the Model Context Protocol (MCP). + +## Get Started + +Choose the setup that fits your workflow: + +| Your workflow | Start with | +| --- | --- | +| Build integrations in an AI coding assistant | [Install the SumUp plugin](/tools/llms/plugins/) for your assistant to get skills and MCP configuration. | +| Connect an assistant directly to your SumUp account | [Set up the hosted MCP server](/tools/llms/mcp-server/) and sign in with SumUp. | +| Add integration guidance to an assistant that supports skills | [Install Agent Skills](/tools/llms/agent-skills/). Skills work without connecting an account. | +| Build your own agentic application | [Use the Agent Toolkit](/tools/llms/agent-toolkit/) to add SumUp API tools to your application. | + +For example, after installing the plugin, ask your assistant: + +- "Help me choose between SumUp Hosted Checkout and the Payment Widget." +- "Implement a SumUp Payment Widget checkout with server-side checkout creation." +- "Use the SumUp MCP tools to show my merchant profile." + +The first two prompts use integration guidance. Account queries require an authenticated MCP connection. ## Plain Text Docs diff --git a/src/content/docs/tools/llms/mcp-server.mdx b/src/content/docs/tools/llms/mcp-server.mdx index 10ff5452..3722e110 100644 --- a/src/content/docs/tools/llms/mcp-server.mdx +++ b/src/content/docs/tools/llms/mcp-server.mdx @@ -1,57 +1,170 @@ --- title: MCP Server -description: Connect MCP-compatible clients and assistants to SumUp APIs and tools. +description: Connect Codex, Claude Code, Cursor, Gemini CLI, and other MCP clients to SumUp. sidebar: order: 53 --- -[MCP](https://modelcontextprotocol.io/introduction) is an open protocol that standardizes how applications provide context and tools to LLMs. SumUp provides a [managed MCP server](https://github.com/sumup/sumup-mcp) for AI-powered code editors such as Cursor and general-purpose clients such as Claude Desktop. +import { Tabs, TabItem } from '@astrojs/starlight/components'; -The MCP server gives AI agents tools for calling the SumUp API. It also exposes the SumUp developer documentation index and OpenAPI specification as resources. +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 the developer documentation index and OpenAPI specification. -SumUp runs a managed MCP server at [https://mcp.sumup.com/mcp](https://mcp.sumup.com/mcp). This endpoint allows your MCP client to interact with SumUp APIs to manage your account, create checkouts, or process payments using [Cloud API](/terminal-payments/cloud-api). The server supports Streamable HTTP[^streamable_http] via `/mcp` and the deprecated SSE transport via `/sse`. +Use it to query your merchant profile, inspect checkout status, review transactions, or build payment workflows with [Cloud API](/terminal-payments/cloud-api/). -## Hosted MCP (managed) +## Choose a Setup -If your MCP client supports Streamable HTTP and OAuth, connect it directly to `https://mcp.sumup.com/mcp`. The client can discover the SumUp authorization server from the endpoint's protected resource metadata and ask you to authorize access. +If you use a supported coding assistant, [install the SumUp plugin](/tools/llms/plugins/) to get both integration skills and MCP configuration. If you have already installed the plugin, authorize its bundled server and continue to [verify the connection](#verify-the-connection). -The hosted server accepts OAuth access tokens issued for the MCP resource. Do not send a SumUp API key such as `sup_sk_...` as its Bearer token. +For a direct connection, choose between: -## CLI +| 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 | -The [local MCP CLI](https://github.com/sumup/sumup-ai/tree/main/mcp) requires Node.js 22 or later and uses a SumUp API key. Run it with: +## Connect the Hosted Server -```sh -SUMUP_API_KEY='sup_sk_MvxmLOl0...' npx -y @sumup/mcp +Add `https://mcp.sumup.com/mcp` to your client, then authorize access in your browser. The client discovers the SumUp authorization server through the endpoint's protected resource metadata. + +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. + + + + +Run these commands in your terminal: + +```bash +codex mcp add sumup --url https://mcp.sumup.com/mcp +codex mcp login sumup +codex mcp list ``` -The local MCP server reads the API key from the `SUMUP_API_KEY` environment variable. +Complete the browser login. In a Codex session, use `/mcp` to check the active tools. -## [Cursor](https://www.cursor.com/) +Alternatively, add this entry to `~/.codex/config.toml`, then run `codex mcp login sumup`: -1. Go to `Cursor Settings` > `MCP` -2. Click `+ Add new Global MCP Server` -3. Add the following configuration to your global `.cursor/mcp.json` file. +```toml +[mcp_servers.sumup] +url = "https://mcp.sumup.com/mcp" +``` + +The Codex CLI, ChatGPT desktop app, and Codex IDE extension share this MCP configuration on the same host. See the [OpenAI MCP documentation](https://developers.openai.com/codex/mcp). -See the [Cursor documentation](https://docs.cursor.com/context/model-context-protocol) for more details. You can also add this to your project-specific Cursor configuration (supported in Cursor 0.46+). + + + +Add the server from your terminal: + +```bash +claude mcp add --transport http --scope user sumup https://mcp.sumup.com/mcp +claude mcp list +``` + +Open Claude Code, run `/mcp`, and select the SumUp server to authenticate in your browser. The `user` scope makes the connection available across your projects. + +See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp). + + + + +Add this entry to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one project. Merge it with any existing servers: ```json { "mcpServers": { "sumup": { - "command": "npx", - "args": ["-y", "@sumup/mcp"], - "env": { - "SUMUP_API_KEY": "sup_sk_..." - } + "url": "https://mcp.sumup.com/mcp" } } } ``` -## [Claude](https://claude.ai) +Open Cursor's MCP settings, connect the SumUp server, and complete authorization in your browser. Check that its tools are available in Agent. + +See the [Cursor MCP documentation](https://cursor.com/docs/context/mcp). + + + + +Add the server from your terminal: + +```bash +gemini mcp add --transport http --scope user sumup https://mcp.sumup.com/mcp +gemini mcp list +``` -Add the following to your `claude_desktop_config.json` file. See the [Claude Desktop documentation](https://modelcontextprotocol.io/quickstart/user) for more details. +Start Gemini CLI and run `/mcp auth sumup` to sign in through your browser. Use `/mcp` to check the server and its tools. + +See the [Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/). + + + + +For GitHub Copilot, add this configuration to `.vscode/mcp.json` in your workspace. Merge it with any existing servers: + +```json +{ + "servers": { + "sumup": { + "type": "http", + "url": "https://mcp.sumup.com/mcp" + } + } +} +``` + +Run **MCP: List Servers** from the command palette, start SumUp, and complete authorization when prompted. Its tools are then available in agent chat. + +See the [VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers). + + + + +For a Claude plan that supports custom connectors: + +1. Open **Customize > Connectors**. +2. Choose **Add**, then **Add custom connector**. +3. Enter **SumUp** as the name and `https://mcp.sumup.com/mcp` as the URL. +4. Complete the SumUp authorization flow and enable the connector in your conversation. + +On Team and Enterprise plans, an owner must add the connector before members can connect it. See the [Claude custom connector documentation](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). + + + + +## Verify the Connection + +Confirm that your client's MCP tool list includes SumUp, then try a read-only prompt: + +```text +Use the SumUp MCP tools to show my merchant profile. +``` + +To test a payment workflow, first connect a [sandbox merchant account](/online-payments/#getting-a-sandbox-merchant-account). For example: + +```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 { @@ -67,6 +180,13 @@ Add the following to your `claude_desktop_config.json` file. See the [Claude Des } ``` -The code editor agent automatically detects available tools and calls the relevant tool when you ask related questions. +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`. -[^streamable_http]: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http +For integration guidance alongside the tools, see [Agent Skills](/tools/llms/agent-skills/) and [Plugins](/tools/llms/plugins/). diff --git a/src/content/docs/tools/llms/plugins.mdx b/src/content/docs/tools/llms/plugins.mdx index 87c97c04..ecce851f 100644 --- a/src/content/docs/tools/llms/plugins.mdx +++ b/src/content/docs/tools/llms/plugins.mdx @@ -1,63 +1,143 @@ --- title: Plugins -description: Install SumUp plugins, extensions, and powers for AI coding assistants. +description: Set up SumUp skills and MCP tools in Codex, Claude Code, Cursor, Gemini CLI, and Kiro. sidebar: order: 52 --- -SumUp publishes packaged integrations for AI coding assistants in the [`sumup/sumup-skills`](https://github.com/sumup/sumup-skills) repository. These packages include SumUp skill instructions and, where supported by the host application, SumUp MCP configuration. +import { Tabs, TabItem } from '@astrojs/starlight/components'; -Use the repository URL when an application asks for a GitHub source: +The [SumUp plugin](https://github.com/sumup/sumup-skills) bundles integration skills with configuration for the hosted MCP server at `https://mcp.sumup.com/mcp`. Install the package for your assistant, then sign in with SumUp when prompted to use account tools. -```txt -https://github.com/sumup/sumup-skills -``` +Skills provide guidance for implementing, testing, upgrading, and debugging payment integrations. MCP tools let your assistant query your merchant account and call SumUp APIs. You can use the skills before connecting an account. + +## Install the Plugin -## Claude Code + + -Install the SumUp plugin from the Claude Code plugin marketplace: +Run these commands in your terminal: ```bash -/plugin marketplace add sumup/sumup-skills -/plugin install sumup@sumup +codex plugin marketplace add sumup/sumup-skills +codex plugin add sumup@sumup +codex plugin list ``` -## Cursor +Start a new Codex session to load the skills and tools. Complete the SumUp authorization flow when prompted. -Install from the Cursor Marketplace, or add it manually in: +Plugins are supported in the Codex CLI and Codex in the ChatGPT desktop app. For the Codex IDE extension, [install skills](/tools/llms/agent-skills/) and [configure MCP directly](/tools/llms/mcp-server/#connect-the-hosted-server). -`Settings` -> `Rules` -> `Add Rule` -> `Remote Rule (Github)` with: +See the [OpenAI plugin documentation](https://developers.openai.com/codex/plugins/). -```txt -sumup/sumup-skills + + + +Run these commands in your terminal: + +```bash +claude plugin marketplace add sumup/sumup-skills +claude plugin install sumup@sumup +claude plugin list ``` -## Gemini CLI +You can also run `/plugin marketplace add sumup/sumup-skills` and `/plugin install sumup@sumup` inside Claude Code. + +Open `/plugin` to confirm SumUp is installed. Follow the install summary's reload instructions, then open `/mcp` and authenticate the SumUp server in your browser. + +See the [Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins). + + + + +For a team marketplace, an administrator can import the repository: + +1. Open the Cursor dashboard and go to **Plugins & MCPs**. +2. Under **Team Marketplaces**, choose **Add Marketplace**, then **Import from Repo**. +3. Enter `https://github.com/sumup/sumup-skills` and add the SumUp plugin to the marketplace. +4. In Cursor, install SumUp from your team's marketplace and authorize the MCP connection when prompted. -Install the SumUp Gemini extension from GitHub: +For an individual setup, [install the SumUp skills](/tools/llms/agent-skills/) and [add the hosted MCP server](/tools/llms/mcp-server/#connect-the-hosted-server). + +See the [Cursor plugin documentation](https://cursor.com/docs/plugins). + + + + +Install the SumUp extension from your terminal: ```bash gemini extensions install https://github.com/sumup/sumup-skills --ref=main +gemini extensions list +``` + +Start a new Gemini CLI session. Run `/mcp` to check the SumUp server and `/mcp auth sumup` to complete authorization in your browser. + +See the [Gemini CLI extension documentation](https://geminicli.com/docs/extensions/). + + + + +Import SumUp as a custom power: + +1. Open **Powers**. +2. Select **Add Custom Power**, then **Import power from GitHub**. +3. Enter `https://github.com/sumup/sumup-skills`. +4. Activate the SumUp power and complete authentication when its MCP tools are needed. + +For local testing, use **Import power from a folder** and select a clone of the repository. + +See the [Kiro power installation documentation](https://kiro.dev/docs/powers/installation/). + + + + +## Verify the Setup + +Start with a guidance prompt: + +```text +Use the SumUp skills to explain how to build a Hosted Checkout integration. ``` -## OpenAI Codex +After authorizing MCP, check the connection with a read-only request: -Install the SumUp plugin with the Codex plugin marketplace: +```text +Use the SumUp MCP tools to show my merchant profile. +``` + +If the skills load but account tools fail, follow [MCP troubleshooting](/tools/llms/mcp-server/#troubleshooting). Before trying payment flows, use a [sandbox merchant account](/online-payments/#getting-a-sandbox-merchant-account). + +## Keep the Plugin Updated + +For Codex, refresh the marketplace from your terminal, then start a new session: ```bash -codex plugin marketplace add sumup/sumup-skills +codex plugin marketplace upgrade sumup ``` -## Kiro +For Claude Code, update the installed plugin: -Import the repository as a custom Kiro power: +```bash +claude plugin update sumup@sumup +``` + +For Gemini CLI, update the extension: + +```bash +gemini extensions update sumup +``` -1. Open `Powers`. -2. Select `Add Custom Power`. -3. Select `Import power from GitHub`. -4. Use `https://github.com/sumup/sumup-skills`. +For a Cursor team marketplace, your administrator can enable **Auto Refresh** in its marketplace settings. -## Related +For Kiro, open the SumUp power, select **Check for updates**, and install any available update. + +## Other Assistants + +For clients that support Agent Skills, install the skills separately: + +```bash +npx skills add https://github.com/sumup/sumup-skills +``` -- [Agent Skills](/tools/llms/agent-skills/) -- [MCP Server](/tools/llms/mcp-server/) +Then [connect the MCP server](/tools/llms/mcp-server/) if you need account tools. For more installation options, see [Agent Skills](/tools/llms/agent-skills/). From e4ebb030f74d29e3ac438ed333bf2af6ce6de51b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Dzivjak?= Date: Wed, 7 Oct 2026 23:41:38 +0200 Subject: [PATCH 2/2] feat(docs): restructure AI docs --- public/_redirects | 5 + src/content/docs/tools/llms/agent-skills.mdx | 42 +-- src/content/docs/tools/llms/agent-toolkit.mdx | 2 +- src/content/docs/tools/llms/index.mdx | 59 +--- src/content/docs/tools/llms/mcp-server.mdx | 146 ++-------- src/content/docs/tools/llms/plugins.mdx | 143 ---------- src/content/docs/tools/llms/setup.mdx | 264 ++++++++++++++++++ 7 files changed, 331 insertions(+), 330 deletions(-) delete mode 100644 src/content/docs/tools/llms/plugins.mdx create mode 100644 src/content/docs/tools/llms/setup.mdx diff --git a/public/_redirects b/public/_redirects index e9814e48..c5f0b6df 100644 --- a/public/_redirects +++ b/public/_redirects @@ -1,3 +1,8 @@ +# AI assistant setup +/tools/llms/plugins /tools/llms/setup/ 301 +/tools/llms/plugins/ /tools/llms/setup/ 301 +/tools/llms/plugins/index.md /tools/llms/setup/index.md 301 + # SDKs redirects /tools/sdks/ios-sdk/ /terminal-payments/sdks/ios-sdk /tools/sdks/android-ttp/ /terminal-payments/sdks/android-ttp diff --git a/src/content/docs/tools/llms/agent-skills.mdx b/src/content/docs/tools/llms/agent-skills.mdx index a850d4fb..e98ac7ad 100644 --- a/src/content/docs/tools/llms/agent-skills.mdx +++ b/src/content/docs/tools/llms/agent-skills.mdx @@ -2,14 +2,31 @@ title: Agent Skills description: Use SumUp Agent Skills in AI coding assistants when building payment integrations. sidebar: - order: 51 + order: 52 --- [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) let AI coding assistants load focused instructions for specific tasks. We publish SumUp skills in the [`sumup/sumup-skills`](https://github.com/sumup/sumup-skills) repository to help you build terminal and online payment integrations faster and with fewer mistakes. -## Install Skills +## Available Skills + +- `sumup`: Implementing SumUp checkout flows end-to-end across Checkouts API, Payment Widget, Hosted Checkout, recurring tokenization, and terminal flows. +- `sumup-best-practices`: Choosing the right integration path and security posture across online, mobile, terminal SDK, and Cloud API integrations. +- `upgrade-sumup`: Planning and executing SumUp API and SDK upgrades across server and mobile surfaces. +- `sumup-debug`: Diagnosing integration failures such as webhook signature mismatches, scope issues, session expiry, widget failures, and duplicate refs. +- `sumup-mcp`: Configuring and using the SumUp MCP server (`https://mcp.sumup.com/mcp`) from MCP-capable clients. +- `sumup-testing`: Setting up sandbox test merchants, running success and failure scenarios, and validating end-to-end checkout behavior. + +## Use Skills + +After installation, ask your assistant to use the relevant SumUp skill for checkout work, for example: + +- "Use `$sumup` to build a Cloud API payment flow for Solo." +- "Use `$sumup` to implement a Payment Widget checkout with server-side checkout creation." +- "Use `$sumup-debug` to troubleshoot 3DS and webhook handling for online payments." + +## Install Standalone Skills -For assistants that support SumUp's packaged integrations, [install the plugin](/tools/llms/plugins/) to get both skills and MCP configuration. Use the instructions below to install skills on their own; this does not configure an MCP connection or require SumUp credentials. +To install skills together with MCP configuration, follow [Set up your AI assistant](/tools/llms/setup/). The instructions below install skills on their own; they do not configure an MCP connection or require SumUp credentials. If your assistant supports standard Agent Skills folders, install the SumUp skills with: @@ -41,26 +58,9 @@ Use this URL in clients that accept a discovery index. Clients that automaticall https://developer.sumup.com ``` -## Available Skills - -- `sumup`: Implementing SumUp checkout flows end-to-end across Checkouts API, Payment Widget, Hosted Checkout, recurring tokenization, and terminal flows. -- `sumup-best-practices`: Choosing the right integration path and security posture across online, mobile, terminal SDK, and Cloud API integrations. -- `upgrade-sumup`: Planning and executing SumUp API and SDK upgrades across server and mobile surfaces. -- `sumup-debug`: Diagnosing integration failures such as webhook signature mismatches, scope issues, session expiry, widget failures, and duplicate refs. -- `sumup-mcp`: Configuring and using the SumUp MCP server (`https://mcp.sumup.com/mcp`) from MCP-capable clients. -- `sumup-testing`: Setting up sandbox test merchants, running success and failure scenarios, and validating end-to-end checkout behavior. - -## Use Skills - -After installation, ask your assistant to use the relevant SumUp skill for checkout work, for example: - -- "Use `$sumup` to build a Cloud API payment flow for Solo." -- "Use `$sumup` to implement a Payment Widget checkout with server-side checkout creation." -- "Use `$sumup-debug` to troubleshoot 3DS and webhook handling for online payments." - ## Related -- [Plugins](/tools/llms/plugins/) +- [Set up your AI assistant](/tools/llms/setup/) - [LLMs overview](/tools/llms/) - [Agentic workflows](/tools/llms/agent-toolkit/) - [SumUp MCP Server](https://mcp.sumup.com/mcp) diff --git a/src/content/docs/tools/llms/agent-toolkit.mdx b/src/content/docs/tools/llms/agent-toolkit.mdx index 0da81e0f..02f412c8 100644 --- a/src/content/docs/tools/llms/agent-toolkit.mdx +++ b/src/content/docs/tools/llms/agent-toolkit.mdx @@ -141,4 +141,4 @@ The MCP adapter supports the following catalog controls: - `readOnly`: expose only tools that do not modify data. - `includeOutputSchemas`: advertise output schemas to MCP clients. This is disabled by default to reduce the context used by `tools/list`; tool results are still validated at runtime. -To connect an MCP client to SumUp without hosting your own server, use the [managed SumUp MCP server](/tools/llms/mcp-server/). +To connect an assistant to SumUp's managed MCP server, follow [Set up your AI assistant](/tools/llms/setup/). For server capabilities and local setup, see [MCP Server](/tools/llms/mcp-server/). diff --git a/src/content/docs/tools/llms/index.mdx b/src/content/docs/tools/llms/index.mdx index fbcf3616..94ba06ea 100644 --- a/src/content/docs/tools/llms/index.mdx +++ b/src/content/docs/tools/llms/index.mdx @@ -1,6 +1,6 @@ --- title: Overview -description: Set up AI coding assistants with SumUp plugins, skills, and MCP tools. +description: Build SumUp integrations and agentic applications with AI assistants, skills, and MCP tools. sidebar: order: 50 --- @@ -9,59 +9,26 @@ Use your AI assistant to build SumUp payment integrations, troubleshoot checkout ## Get Started -Choose the setup that fits your workflow: +[Set up your AI assistant](/tools/llms/setup/) for client-specific installation, authentication, and verification instructions. The guide covers Codex, Claude Code, Cursor, Gemini CLI, Kiro, VS Code, and Claude Desktop. -| Your workflow | Start with | -| --- | --- | -| Build integrations in an AI coding assistant | [Install the SumUp plugin](/tools/llms/plugins/) for your assistant to get skills and MCP configuration. | -| Connect an assistant directly to your SumUp account | [Set up the hosted MCP server](/tools/llms/mcp-server/) and sign in with SumUp. | -| Add integration guidance to an assistant that supports skills | [Install Agent Skills](/tools/llms/agent-skills/). Skills work without connecting an account. | -| Build your own agentic application | [Use the Agent Toolkit](/tools/llms/agent-toolkit/) to add SumUp API tools to your application. | - -For example, after installing the plugin, ask your assistant: +After setup, try prompts such as: - "Help me choose between SumUp Hosted Checkout and the Payment Widget." - "Implement a SumUp Payment Widget checkout with server-side checkout creation." - "Use the SumUp MCP tools to show my merchant profile." -The first two prompts use integration guidance. Account queries require an authenticated MCP connection. - -## Plain Text Docs - -You can access all of our documentation as plain text Markdown files by adding `index.md` to the end of any URL. For example, you can find the plaintext version of this page itself at https://developer.sumup.com/tools/llms/index.md. - -This helps AI tools and agents consume our content and allows you to copy and paste the entire contents of a doc into an LLM. This format is preferable to scraping or copying from our HTML and JavaScript-rendered pages because: - -- Plain text contains fewer formatting tokens. -- Content that isn’t rendered in the default view (for example, it’s hidden in a tab) of a given page is rendered in the plaintext version. -- LLMs can parse and understand Markdown hierarchy. - -We also host an [/llms.txt](/llms.txt) file which instructs AI tools and agents how to retrieve the plaintext versions of our pages. The `/llms.txt` file is an [emerging standard](https://llmstxt.org/) for making websites and content more accessible to LLMs. - -## Agent Skills +Skills provide integration guidance without requiring credentials. Account queries require an authenticated MCP connection. -If you use AI coding assistants, SumUp provides [Agent Skills](/tools/llms/agent-skills/) with targeted guidance for building payment integrations. Install only the skill folders with `npx skills`, copy them into your assistant's skills directory, or use the hosted Agent Skills Discovery index at `https://developer.sumup.com/.well-known/agent-skills/index.json`. +## Explore the Tools -## Plugins - -SumUp also publishes [plugins, extensions, and powers](/tools/llms/plugins/) for Claude Code, Cursor, Gemini CLI, OpenAI Codex, and Kiro. Use these packaged integrations when you want the assistant-specific setup from the `sumup/sumup-skills` repository. - -## SumUp Model Context Protocol (MCP) Server - -Use the [SumUp MCP server](/tools/llms/mcp-server/) to connect MCP-compatible clients and AI assistants to SumUp APIs and documentation tools. - -Hosted MCP URL: [https://mcp.sumup.com/mcp](https://mcp.sumup.com/mcp) - -The hosted server uses OAuth. Connect with an OAuth-capable MCP client and authorize access when prompted. - -You can also run MCP locally with Node.js 22 or later and a SumUp API key: - -```sh -SUMUP_API_KEY='sup_sk_...' npx -y @sumup/mcp -``` +| Tool | Use it for | +| --- | --- | +| [Agent Skills](/tools/llms/agent-skills/) | Focused guidance for implementing, testing, upgrading, and debugging integrations; browse the skill catalog or install skills on their own. | +| [MCP Server](/tools/llms/mcp-server/) | SumUp API tools and documentation resources; learn about authentication, local setup, and troubleshooting. | +| [Agent Toolkit](/tools/llms/agent-toolkit/) | SumUp API tools for your own applications built with LangChain, AI SDK, the OpenAI Agents SDK, or MCP. | -For full setup instructions and client examples, see [MCP Server](/tools/llms/mcp-server/). +## Plain Text Docs -## SumUp Agent Toolkit SDK +AI tools can discover our documentation through [/llms.txt](/llms.txt). To read a page as Markdown, append `index.md` to its URL, for example [this overview as Markdown](/tools/llms/index.md). -If you’re building agentic software, we provide an SDK for adding SumUp functionality to your agent’s capabilities. Learn more in our [agents documentation](/tools/llms/agent-toolkit/). +Markdown versions include content from every tab and preserve heading structure, making them useful for assistants and agents. For hosted skill discovery, see [Discover Skills](/tools/llms/agent-skills/#discover-skills). diff --git a/src/content/docs/tools/llms/mcp-server.mdx b/src/content/docs/tools/llms/mcp-server.mdx index 3722e110..8cec22c4 100644 --- a/src/content/docs/tools/llms/mcp-server.mdx +++ b/src/content/docs/tools/llms/mcp-server.mdx @@ -1,146 +1,54 @@ --- title: MCP Server -description: Connect Codex, Claude Code, Cursor, Gemini CLI, and other MCP clients to SumUp. +description: Learn about SumUp MCP capabilities, authentication, documentation resources, local setup, and troubleshooting. sidebar: order: 53 --- -import { Tabs, TabItem } from '@astrojs/starlight/components'; +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. -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 the developer documentation index and OpenAPI specification. +For client-specific installation and login steps, start with [Set up your AI assistant](/tools/llms/setup/). -Use it to query your merchant profile, inspect checkout status, review transactions, or build payment workflows with [Cloud API](/terminal-payments/cloud-api/). +## What You Can Do -## Choose a Setup +Use the server to: -If you use a supported coding assistant, [install the SumUp plugin](/tools/llms/plugins/) to get both integration skills and MCP configuration. If you have already installed the plugin, authorize its bundled server and continue to [verify the connection](#verify-the-connection). +- 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. -For a direct connection, choose between: +## 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 +### Connect the Hosted Server -Add `https://mcp.sumup.com/mcp` to your client, then authorize access in your browser. The client discovers the SumUp authorization server through the endpoint's protected resource metadata. +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. - - - -Run these commands in your terminal: - -```bash -codex mcp add sumup --url https://mcp.sumup.com/mcp -codex mcp login sumup -codex mcp list -``` - -Complete the browser login. In a Codex session, use `/mcp` to check the active tools. - -Alternatively, add this entry to `~/.codex/config.toml`, then run `codex mcp login sumup`: - -```toml -[mcp_servers.sumup] -url = "https://mcp.sumup.com/mcp" -``` - -The Codex CLI, ChatGPT desktop app, and Codex IDE extension share this MCP configuration on the same host. See the [OpenAI MCP documentation](https://developers.openai.com/codex/mcp). - - - - -Add the server from your terminal: - -```bash -claude mcp add --transport http --scope user sumup https://mcp.sumup.com/mcp -claude mcp list -``` - -Open Claude Code, run `/mcp`, and select the SumUp server to authenticate in your browser. The `user` scope makes the connection available across your projects. - -See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp). - - - - -Add this entry to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one project. Merge it with any existing servers: - -```json -{ - "mcpServers": { - "sumup": { - "url": "https://mcp.sumup.com/mcp" - } - } -} -``` - -Open Cursor's MCP settings, connect the SumUp server, and complete authorization in your browser. Check that its tools are available in Agent. - -See the [Cursor MCP documentation](https://cursor.com/docs/context/mcp). - - - - -Add the server from your terminal: - -```bash -gemini mcp add --transport http --scope user sumup https://mcp.sumup.com/mcp -gemini mcp list -``` - -Start Gemini CLI and run `/mcp auth sumup` to sign in through your browser. Use `/mcp` to check the server and its tools. - -See the [Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/). - - - - -For GitHub Copilot, add this configuration to `.vscode/mcp.json` in your workspace. Merge it with any existing servers: - -```json -{ - "servers": { - "sumup": { - "type": "http", - "url": "https://mcp.sumup.com/mcp" - } - } -} -``` - -Run **MCP: List Servers** from the command palette, start SumUp, and complete authorization when prompted. Its tools are then available in agent chat. - -See the [VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers). - - - - -For a Claude plan that supports custom connectors: - -1. Open **Customize > Connectors**. -2. Choose **Add**, then **Add custom connector**. -3. Enter **SumUp** as the name and `https://mcp.sumup.com/mcp` as the URL. -4. Complete the SumUp authorization flow and enable the connector in your conversation. - -On Team and Enterprise plans, an owner must add the connector before members can connect it. See the [Claude custom connector documentation](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). - - - +The hosted server supports Streamable HTTP at `/mcp` and the legacy SSE transport at `/sse`. Use `/mcp` for new connections. ## Verify the Connection -Confirm that your client's MCP tool list includes SumUp, then try a read-only prompt: - -```text -Use the SumUp MCP tools to show my merchant profile. -``` +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). -To test a payment workflow, first connect a [sandbox merchant account](/online-payments/#getting-a-sandbox-merchant-account). For example: +For example, once your sandbox connection is ready: ```text Using my sandbox merchant, create a checkout for 12.34 EUR with a unique @@ -189,4 +97,4 @@ Replace the placeholder with your API key in your client's private configuration - **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 [Plugins](/tools/llms/plugins/). +For integration guidance alongside the tools, see [Agent Skills](/tools/llms/agent-skills/) and [Set up your AI assistant](/tools/llms/setup/). diff --git a/src/content/docs/tools/llms/plugins.mdx b/src/content/docs/tools/llms/plugins.mdx deleted file mode 100644 index ecce851f..00000000 --- a/src/content/docs/tools/llms/plugins.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Plugins -description: Set up SumUp skills and MCP tools in Codex, Claude Code, Cursor, Gemini CLI, and Kiro. -sidebar: - order: 52 ---- - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -The [SumUp plugin](https://github.com/sumup/sumup-skills) bundles integration skills with configuration for the hosted MCP server at `https://mcp.sumup.com/mcp`. Install the package for your assistant, then sign in with SumUp when prompted to use account tools. - -Skills provide guidance for implementing, testing, upgrading, and debugging payment integrations. MCP tools let your assistant query your merchant account and call SumUp APIs. You can use the skills before connecting an account. - -## Install the Plugin - - - - -Run these commands in your terminal: - -```bash -codex plugin marketplace add sumup/sumup-skills -codex plugin add sumup@sumup -codex plugin list -``` - -Start a new Codex session to load the skills and tools. Complete the SumUp authorization flow when prompted. - -Plugins are supported in the Codex CLI and Codex in the ChatGPT desktop app. For the Codex IDE extension, [install skills](/tools/llms/agent-skills/) and [configure MCP directly](/tools/llms/mcp-server/#connect-the-hosted-server). - -See the [OpenAI plugin documentation](https://developers.openai.com/codex/plugins/). - - - - -Run these commands in your terminal: - -```bash -claude plugin marketplace add sumup/sumup-skills -claude plugin install sumup@sumup -claude plugin list -``` - -You can also run `/plugin marketplace add sumup/sumup-skills` and `/plugin install sumup@sumup` inside Claude Code. - -Open `/plugin` to confirm SumUp is installed. Follow the install summary's reload instructions, then open `/mcp` and authenticate the SumUp server in your browser. - -See the [Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins). - - - - -For a team marketplace, an administrator can import the repository: - -1. Open the Cursor dashboard and go to **Plugins & MCPs**. -2. Under **Team Marketplaces**, choose **Add Marketplace**, then **Import from Repo**. -3. Enter `https://github.com/sumup/sumup-skills` and add the SumUp plugin to the marketplace. -4. In Cursor, install SumUp from your team's marketplace and authorize the MCP connection when prompted. - -For an individual setup, [install the SumUp skills](/tools/llms/agent-skills/) and [add the hosted MCP server](/tools/llms/mcp-server/#connect-the-hosted-server). - -See the [Cursor plugin documentation](https://cursor.com/docs/plugins). - - - - -Install the SumUp extension from your terminal: - -```bash -gemini extensions install https://github.com/sumup/sumup-skills --ref=main -gemini extensions list -``` - -Start a new Gemini CLI session. Run `/mcp` to check the SumUp server and `/mcp auth sumup` to complete authorization in your browser. - -See the [Gemini CLI extension documentation](https://geminicli.com/docs/extensions/). - - - - -Import SumUp as a custom power: - -1. Open **Powers**. -2. Select **Add Custom Power**, then **Import power from GitHub**. -3. Enter `https://github.com/sumup/sumup-skills`. -4. Activate the SumUp power and complete authentication when its MCP tools are needed. - -For local testing, use **Import power from a folder** and select a clone of the repository. - -See the [Kiro power installation documentation](https://kiro.dev/docs/powers/installation/). - - - - -## Verify the Setup - -Start with a guidance prompt: - -```text -Use the SumUp skills to explain how to build a Hosted Checkout integration. -``` - -After authorizing MCP, check the connection with a read-only request: - -```text -Use the SumUp MCP tools to show my merchant profile. -``` - -If the skills load but account tools fail, follow [MCP troubleshooting](/tools/llms/mcp-server/#troubleshooting). Before trying payment flows, use a [sandbox merchant account](/online-payments/#getting-a-sandbox-merchant-account). - -## Keep the Plugin Updated - -For Codex, refresh the marketplace from your terminal, then start a new session: - -```bash -codex plugin marketplace upgrade sumup -``` - -For Claude Code, update the installed plugin: - -```bash -claude plugin update sumup@sumup -``` - -For Gemini CLI, update the extension: - -```bash -gemini extensions update sumup -``` - -For a Cursor team marketplace, your administrator can enable **Auto Refresh** in its marketplace settings. - -For Kiro, open the SumUp power, select **Check for updates**, and install any available update. - -## Other Assistants - -For clients that support Agent Skills, install the skills separately: - -```bash -npx skills add https://github.com/sumup/sumup-skills -``` - -Then [connect the MCP server](/tools/llms/mcp-server/) if you need account tools. For more installation options, see [Agent Skills](/tools/llms/agent-skills/). diff --git a/src/content/docs/tools/llms/setup.mdx b/src/content/docs/tools/llms/setup.mdx new file mode 100644 index 00000000..2d61dbef --- /dev/null +++ b/src/content/docs/tools/llms/setup.mdx @@ -0,0 +1,264 @@ +--- +title: Set up your AI assistant +description: Install SumUp skills and connect MCP tools in Codex, Claude Code, Cursor, Gemini CLI, Kiro, VS Code, and Claude Desktop. +sidebar: + label: Set up your assistant + order: 51 +tableOfContents: + maxHeadingLevel: 2 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Set up your assistant to build SumUp integrations and work with your merchant account. Choose your assistant below, install the available package, and sign in with SumUp to use account tools. + +The [SumUp plugin](https://github.com/sumup/sumup-skills) bundles two capabilities: + +- **Agent Skills** provide guidance for implementing, testing, upgrading, and debugging payment integrations. Skills work without connecting a SumUp account. +- **MCP tools** let your assistant call SumUp APIs and read documentation resources. The hosted server at `https://mcp.sumup.com/mcp` uses OAuth: sign in with SumUp through your client when prompted. + +If you install a plugin, extension, or power that configures MCP, use its bundled connection. The direct MCP instructions are an alternative for clients without plugins or when you only need account tools. For API-key authentication or stdio-only clients, see [local MCP setup](/tools/llms/mcp-server/#run-the-local-server). + +## Choose Your Assistant + + + + +### Install the Codex Plugin + +Run these commands in your terminal: + +```bash +codex plugin marketplace add sumup/sumup-skills +codex plugin add sumup@sumup +codex plugin list +``` + +Start a new Codex session to load the skills and tools. Complete the SumUp authorization flow when prompted. + +Plugins are supported in the Codex CLI and Codex in the ChatGPT desktop app. For the Codex IDE extension, [install standalone skills](/tools/llms/agent-skills/#install-standalone-skills) and use the direct MCP instructions below. + +See the [OpenAI plugin documentation](https://developers.openai.com/codex/plugins/). + +### Connect Codex Directly + +Run these commands in your terminal: + +```bash +codex mcp add sumup --url https://mcp.sumup.com/mcp +codex mcp login sumup +codex mcp list +``` + +Complete the browser login. In a Codex session, use `/mcp` to check the active tools. + +Alternatively, add this entry to `~/.codex/config.toml`, then run `codex mcp login sumup`: + +```toml +[mcp_servers.sumup] +url = "https://mcp.sumup.com/mcp" +``` + +The Codex CLI, ChatGPT desktop app, and Codex IDE extension share this MCP configuration on the same host. See the [OpenAI MCP documentation](https://developers.openai.com/codex/mcp). + + + + +### Install the Claude Code Plugin + +Run these commands in your terminal: + +```bash +claude plugin marketplace add sumup/sumup-skills +claude plugin install sumup@sumup +claude plugin list +``` + +You can also run `/plugin marketplace add sumup/sumup-skills` and `/plugin install sumup@sumup` inside Claude Code. + +Open `/plugin` to confirm SumUp is installed. Follow the install summary's reload instructions, then open `/mcp` and authenticate the SumUp server in your browser. + +See the [Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins). + +### Connect Claude Code Directly + +Add the server from your terminal: + +```bash +claude mcp add --transport http --scope user sumup https://mcp.sumup.com/mcp +claude mcp list +``` + +Open Claude Code, run `/mcp`, and select the SumUp server to authenticate in your browser. The `user` scope makes the connection available across your projects. + +See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp). + + + + +### Install the Cursor Plugin + +For a team marketplace, an administrator can import the repository: + +1. Open the Cursor dashboard and go to **Plugins & MCPs**. +2. Under **Team Marketplaces**, choose **Add Marketplace**, then **Import from Repo**. +3. Enter `https://github.com/sumup/sumup-skills` and add the SumUp plugin to the marketplace. +4. In Cursor, install SumUp from your team's marketplace and authorize the MCP connection when prompted. + +For an individual setup, [install standalone SumUp skills](/tools/llms/agent-skills/#install-standalone-skills) and add the hosted MCP server using the configuration below. + +See the [Cursor plugin documentation](https://cursor.com/docs/plugins). + +### Connect Cursor Directly + +Add this entry to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one project. Merge it with any existing servers: + +```json +{ + "mcpServers": { + "sumup": { + "url": "https://mcp.sumup.com/mcp" + } + } +} +``` + +Open Cursor's MCP settings, connect the SumUp server, and complete authorization in your browser. Check that its tools are available in Agent. + +See the [Cursor MCP documentation](https://cursor.com/docs/context/mcp). + + + + +### Install the Gemini Extension + +Install the SumUp extension from your terminal: + +```bash +gemini extensions install https://github.com/sumup/sumup-skills --ref=main +gemini extensions list +``` + +Start a new Gemini CLI session. Run `/mcp` to check the SumUp server and `/mcp auth sumup` to complete authorization in your browser. + +See the [Gemini CLI extension documentation](https://geminicli.com/docs/extensions/). + +### Connect Gemini CLI Directly + +Add the server from your terminal: + +```bash +gemini mcp add --transport http --scope user sumup https://mcp.sumup.com/mcp +gemini mcp list +``` + +Start Gemini CLI and run `/mcp auth sumup` to sign in through your browser. Use `/mcp` to check the server and its tools. + +See the [Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/). + + + + +### Install the Kiro Power + +Import SumUp as a custom power: + +1. Open **Powers**. +2. Select **Add Custom Power**, then **Import power from GitHub**. +3. Enter `https://github.com/sumup/sumup-skills`. +4. Activate the SumUp power and complete authentication when its MCP tools are needed. + +For local testing, use **Import power from a folder** and select a clone of the repository. + +See the [Kiro power installation documentation](https://kiro.dev/docs/powers/installation/). + + + + +### Connect VS Code to SumUp + +For GitHub Copilot, add this configuration to `.vscode/mcp.json` in your workspace. Merge it with any existing servers: + +```json +{ + "servers": { + "sumup": { + "type": "http", + "url": "https://mcp.sumup.com/mcp" + } + } +} +``` + +Run **MCP: List Servers** from the command palette, start SumUp, and complete authorization when prompted. Its tools are then available in agent chat. + +See the [VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers). + + + + +### Connect Claude Desktop to SumUp + +For a Claude plan that supports custom connectors: + +1. Open **Customize > Connectors**. +2. Choose **Add**, then **Add custom connector**. +3. Enter **SumUp** as the name and `https://mcp.sumup.com/mcp` as the URL. +4. Complete the SumUp authorization flow and enable the connector in your conversation. + +On Team and Enterprise plans, an owner must add the connector before members can connect it. See the [Claude custom connector documentation](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). + + + + +## Verify the Setup + +If you installed skills, start with a guidance prompt: + +```text +Use the SumUp skills to explain how to build a Hosted Checkout integration. +``` + +After authorizing MCP, check the connection with a read-only request: + +```text +Use the SumUp MCP tools to show my merchant profile. +``` + +If the skills load but account tools fail, follow [MCP troubleshooting](/tools/llms/mcp-server/#troubleshooting). Before trying payment flows, use a [sandbox merchant account](/online-payments/#getting-a-sandbox-merchant-account). + +## Keep the Plugin Updated + +For Codex, refresh the marketplace from your terminal, then start a new session: + +```bash +codex plugin marketplace upgrade sumup +``` + +For Claude Code, update the installed plugin: + +```bash +claude plugin update sumup@sumup +``` + +For Gemini CLI, update the extension: + +```bash +gemini extensions update sumup +``` + +For a Cursor team marketplace, your administrator can enable **Auto Refresh** in its marketplace settings. + +For Kiro, open the SumUp power, select **Check for updates**, and install any available update. + +## Other Assistants + +For clients that support Agent Skills, install the skills separately: + +```bash +npx skills add https://github.com/sumup/sumup-skills +``` + +For account tools, add `https://mcp.sumup.com/mcp` using your client's Streamable HTTP configuration and complete its OAuth login flow. Check that SumUp tools appear, then use the verification prompt above. + +For more installation options, see [Agent Skills](/tools/llms/agent-skills/). For server capabilities, local setup, and troubleshooting, see [MCP Server](/tools/llms/mcp-server/).