Remote MCP - Portkey Docs

Model Context Protocol (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:

Portkey Gateway execution — Prefix the MCP server with @portkey-mcp in the Responses API or Messages API, and send the following header x-portkey-beta: server-side-mcp-2026-06-01. Portkey fetches and executes tools on your behalf. See Beta Features for the full header reference.
Provider execution — Pass a server_url directly in the OpenAI or 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 to learn how to handle tool fetching and invocations on the client side.

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.

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": [
        {
            "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"
}'

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",
    portkeyBeta: "server-side-mcp-2026-06-01",
  })
});

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);

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",
    portkeyBeta="server-side-mcp-2026-06-01",
  )
)

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)

import Portkey from 'portkey-ai';

const portkey = new Portkey({
  apiKey: "PORTKEY_API_KEY",
  provider: "@your-provider-slug",
  portkeyBeta: "server-side-mcp-2026-06-01"
});

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);

from portkey_ai import Portkey

portkey = Portkey(
  api_key="PORTKEY_API_KEY",
  provider="@your-provider-slug",
  portkey_beta="server-side-mcp-2026-06-01"
)

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.

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": [
        {
            "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
}'

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  apiKey: "PORTKEY_API_KEY",
  baseURL: "https://api.portkey.ai",
  defaultHeaders: {
    "x-portkey-beta": "server-side-mcp-2026-06-01"
  }
})

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)

import anthropic

client = anthropic.Anthropic(
  api_key="dummy",
  default_headers={
    "x-portkey-api-key": "PORTKEY_API_KEY",
    "x-portkey-beta": "server-side-mcp-2026-06-01"
  },
  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.

curl https://api.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{
    "model": "@OPENAI_PROVIDER/gpt-4.1",
    "tools": [
      {
        "type": "mcp",
        "server_label": "deepwiki",
        "server_url": "https://mcp.deepwiki.com/mcp",
        "require_approval": "never"
      }
    ],
    "input": "What transport protocols are supported in the 2025-03-26 version of the MCP spec?"
  }'

import OpenAI from "openai";
import { PORTKEY_GATEWAY_URL, createHeaders } from 'portkey-ai'

const client = new OpenAI({
  apiKey: "PORTKEY_API_KEY",
  baseURL: PORTKEY_GATEWAY_URL
});

const resp = await client.responses.create({
  model: "@OPENAI_PROVIDER/gpt-4.1",
  tools: [
    {
      type: "mcp",
      server_label: "deepwiki",
      server_url: "https://mcp.deepwiki.com/mcp",
      require_approval: "never",
    },
  ],
  input: "What transport protocols are supported in the 2025-03-26 version of the MCP spec?",
});

console.log(resp.output_text);

from openai import OpenAI
from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders

client = OpenAI(
  api_key="PORTKEY_API_KEY",
  base_url=PORTKEY_GATEWAY_URL,
)

resp = client.responses.create(
  model="@OPENAI_PROVIDER/gpt-4.1",
  tools=[
    {
      "type": "mcp",
      "server_label": "deepwiki",
      "server_url": "https://mcp.deepwiki.com/mcp",
      "require_approval": "never",
    },
  ],
  input="What transport protocols are supported in the 2025-03-26 version of the MCP spec?",
)

print(resp.output_text)

import Portkey from 'portkey-ai';

const portkey = new Portkey({
  apiKey: "PORTKEY_API_KEY"
});

const resp = await portkey.responses.create({
  model: "@OPENAI_PROVIDER/gpt-4.1",
  tools: [
    {
      type: "mcp",
      server_label: "deepwiki",
      server_url: "https://mcp.deepwiki.com/mcp",
      require_approval: "never",
    },
  ],
  input: "What transport protocols are supported in the 2025-03-26 version of the MCP spec?",
});

console.log(resp.output_text);

from portkey_ai import Portkey

portkey = Portkey(
  api_key="PORTKEY_API_KEY"
)

resp = portkey.responses.create(
  model="@OPENAI_PROVIDER/gpt-4.1",
  tools=[
    {
      "type": "mcp",
      "server_label": "deepwiki",
      "server_url": "https://mcp.deepwiki.com/mcp",
      "require_approval": "never",
    },
  ],
  input="What transport protocols are supported in the 2025-03-26 version of the MCP spec?",
)

print(resp.output_text)

MCP Server Authentication

