sumup · matoous · Aug 15, 2026 · Aug 15, 2026
diff --git a/src/content/docs/tools/llms/agent-toolkit.mdx b/src/content/docs/tools/llms/agent-toolkit.mdx
@@ -1,90 +1,144 @@
 ---
-title: Agentic Workflows
-description: Use SumUp in your agentic workflows.
+title: Agent Toolkit
+description: Add SumUp API tools to LangChain, AI SDK, OpenAI Agents SDK, or an MCP server.
 sidebar:
   order: 54
 ---
 
-Use SumUp to enhance your agent with SumUp functionalities. By enabling access to financial services and tools, you allow your agents to help you earn money, manage funds, and other provide other functionalities available in SumUp APIs.
+The [SumUp Agent Toolkit](https://github.com/sumup/sumup-ai) adds SumUp API tools to agentic applications built with LangChain, AI SDK, the OpenAI Agents SDK, or the Model Context Protocol (MCP).
 
-## OpenAI
+## Prerequisites
 
-Example usage of the [SumUp Agent Toolkit](https://github.com/sumup/sumup-ai) with the [OpenAI](https://github.com/openai/openai-node).
+The Agent Toolkit requires Node.js 22 or later and a [SumUp API key](/tools/authorization/api-keys/).
 
-```ts
-import { SumUpAgentToolkit } from "@sumup/agent-toolkit/openai";
-import OpenAI from "openai";
-import type { ChatCompletionMessageParam } from "openai/resources";
+## Installation
 
-require("dotenv").config();
+```sh
+npm install @sumup/agent-toolkit
+```
 
-const openai = new OpenAI();
+## LangChain
+
+```ts
+import { SumUpAgentToolkit } from "@sumup/agent-toolkit/langchain";
+import { createAgent } from "langchain";
 
 const sumupAgentToolkit = new SumUpAgentToolkit({
   apiKey: process.env.SUMUP_API_KEY!,
 });
 
-(async (): Promise<void> => {
-  let messages: ChatCompletionMessageParam[] = [
+const agent = createAgent({
+  model: "openai:gpt-4o",
+  tools: sumupAgentToolkit.getTools(),
+});
+
+const response = await agent.invoke({
+  messages: [
     {
       role: "user",
-      content: "Tell me about my last 10 transactions please.",
+      content: "Tell me about my last 10 transactions.",
     },
-  ];
-
-  while (true) {
-    // eslint-disable-next-line no-await-in-loop
-    const completion = await openai.chat.completions.create({
-      model: "gpt-4o",
-      messages,
-      tools: sumupAgentToolkit.getTools(),
-    });
-
-    const message = completion.choices[0].message;
-
-    messages.push(message);
-
-    if (message.tool_calls) {
-      // eslint-disable-next-line no-await-in-loop
-      const toolMessages = await Promise.all(
-        message.tool_calls.map((tc) => sumupAgentToolkit.handleToolCall(tc)),
-      );
-      messages = [...messages, ...toolMessages];
-    } else {
-      console.log(completion.choices[0].message);
-      break;
-    }
-  }
-})();
+  ],
+});
+
+console.log(response);
 ```
 
 ## AI SDK
 
-Example usage of the [SumUp Agent Toolkit](https://github.com/sumup/ai) with the [AI SDK](https://sdk.vercel.ai/).
-
 ```ts
-import { openai } from "@ai-sdk/openai";
 import { SumUpAgentToolkit } from "@sumup/agent-toolkit/ai";
-import { generateText } from "ai";
+import { generateText, stepCountIs } from "ai";
+
+const sumupAgentToolkit = new SumUpAgentToolkit({
+  apiKey: process.env.SUMUP_API_KEY!,
+});
+
+const response = await generateText({
+  model: "openai/gpt-4o",
+  tools: sumupAgentToolkit.getTools(),
+  stopWhen: stepCountIs(5),
+  prompt: "Tell me about my last 10 transactions.",
+});
 
-require("dotenv").config();
+console.log(response.text);
+```
+
+## OpenAI Agents SDK
+
+```ts
+import { Agent, run } from "@openai/agents";
+import { SumUpAgentToolkit } from "@sumup/agent-toolkit/openai";
 
 const sumupAgentToolkit = new SumUpAgentToolkit({
   apiKey: process.env.SUMUP_API_KEY!,
 });
 
-const model = openai("gpt-4o");
+const agent = new Agent({
+  name: "Transactions reporter",
+  instructions: "You are a helpful payments assistant.",
+  tools: sumupAgentToolkit.getTools(),
+});
+
+const result = await run(agent, "Tell me about my last 10 transactions.");
+
+console.log(result.finalOutput);
+```
+
+## Tool approvals
 
-(async () => {
-  const result = await generateText({
-    model: model,
-    tools: {
-      ...sumupAgentToolkit.getTools(),
+The AI SDK and OpenAI Agents SDK adapters require approval before running tools that can modify data. Read-only tools run without approval. You can override the default with an `approvalPolicy` callback that is evaluated for each tool call.
+
+```ts
+const sumupAgentToolkit = new SumUpAgentToolkit({
+  apiKey: process.env.SUMUP_API_KEY!,
+  approvalPolicy: (tool) => !tool.annotations?.readOnly,
+});
+```
+
+Your application is responsible for presenting and resolving approval requests using the framework's approval flow.
+
+## Observability
+
+Every adapter accepts optional lifecycle callbacks for recording tool execution rate, errors, and duration. Events include the tool name and timing information, but never tool arguments or results. Callback failures do not interrupt tool execution.
+
+```ts
+const sumupAgentToolkit = new SumUpAgentToolkit({
+  apiKey: process.env.SUMUP_API_KEY!,
+  observability: {
+    onToolEnd: ({ toolName, durationMs }) => {
+      console.info("SumUp tool completed", { toolName, durationMs });
     },
-    maxSteps: 5,
-    prompt: "Tell me about my last 5 transactions and their status.",
-  });
+    onToolError: ({ toolName, durationMs, error }) => {
+      console.error("SumUp tool failed", {
+        toolName,
+        durationMs,
+        errorType: error instanceof Error ? error.name : "unknown",
+      });
+    },
+  },
+});
+```
+
+## MCP adapter
+
+Use the MCP adapter when embedding SumUp tools in your own MCP server.
+
+```ts
+import { SumUpAgentToolkit } from "@sumup/agent-toolkit/mcp";
 
