diff --git a/app/en/guides/mcp-gateways/_meta.tsx b/app/en/guides/mcp-gateways/_meta.tsx index 2183b7884..a18ae66b7 100644 --- a/app/en/guides/mcp-gateways/_meta.tsx +++ b/app/en/guides/mcp-gateways/_meta.tsx @@ -10,6 +10,9 @@ export const meta: MetaRecord = { "create-via-ai": { title: "Create via AI Assistant", }, + "protocol-versions": { + title: "Supported protocol versions", + }, }; export default meta; diff --git a/app/en/guides/mcp-gateways/page.mdx b/app/en/guides/mcp-gateways/page.mdx index b14f50f26..8deacf3a1 100644 --- a/app/en/guides/mcp-gateways/page.mdx +++ b/app/en/guides/mcp-gateways/page.mdx @@ -57,7 +57,7 @@ Any MCP client that supports the Streamable HTTP transport can use an Arcade MCP https://api.arcade.dev/mcp/{YOUR-GATEWAY-SLUG} ``` -Learn how to [connect MCP Gateways to your preferred client](/get-started/mcp-clients). +Learn how to [connect MCP Gateways to your preferred client](/get-started/mcp-clients). See [Supported MCP protocol versions](/guides/mcp-gateways/protocol-versions) for which protocol versions Arcade gateways support. ## Authentication diff --git a/app/en/guides/mcp-gateways/protocol-versions/page.mdx b/app/en/guides/mcp-gateways/protocol-versions/page.mdx new file mode 100644 index 000000000..acd86d7b3 --- /dev/null +++ b/app/en/guides/mcp-gateways/protocol-versions/page.mdx @@ -0,0 +1,110 @@ +--- +title: "Supported MCP protocol versions" +description: "Which MCP protocol versions Arcade gateways support, and what changes for clients that adopt 2026-07-28" +--- + +import { Callout } from "nextra/components"; + +# Supported MCP protocol versions + +Arcade MCP Gateways support three MCP protocol versions: `2026-07-28`, `2025-11-25`, and `2025-06-18`. All three are fully supported today, none are deprecated, and there's no migration required to keep using the one your client already speaks. + +## Supported versions + +| Protocol version | Transport | Summary | +|---|---|---| +| `2026-07-28` | Sessionless | Tools only (`tools/list`, `tools/call`), including structured output. OAuth authorization challenges come back as an in-band MRTR url-mode elicitation instead of a transport error. | +| `2025-11-25` | Session-based (`Mcp-Session-Id`) | Tools only. | +| `2025-06-18` | Session-based (`Mcp-Session-Id`) | Tools only. | + +## How version selection works + +The gateway serves every version from the same URL. There's no separate endpoint or config flag per version: + +``` +https://api.arcade.dev/mcp/{YOUR-GATEWAY-SLUG} +``` + +The gateway picks which path to serve a request on from the `MCP-Protocol-Version` header the client sends, not from any project setting. This means: + +- Your gateway needs no configuration changes or migration to support any of the three versions. +- Existing clients on `2025-11-25` or `2025-06-18` see zero behavior change. +- Adopting `2026-07-28` is a choice you make as a builder, typically by upgrading to a client SDK that speaks it, not something Arcade switches on for you. + +## 2026-07-28 capabilities on Arcade gateways + +On the `2026-07-28` sessionless path, Arcade gateways support: + +- **`tools/list` and `tools/call`**, including structured tool output (`structuredContent` in the result). +- **OAuth authorization via a url-mode elicitation retry flow.** When a tool call needs end-user authorization, the gateway returns the authorization challenge as part of the tool result rather than failing the request. + +The following are explicitly **not** supported on `2026-07-28`: + +- `roots`, `sampling`, and `logging` (all deprecated in this protocol revision) +- Server-initiated streaming or notifications +- Extensions + +### OAuth authorization retry flow + +If your client declares the `elicitation.url` capability, a tool call that needs end-user authorization returns an MRTR (Multi-Round Tool Response) result with `resultType: "input_required"` and an `elicitation/create` entry in `inputRequests`: + +```json +// Request: tools/call, with headers +// MCP-Protocol-Version: 2026-07-28 +// Mcp-Method: tools/call +// Mcp-Name: Google_SendEmail +{ + "jsonrpc": "2.0", + "id": 11, + "method": "tools/call", + "params": { + "name": "Google_SendEmail", + "arguments": { "to": "someone@example.com", "subject": "Hello" }, + "_meta": { + "io.modelcontextprotocol/protocolVersion": "2026-07-28", + "io.modelcontextprotocol/clientInfo": { "name": "my-agent", "version": "1.0.0" }, + "io.modelcontextprotocol/clientCapabilities": { "elicitation": { "url": {} } } + } + } +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 11, + "result": { + "isError": false, + "resultType": "input_required", + "inputRequests": { + "1": { + "method": "elicitation/create", + "params": { + "mode": "url", + "url": "https://api.arcade.dev/oauth/authorize?..." + } + } + } + } +} +``` + +The client shows the user the elicitation `url`, the user completes authorization in their browser, and the client retries the same `tools/call` request. There's no transport-level error and no `isError: true`: the gateway treats "authorization needed" as a normal step in the tool call, not a failure. + + + A client that doesn't declare `elicitation.url` still gets the authorization link, but as an ordinary (non-error) tool result: an `authorization_url` field inside `structuredContent`, alongside `message` and `llm_instructions` fields describing what to do next. This matches the result shape Arcade already returns for auth-required tools on `2025-11-25` and `2025-06-18`. + + +## Legacy notes + +- Sessions on `2025-11-25` and `2025-06-18` keep working exactly as before: the gateway issues an `Mcp-Session-Id` on initialize, and later requests carry it. +- `2026-07-28` requests are sessionless, so the gateway ignores any `Mcp-Session-Id` a client happens to send: there's nothing to reuse or terminate. + +## External MCP servers behind gateways + +A `2026-07-28` client works the same way against a gateway whose tools come from an external (non-Arcade) MCP server as it does against one built entirely on Arcade. The gateway translates between the client's protocol version and whatever the backing server speaks, so the version mismatch is invisible to the client. + +## Next steps + +- [Connect to MCP clients](/get-started/mcp-clients) +- [Add remote MCP servers](/guides/mcp-gateways/add-remote-servers) diff --git a/public/llms.txt b/public/llms.txt index d8b90a01e..43caa8123 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -1,4 +1,4 @@ - + # Arcade @@ -142,6 +142,7 @@ Arcade delivers three capabilities. Enforce (Agent Authorization): deploy agents - [Setup Arcade with OpenAI Agents (TypeScript)](https://docs.arcade.dev/en/get-started/agent-frameworks/openai-agents/setup-typescript): This documentation page provides a comprehensive guide for setting up and building AI agents using the OpenAI Agents SDK with Arcade tools in TypeScript. It covers the integration process, including converting Arcade tools to the required format, handling authorization, and executing agent functions. - [Setup Arcade with OpenAI Agents SDK](https://docs.arcade.dev/en/get-started/agent-frameworks/openai-agents/setup-python): This documentation page guides users on how to set up and integrate Arcade tools within OpenAI Agents applications using the OpenAI Agents SDK. It covers the necessary prerequisites, provides step-by-step instructions for creating a CLI agent, and explains how to implement tool authorization - [Stytch](https://docs.arcade.dev/en/guides/user-sources/stytch): Documentation page +- [Supported MCP protocol versions](https://docs.arcade.dev/en/guides/mcp-gateways/protocol-versions): Documentation page - [The Arcade Registry](https://docs.arcade.dev/en/resources/registry-early-access): The Arcade Registry documentation provides an overview of a platform where developers can share and monetize their tools for agentic applications, similar to HuggingFace or Pypi. It explains how the registry integrates runtime metrics and user feedback to enhance tool development and usage - [Tool error handling](https://docs.arcade.dev/en/guides/tool-calling/error-handling): This documentation page provides guidance on effectively handling errors when using tools with Arcade's Tool Development Kit (TDK). It explains the error handling philosophy, outlines best practices, and offers code examples for managing output errors in various programming languages. Users will learn how - [Tools](https://docs.arcade.dev/en/resources/tools): This documentation page provides an overview of Arcade's ecosystem for AI tools, enabling users to explore a catalog of pre-built integrations, create custom tools, and contribute their own tools to the community. It outlines the benefits of using Arcade tools, such as built