Unlike the DeepWiki MCP server, most other MCP servers require authentication. The MCP tool in the Responses API gives you the ability to flexibly specify headers that should be included in any request made to a remote MCP server. These headers can be used to share API keys, oAuth access tokens, or any other authentication scheme the remote MCP server implements. you can pass additional headers in the headers object or the oauth token in the authorization key. Use Stripe MCP tool

curl https://api.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{
    "model": "@OPENAI_PROVIDER/gpt-4.1",
    "input": "Create a payment link for $20",
    "tools": [
      {
        "type": "mcp",
        "server_label": "stripe",
        "server_url": "https://mcp.stripe.com",
        "headers": {
          "Authorization": "Bearer $STRIPE_API_KEY"
        }
      }
    ]
  }'

import OpenAI from "openai";
import { PORTKEY_GATEWAY_URL } from 'portkey-ai'

const client = new OpenAI({
  apiKey: "PORTKEY_API_KEY",
  baseURL: PORTKEY_GATEWAY_URL
});

const resp = await client.responses.create({
  model: "@OPENAI_PROVIDER/gpt-4.1",
  input: "Create a payment link for $20",
  tools: [
    {
      type: "mcp",
      server_label: "stripe",
      server_url: "https://mcp.stripe.com",
      headers: {
        Authorization: "Bearer $STRIPE_API_KEY"
      }
    }
  ]
});

console.log(resp.output_text);

from openai import OpenAI
from portkey_ai import PORTKEY_GATEWAY_URL

client = OpenAI(
  api_key="PORTKEY_API_KEY",
  base_url=PORTKEY_GATEWAY_URL
)

resp = client.responses.create(
  model="@OPENAI_PROVIDER/gpt-4.1",
  input="Create a payment link for $20",
  tools=[
    {
      "type": "mcp",
      "server_label": "stripe",
      "server_url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer $STRIPE_API_KEY"
      }
    }
  ]
)

print(resp.output_text)

import Portkey from 'portkey-ai';

const portkey = new Portkey({
  apiKey: "PORTKEY_API_KEY"
});

const resp = await portkey.responses.create({
  model: "@OPENAI_PROVIDER/gpt-4.1",
  input: "Create a payment link for $20",
  tools: [
    {
      type: "mcp",
      server_label: "stripe",
      server_url: "https://mcp.stripe.com",
      headers: {
        Authorization: "Bearer $STRIPE_API_KEY"
      }
    }
  ]
});

console.log(resp.output_text);

from portkey_ai import Portkey

portkey = Portkey(
  api_key="PORTKEY_API_KEY"
)

resp = portkey.responses.create(
  model="@OPENAI_PROVIDER/gpt-4.1",
  input="Create a payment link for $20",
  tools=[
    {
      "type": "mcp",
      "server_label": "stripe",
      "server_url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer $STRIPE_API_KEY"
      }
    }
  ]
)

print(resp.output_text)

To prevent the leakage of sensitive keys, the Responses API does not store the values of any string you provide in the headers object. These values will also not be visible in the Response object created. Additionally, because some remote MCP servers generate authenticated URLs, we also discard the path portion of the server_url in our responses (i.e. example.com/mcp becomes example.com). Because of this, you must send the full path of the MCP server_url and any relevant headers in every Responses API creation request you make.

Using MCP Servers Registered on Portkey

If you have MCP servers registered on Portkey’s MCP Gateway, you can connect to them through the Responses API by passing the appropriate authentication in the tool definition.

No-auth or header-based auth servers: Pass your Portkey API key as x-portkey-api-key inside the headers object.
OAuth-based servers: Pass the OAuth access token using the authorization field on the tool.

Header-based auth (or no auth)

{
  "model": "@OPENAI_PROVIDER/gpt-4.1",
  "tools": [
    {
      "type": "mcp",
      "server_label": "dmcp",
      "server_description": "deepwiki mcp",
      "server_url": "https://mcp.portkey.ai/deepwiki/mcp",
      "headers": {
        "x-portkey-api-key": "{{PORTKEY_API_KEY}}"
      },
      "require_approval": "never"
    }
  ],
  "input": "what is portkey gateway"
}

OAuth-based auth

{
  "model": "@OPENAI_PROVIDER/gpt-4.1",
  "tools": [
    {
      "type": "mcp",
      "server_label": "dmcp",
      "server_description": "deepwiki mcp",
      "server_url": "https://mcp.portkey.ai/deepwiki/mcp",
      "authorization": "{{OAUTH_TOKEN}}",
      "require_approval": "never"
    }
  ],
  "input": "what is portkey gateway"
}

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.

