Remote MCP

Portkey’s AI gateway has MCP server support that many foundational model providers offer.

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:

1. Portkey Gateway execution — Prefix the MCP server with @portkey-mcp in the Responses API or Messages API. Portkey fetches and executes tools on your behalf.
2. 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

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"
}'

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

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
}'

OpenAI

A Responses API request to OpenAI with MCP tools enabled.

cURL

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?"
  }'

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

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"
        }
      }
    ]
  }'

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

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"
      }
    ]
  }'

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.

1. Run the inspector with the following command. You need Node.js installed on your machine.

   npx @modelcontextprotocol/inspector
   

2. In the sidebar on the left, for “Transport type”, select either “SSE” or “Streamable HTTP”.

3. Enter the URL of the MCP server.

4. In the right area, click on the “Open Auth Settings” button after “Need to configure authentication?”.

5. Click “Quick OAuth Flow” and authorize on the OAuth screen.

6. Follow the steps in the “OAuth Flow Progress” section of the inspector and click “Continue” until you reach “Authentication complete”.

7. Copy the access_token value.

8. 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.