-  console.log(result);
-})();
+const server = new SumUpAgentToolkit({
+  apiKey: process.env.SUMUP_API_KEY!,
+  readOnly: true,
+  configuration: {},
+});
 ```
+
+The MCP adapter supports the following catalog controls:
+
+- `includeTools`: expose only the named tools.
+- `excludeTools`: omit the named tools.
+- `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/).
diff --git a/src/content/docs/tools/llms/index.mdx b/src/content/docs/tools/llms/index.mdx
@@ -33,7 +33,9 @@ Use the [SumUp MCP server](/tools/llms/mcp-server/) to connect MCP-compatible cl
 
 Hosted MCP URL: [https://mcp.sumup.com/mcp](https://mcp.sumup.com/mcp)
 
-You can also run MCP locally:
+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

diff --git a/src/content/docs/tools/llms/mcp-server.mdx b/src/content/docs/tools/llms/mcp-server.mdx
@@ -5,25 +5,27 @@ sidebar:
   order: 53
 ---
 
-[MCP](https://modelcontextprotocol.io/introduction) is an open protocol that standardizes how applications provide context to LLMs. For developers using AI-powered code editors such as Cursor or Windsurf, or general-purpose tools such as Claude Desktop, we provide the [SumUp Model Context Protocol (MCP) server](https://github.com/sumup/ai/tree/main/mcp).
+[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 MCP server gives AI agents tools for calling the SumUp API and searching our knowledge base (documentation, support articles, and so on).
+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.
 
-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] transport via `/mcp` and the SSE transport (deprecated) via `/sse`.
+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`.
 
 ## Hosted MCP (managed)
 
-If your MCP client supports streamable HTTP, connect directly to the hosted server instead of running a local process. Configure your MCP client to use `https://mcp.sumup.com/mcp` and send your SumUp API key as a Bearer token in the `Authorization` header (or equivalent auth configuration in your client).
+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.
+
+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.
 
 ## CLI
 
-Run the following command to start the MCP server locally.
+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:
 
 ```sh
 SUMUP_API_KEY='sup_sk_MvxmLOl0...' npx -y @sumup/mcp
 ```
 
-The MCP server uses either the passed `--api-key` or the `SUMUP_API_KEY` environment variable.
+The local MCP server reads the API key from the `SUMUP_API_KEY` environment variable.
 
 ## [Cursor](https://www.cursor.com/)