This feature requires the beta header: "anthropic-beta": "mcp-client-2025-04-04"

Key features

Direct API integration: Connect to MCP servers without implementing an MCP client
Tool calling support: Access MCP tools through the Messages API
OAuth authentication: Support for OAuth Bearer tokens for authenticated servers
Multiple servers: Connect to multiple MCP servers in a single request

Using the MCP connector in the Messages API

To connect to a remote MCP server, include the mcp_servers parameter in your Messages API request:

curl https://api.portkey.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dummy" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-04-04" \
  -H "x-portkey-api-key: PORTKEY_API_KEY" \
  -d '{
    "model": "@your-provider-slug/your-model-name",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "What tools do you have available?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ]
  }'

const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1000,
  messages: [
    {
      role: "user",
      content: "What tools do you have available?",
    },
  ],
  mcp_servers: [
    {
      type: "url",
      url: "https://example-server.modelcontextprotocol.io/sse",
      name: "example-mcp",
      authorization_token: "YOUR_TOKEN",
    },
  ],
  betas: ["mcp-client-2025-04-04"],
});

response = anthropic.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1000,
    messages=[{
        "role": "user",
        "content": "What tools do you have available?"
    }],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.example.com/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
    }],
    betas=["mcp-client-2025-04-04"]
)

  Coming soon!

  Coming soon!

MCP server configuration Each MCP server in the mcp_servers array supports the following configuration:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "tool_configuration": {
    "enabled": true,
    "allowed_tools": ["example_tool_1", "example_tool_2"]
  },
  "authorization_token": "YOUR_TOKEN"
}

Field descriptions

Property	Type	Required	Description
`type`	string	Yes	Currently only “url” is supported
`url`	string	Yes	The URL of the MCP server. Must start with https://
`name`	string	Yes	A unique identifier for this MCP server. It will be used in `mcp_tool_call` blocks to identify the server and to disambiguate tools to the model.
`tool_configuration`	object	No	Configure tool usage
`tool_configuration.enabled`	boolean	No	Whether to enable tools from this server (default: true)
`tool_configuration.allowed_tools`	array	No	List to restrict the tools to allow (by default, all tools are allowed)
`authorization_token`	string	No	OAuth authorization token if required by the MCP server. See MCP specification.

Response content types

When Claude uses MCP tools, the response will include two new content block types:

MCP Tool Use Block

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

MCP Tool Result Block

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

MCP Server Authentication

For MCP servers that require OAuth authentication, you’ll need to obtain an access token. The MCP connector beta supports passing an authorization_token parameter in the MCP server definition. API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, as well as refreshing the token as needed.

Obtaining an access token for testing

The MCP inspector can guide you through the process of obtaining an access token for testing purposes.

Run the inspector with the following command. You need Node.js installed on your machine.
```
npx @modelcontextprotocol/inspector
```
In the sidebar on the left, for “Transport type”, select either “SSE” or “Streamable HTTP”.
Enter the URL of the MCP server.
In the right area, click on the “Open Auth Settings” button after “Need to configure authentication?”.
Click “Quick OAuth Flow” and authorize on the OAuth screen.
Follow the steps in the “OAuth Flow Progress” section of the inspector and click “Continue” until you reach “Authentication complete”.
Copy the access_token value.
Paste it into the authorization_token field in your MCP server configuration.

Using the access token

Once you’ve obtained an access token using either OAuth flow above, you can use it in your MCP server configuration:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

For detailed explanations of the OAuth flow, refer to the Authorization section in the MCP specification.

​Two Ways to Use Remote MCP

​Responses API

​Messages API

​OpenAI

​MCP Server Authentication

​Using MCP Servers Registered on Portkey

​Header-based auth (or no auth)

​OAuth-based auth

​Anthropic

​Using the MCP connector in the Messages API

Field descriptions

​Response content types

MCP Tool Use Block

MCP Tool Result Block

​MCP Server Authentication

Obtaining an access token for testing

Using the access token

Two Ways to Use Remote MCP

Responses API

Messages API

OpenAI

MCP Server Authentication

Using MCP Servers Registered on Portkey

Header-based auth (or no auth)

OAuth-based auth

Anthropic

Using the MCP connector in the Messages API

Response content types

MCP Server Authentication