From 9e990aea53a3eb30676ff9407daebaccb93dbd0f Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni Date: Wed, 20 May 2026 17:52:47 +0530 Subject: [PATCH 1/7] add documentation for portkey remote mcp --- product/ai-gateway/remote-mcp.mdx | 264 ++++++++++++++++++++++++++++-- 1 file changed, 250 insertions(+), 14 deletions(-) diff --git a/product/ai-gateway/remote-mcp.mdx b/product/ai-gateway/remote-mcp.mdx index f72a2cf2..e2d8f9e5 100644 --- a/product/ai-gateway/remote-mcp.mdx +++ b/product/ai-gateway/remote-mcp.mdx @@ -12,7 +12,254 @@ description: Portkey's AI gateway has MCP server support that many foundational Portkey Supports using MCP server via the Response API. Calling a remote MCP server with the Responses API is straightforward. For example, here's how you can use the [DeepWiki](https://deepwiki.com/) MCP server to ask questions about nearly any public GitHub repository. -## OpenAI Responses API Remote MCP Support +## Responses API +When using upstream inference providers like bedrock, vertex-ai that do not support executing MCP tools remotely, you can pass the prefix `@portkey-mcp` to the mcp tool server_label to execute the tool securely on the gateway and receive the response back from the gateway. + + +fields in the mcp tool object like `server_description`, `server_url`, `require_approval` are not supported when using the `@portkey-mcp` prefix. +they are ignored if passed + + + +```bash cURL +curl --location 'https://api.portkey.ai/v1/responses' \ +--header 'Content-Type: application/json' \ +--header 'x-portkey-provider: @your-provider-slug' \ +--header 'x-portkey-api-key: $PORTKEY_API_KEY' \ +--data-raw '{ + "model": "gpt-5.5", + "tools": [ + { + "type": "mcp", + "server_label": "@portkey-mcp/your-mcp-server-label", + "allowed_tools": ["tool_name_1", "tool_name_2"] // Optional, default is all tools + } + ], + "input": "what is portkey gateway" +}' +``` + +```javascript OpenAI Node SDK +import OpenAI from "openai"; +import { PORTKEY_GATEWAY_URL, createHeaders } from 'portkey-ai' + +const client = new OpenAI({ + apiKey: "PORTKEY_API_KEY", + baseURL: PORTKEY_GATEWAY_URL, + defaultHeaders: createHeaders({ + provider: "@your-provider-slug" + }) +}); + +const resp = await client.responses.create({ + model: "gpt-5.5", + tools: [ + { + type: "mcp", + server_label: "@portkey-mcp/your-mcp-server-label", + allowed_tools: ["tool_name_1", "tool_name_2"], // Optional, default is all tools + }, + ], + input: "what is portkey gateway", +}); + +console.log(resp.output_text); +``` + +```python OpenAI Python SDK +from openai import OpenAI +from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders + +client = OpenAI( + api_key="PORTKEY_API_KEY", + base_url=PORTKEY_GATEWAY_URL, + default_headers=createHeaders( + provider="@your-provider-slug" + ) +) + +resp = client.responses.create( + model="gpt-5.5", + tools=[ + { + "type": "mcp", + "server_label": "@portkey-mcp/your-mcp-server-label", + "allowed_tools": ["tool_name_1", "tool_name_2"], # Optional, default is all tools + }, + ], + input="what is portkey gateway", +) + +print(resp.output_text) +``` + +```typescript Portkey Node SDK +import Portkey from 'portkey-ai'; + +const portkey = new Portkey({ + apiKey: "PORTKEY_API_KEY", + provider: "@your-provider-slug" +}); + +const resp = await portkey.responses.create({ + model: "gpt-5.5", + tools: [ + { + type: "mcp", + server_label: "@portkey-mcp/your-mcp-server-label", + allowed_tools: ["tool_name_1", "tool_name_2"], // Optional, default is all tools + }, + ], + input: "what is portkey gateway", +}); + +console.log(resp.output_text); +``` + +```python Portkey Python SDK +from portkey_ai import Portkey + +portkey = Portkey( + api_key="PORTKEY_API_KEY", + provider="@your-provider-slug" +) + +resp = portkey.responses.create( + model="gpt-5.5", + tools=[ + { + "type": "mcp", + "server_label": "@portkey-mcp/your-mcp-server-label", + "allowed_tools": ["tool_name_1", "tool_name_2"], # Optional, default is all tools + }, + ], + input="what is portkey gateway", +) + +print(resp.output_text) +``` + + + +## Messages API +When using upstream inference providers like bedrock, vertex-ai that do not support executing MCP tools remotely, you can pass the prefix `@portkey-mcp` to the mcp tool mcp_server_name to execute the tool securely on the gateway and receive the response back from the gateway. + + +```bash cURL +curl --location 'https://api.portkey.ai/v1/messages' \ +--header 'Content-Type: application/json' \ +--header 'x-portkey-api-key: $PORTKEY_API_KEY' \ +--data-raw '{ + "messages": [ + { + "role": "user", + "content": "what is Portkey-AI gateway repository?" + } + ], + "model": "@anthropic/claude-haiku-4-5", + "max_tokens": 10000, + "mcp_servers": [ + { + "type": "url", + "url": "https://mcp.portkey.ai/server-name/mcp", // not required when using @portkey-mcp + "name": "@portkey-mcp/deepwiki" + } + ], + "tools": { + "type": "mcp_toolset", + "mcp_server_name": "@portkey-mcp/deepwiki", + "default_config": { + "enabled": true + }, + "configs": { + "specific_tool_name": { + "enabled": true + } + } + }, + "stream": false +}' +``` + +```javascript Anthropic JS SDK +import Anthropic from '@anthropic-ai/sdk' + +const client = new Anthropic({ + apiKey: "PORTKEY_API_KEY", + baseURL: "https://api.portkey.ai" +}) + +const message = await client.messages.create({ + model: "@anthropic/claude-haiku-4-5", + max_tokens: 10000, + messages: [{ + role: "user", + content: "what is Portkey-AI gateway repository?" + }], + mcp_servers: [{ + type: "url", + name: "@portkey-mcp/deepwiki", + // url not required when using @portkey-mcp + }], + tools: { + type: "mcp_toolset", + mcp_server_name: "@portkey-mcp/deepwiki", + default_config: { + enabled: true + }, + configs: { + specific_tool_name: { + enabled: true + } + } + }, + stream: false +}) + +console.log(message.content) +``` + +```python Anthropic Python SDK +import anthropic + +client = anthropic.Anthropic( + api_key="dummy", + default_headers={"x-portkey-api-key": "PORTKEY_API_KEY"}, + base_url="https://api.portkey.ai" +) + +message = client.messages.create( + model="@anthropic/claude-haiku-4-5", + max_tokens=10000, + messages=[{ + "role": "user", + "content": "what is Portkey-AI gateway repository?" + }], + mcp_servers=[{ + "type": "url", + "name": "@portkey-mcp/deepwiki", + # url not required when using @portkey-mcp + }], + tools={ + "type": "mcp_toolset", + "mcp_server_name": "@portkey-mcp/deepwiki", + "default_config": { + "enabled": True + }, + "configs": { + "specific_tool_name": { + "enabled": True + } + } + }, + stream=False +) + +print(message.content) +``` + + +## OpenAI A Responses API request to OpenAI with MCP tools enabled. @@ -323,19 +570,7 @@ If you have MCP servers registered on Portkey's [MCP Gateway](/product/mcp-gatew ``` - - - - - - - - - - - - -## Anthropic's Messages API MCP connector +## Anthropic Claude's Model Context Protocol (MCP) connector feature enables you to connect to remote MCP servers directly from the Messages API without a separate MCP client. @@ -565,5 +800,6 @@ For detailed explanations of the OAuth flow, refer to the [Authorization section + From 776bee81564d94388a12ba6cb5e9420ffbdd750a Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni Date: Wed, 20 May 2026 18:03:27 +0530 Subject: [PATCH 2/7] add comparison table for portkey mcp execution vs provider mcp execution --- product/ai-gateway/remote-mcp.mdx | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/product/ai-gateway/remote-mcp.mdx b/product/ai-gateway/remote-mcp.mdx index e2d8f9e5..dd863823 100644 --- a/product/ai-gateway/remote-mcp.mdx +++ b/product/ai-gateway/remote-mcp.mdx @@ -5,13 +5,24 @@ description: Portkey's AI gateway has MCP server support that many foundational [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open protocol that standardizes how applications provide tools and context to LLMs. The MCP tool in the Responses API allows developers to give the model access to tools hosted on **Remote MCP servers**. These are MCP servers maintained by developers and organizations across the internet that expose these tools to MCP clients, like the Responses API. +## Two Ways to Use Remote MCP + +There are two ways to connect remote MCP servers through Portkey: + +1. **Portkey Gateway execution** — Prefix the MCP server with `@portkey-mcp` in the [Responses API](#responses-api) or [Messages API](#messages-api). Portkey fetches and executes tools on your behalf. +2. **Provider execution** — Pass a `server_url` directly in the [OpenAI](#openai) or [Anthropic](#anthropic) sections below. The upstream provider connects to and executes MCP tools on their servers. + +| | **Portkey Gateway (`@portkey-mcp`)** | **Provider Execution (`server_url`)** | +| --- | --- | --- | +| **Where tools run** | Securely within your own VPC | On provider servers (OpenAI, Anthropic, etc.) | +| **Data exposure** | MCP credentials stay in your environment | Tokens may be exposed to provider training data and audit pipelines | +| **User attribution** | Actions attributed via your service/user API key | No per-user attribution | +| **Audit & logging** | MCP executions logged and available for audit | No execution logging or security controls | + **Using a Private MCP Server?** If your MCP server is behind a firewall, on localhost, or not publicly accessible, the model provider won't be able to reach it. Check out our guide on [Using Private MCP Servers](/guides/use-cases/private-mcp-servers) to learn how to handle tool fetching and invocations on the client side. -Portkey Supports using MCP server via the Response API. Calling a remote MCP server with the Responses API is straightforward. For example, here's how you can use the [DeepWiki](https://deepwiki.com/) MCP server to ask questions about nearly any public GitHub repository. - - ## Responses API When using upstream inference providers like bedrock, vertex-ai that do not support executing MCP tools remotely, you can pass the prefix `@portkey-mcp` to the mcp tool server_label to execute the tool securely on the gateway and receive the response back from the gateway. From dccfe8683d323554d1866ee0dbd8bb35c961009a Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni <47327611+narengogi@users.noreply.github.com> Date: Tue, 30 Jun 2026 11:52:11 +0530 Subject: [PATCH 3/7] Update remote-mcp.mdx --- product/ai-gateway/remote-mcp.mdx | 51 +++++++++++-------------------- 1 file changed, 17 insertions(+), 34 deletions(-) diff --git a/product/ai-gateway/remote-mcp.mdx b/product/ai-gateway/remote-mcp.mdx index dd863823..12246a87 100644 --- a/product/ai-gateway/remote-mcp.mdx +++ b/product/ai-gateway/remote-mcp.mdx @@ -9,7 +9,7 @@ description: Portkey's AI gateway has MCP server support that many foundational There are two ways to connect remote MCP servers through Portkey: -1. **Portkey Gateway execution** — Prefix the MCP server with `@portkey-mcp` in the [Responses API](#responses-api) or [Messages API](#messages-api). Portkey fetches and executes tools on your behalf. +1. **Portkey Gateway execution** — Prefix the MCP server with `@portkey-mcp` in the [Responses API](#responses-api) or [Messages API](#messages-api), and send the following header `x-portkey-beta: server-side-mcp-2026-06-01` Portkey fetches and executes tools on your behalf. 2. **Provider execution** — Pass a `server_url` directly in the [OpenAI](#openai) or [Anthropic](#anthropic) sections below. The upstream provider connects to and executes MCP tools on their servers. | | **Portkey Gateway (`@portkey-mcp`)** | **Provider Execution (`server_url`)** | @@ -37,6 +37,7 @@ curl --location 'https://api.portkey.ai/v1/responses' \ --header 'Content-Type: application/json' \ --header 'x-portkey-provider: @your-provider-slug' \ --header 'x-portkey-api-key: $PORTKEY_API_KEY' \ +--header 'x-portkey-beta: server-side-mcp-2026-06-01' \ --data-raw '{ "model": "gpt-5.5", "tools": [ @@ -59,6 +60,7 @@ const client = new OpenAI({ baseURL: PORTKEY_GATEWAY_URL, defaultHeaders: createHeaders({ provider: "@your-provider-slug" + portkeyBeta: "server-side-mcp-2026-06-01" }) }); @@ -86,6 +88,7 @@ client = OpenAI( base_url=PORTKEY_GATEWAY_URL, default_headers=createHeaders( provider="@your-provider-slug" + portkeyBeta="server-side-mcp-2026-06-01" ) ) @@ -109,7 +112,8 @@ import Portkey from 'portkey-ai'; const portkey = new Portkey({ apiKey: "PORTKEY_API_KEY", - provider: "@your-provider-slug" + provider: "@your-provider-slug", + portkeyBeta: "server-side-mcp-2026-06-01" }); const resp = await portkey.responses.create({ @@ -132,7 +136,8 @@ from portkey_ai import Portkey portkey = Portkey( api_key="PORTKEY_API_KEY", - provider="@your-provider-slug" + provider="@your-provider-slug", + portkey_beta="server-side-mcp-2026-06-01" ) resp = portkey.responses.create( @@ -160,6 +165,7 @@ When using upstream inference providers like bedrock, vertex-ai that do not supp curl --location 'https://api.portkey.ai/v1/messages' \ --header 'Content-Type: application/json' \ --header 'x-portkey-api-key: $PORTKEY_API_KEY' \ +--header 'x-portkey-beta: server-side-mcp-2026-06-01' \ --data-raw '{ "messages": [ { @@ -197,7 +203,10 @@ import Anthropic from '@anthropic-ai/sdk' const client = new Anthropic({ apiKey: "PORTKEY_API_KEY", - baseURL: "https://api.portkey.ai" + baseURL: "https://api.portkey.ai", + defaultHeaders: { + "x-portkey-beta": "server-side-mcp-2026-06-01" + } }) const message = await client.messages.create({ @@ -235,7 +244,10 @@ import anthropic client = anthropic.Anthropic( api_key="dummy", - default_headers={"x-portkey-api-key": "PORTKEY_API_KEY"}, + default_headers={ + "x-portkey-api-key": "PORTKEY_API_KEY", + "x-portkey-beta": "server-side-mcp-2026-06-01" + }, base_url="https://api.portkey.ai" ) @@ -785,32 +797,3 @@ Once you've obtained an access token using either OAuth flow above, you can use ``` For detailed explanations of the OAuth flow, refer to the [Authorization section](https://modelcontextprotocol.io/docs/concepts/authentication) in the MCP specification. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From b31bae19dccbc8582e623838eda814c77eb4ff02 Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni <47327611+narengogi@users.noreply.github.com> Date: Tue, 30 Jun 2026 12:09:40 +0530 Subject: [PATCH 4/7] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- product/ai-gateway/remote-mcp.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/product/ai-gateway/remote-mcp.mdx b/product/ai-gateway/remote-mcp.mdx index 12246a87..0ea8df01 100644 --- a/product/ai-gateway/remote-mcp.mdx +++ b/product/ai-gateway/remote-mcp.mdx @@ -87,8 +87,8 @@ client = OpenAI( api_key="PORTKEY_API_KEY", base_url=PORTKEY_GATEWAY_URL, default_headers=createHeaders( - provider="@your-provider-slug" - portkeyBeta="server-side-mcp-2026-06-01" + provider="@your-provider-slug", + portkeyBeta="server-side-mcp-2026-06-01", ) ) From 30f2ce3e73876ef79aa9536b477baed417d6c6e7 Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni <47327611+narengogi@users.noreply.github.com> Date: Tue, 30 Jun 2026 12:09:54 +0530 Subject: [PATCH 5/7] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- product/ai-gateway/remote-mcp.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/product/ai-gateway/remote-mcp.mdx b/product/ai-gateway/remote-mcp.mdx index 0ea8df01..4264d60f 100644 --- a/product/ai-gateway/remote-mcp.mdx +++ b/product/ai-gateway/remote-mcp.mdx @@ -59,8 +59,8 @@ const client = new OpenAI({ apiKey: "PORTKEY_API_KEY", baseURL: PORTKEY_GATEWAY_URL, defaultHeaders: createHeaders({ - provider: "@your-provider-slug" - portkeyBeta: "server-side-mcp-2026-06-01" + provider: "@your-provider-slug", + portkeyBeta: "server-side-mcp-2026-06-01", }) }); From 9ea1b0a053c4da534776cb71e05c6ef3600c80b9 Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni <47327611+narengogi@users.noreply.github.com> Date: Tue, 30 Jun 2026 12:10:15 +0530 Subject: [PATCH 6/7] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- product/ai-gateway/remote-mcp.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/product/ai-gateway/remote-mcp.mdx b/product/ai-gateway/remote-mcp.mdx index 4264d60f..05eea1b4 100644 --- a/product/ai-gateway/remote-mcp.mdx +++ b/product/ai-gateway/remote-mcp.mdx @@ -27,8 +27,7 @@ There are two ways to connect remote MCP servers through Portkey: When using upstream inference providers like bedrock, vertex-ai that do not support executing MCP tools remotely, you can pass the prefix `@portkey-mcp` to the mcp tool server_label to execute the tool securely on the gateway and receive the response back from the gateway. -fields in the mcp tool object like `server_description`, `server_url`, `require_approval` are not supported when using the `@portkey-mcp` prefix. -they are ignored if passed +Fields in the MCP tool object like `server_description`, `server_url`, `require_approval` are not supported when using the `@portkey-mcp` prefix; they are ignored if passed. From 4790983eb9388eeb60c2f991f65e33ca9e5c9935 Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni <47327611+narengogi@users.noreply.github.com> Date: Tue, 30 Jun 2026 12:10:26 +0530 Subject: [PATCH 7/7] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- product/ai-gateway/remote-mcp.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product/ai-gateway/remote-mcp.mdx b/product/ai-gateway/remote-mcp.mdx index 05eea1b4..f67c7118 100644 --- a/product/ai-gateway/remote-mcp.mdx +++ b/product/ai-gateway/remote-mcp.mdx @@ -9,7 +9,7 @@ description: Portkey's AI gateway has MCP server support that many foundational There are two ways to connect remote MCP servers through Portkey: -1. **Portkey Gateway execution** — Prefix the MCP server with `@portkey-mcp` in the [Responses API](#responses-api) or [Messages API](#messages-api), and send the following header `x-portkey-beta: server-side-mcp-2026-06-01` Portkey fetches and executes tools on your behalf. +1. **Portkey Gateway execution** — Prefix the MCP server with `@portkey-mcp` in the [Responses API](#responses-api) or [Messages API](#messages-api), and send the following header `x-portkey-beta: server-side-mcp-2026-06-01`. Portkey fetches and executes tools on your behalf. 2. **Provider execution** — Pass a `server_url` directly in the [OpenAI](#openai) or [Anthropic](#anthropic) sections below. The upstream provider connects to and executes MCP tools on their servers. | | **Portkey Gateway (`@portkey-mcp`)** | **Provider Execution (`server_url`)** |