matoous · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026
diff --git 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
@@ -2,12 +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
+
+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:
 
@@ -25,8 +44,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:
@@ -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
@@ -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
@@ -1,48 +1,34 @@
 ---
 title: Overview
-description: Use LLMs to guide you through developing with SumUp SDKs.
+description: Build SumUp integrations and agentic applications with AI assistants, 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).
 
-## 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.
+## Get Started
 
-## Agent Skills
+[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.
 
-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`.
+After setup, try prompts such as:
 
-## Plugins
+- "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."
 
-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.
+Skills provide integration guidance without requiring credentials. Account queries require an authenticated MCP connection.
 
-## SumUp Model Context Protocol (MCP) Server
+## Explore the Tools
 
-Use the [SumUp MCP server](/tools/llms/mcp-server/) to connect MCP-compatible clients and AI assistants to SumUp APIs and documentation tools.
+| 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. |
 
-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
-```
-
-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
@@ -1,57 +1,78 @@
 ---
 title: MCP Server
-description: Connect MCP-compatible clients and assistants to SumUp APIs and tools.
+description: Learn about SumUp MCP capabilities, authentication, documentation resources, local setup, and troubleshooting.
 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.
+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 MCP server gives AI agents tools for calling the SumUp API. It also exposes the SumUp developer documentation index and OpenAPI specification as resources.
+For client-specific installation and login steps, start with [Set up your AI assistant](/tools/llms/setup/).
 
-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`.
+## What You Can Do
 
-## Hosted MCP (managed)
+Use the server to:
 
-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.
+- 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.
 
-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.
+## Documentation Resources
 
-## CLI
+Clients that support MCP resources can read:
 
-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:
+| Resource | URI |
+| --- | --- |
+| Developer documentation index | `https://developer.sumup.com/llms.txt` |
+| API OpenAPI specification | `https://developer.sumup.com/openapi.json` |
 
-```sh
-SUMUP_API_KEY='sup_sk_MvxmLOl0...' npx -y @sumup/mcp
-```
+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.
 
-The local MCP server reads the API key from the `SUMUP_API_KEY` environment variable.
+## Authentication
 
-## [Cursor](https://www.cursor.com/)
+| 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 |
 
-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.
+### Connect the Hosted Server
 
-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+).
+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).
 
-```json
-{
-  "mcpServers": {
-    "sumup": {
-      "command": "npx",
-      "args": ["-y", "@sumup/mcp"],
-      "env": {
-        "SUMUP_API_KEY": "sup_sk_..."
-      }
-    }
-  }
-}
+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.
 ```
 
-## [Claude](https://claude.ai)
+## Run the Local Server
 
-Add the following to your `claude_desktop_config.json` file. See the [Claude Desktop documentation](https://modelcontextprotocol.io/quickstart/user) for more details.
+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 +88,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 [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