Beta Features

Portkey ships certain new gateway capabilities as opt-in beta features before they are promoted to stable APIs. To activate a beta feature, include the x-portkey-beta header (or the equivalent SDK parameter) in your request with the feature’s version string.

x-portkey-beta: <feature-version-string>

To enable multiple beta features at once, pass a comma-separated list:

x-portkey-beta: feature-one-2026-01-01, feature-two-2026-06-01

Once a feature is promoted to stable, the header becomes a no-op and can be safely removed.

Currently Available Beta Features

Use Responses API for Messages Transforms

Header value: use-responses-api-2026-07-30 Disables the automatic transformation of /v1/messages requests to Chat Completions format for providers that don’t natively support the Messages API. When this flag is set, requests are routed through the Responses API adapter instead. When to use it

You want to use the Responses API format internally while still calling the /v1/messages endpoint
You need consistency with Responses API behavior across all your requests
You’re migrating from Messages API to Responses API and want to test the behavior without changing endpoints

How it works By default, when you send a /v1/messages request to a provider that doesn’t natively support Anthropic’s Messages format (like OpenAI, Gemini, Bedrock, etc.), Portkey automatically transforms it to the Chat Completions format. With this beta flag enabled, that transformation is skipped and the request is handled by the Responses API adapter instead. How to send the header

curl https://api.portkey.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-beta: use-responses-api-2026-07-30" \
  -d '{
    "model": "@openai-provider/gpt-4.1",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

import anthropic

client = anthropic.Anthropic(
  api_key="PORTKEY_API_KEY",
  base_url="https://api.portkey.ai",
  default_headers={
    "x-portkey-beta": "use-responses-api-2026-07-30"
  }
)

message = client.messages.create(
  model="@openai-provider/gpt-4.1",
  max_tokens=1024,
  messages=[{"role": "user", "content": "Hello!"}]
)

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: "PORTKEY_API_KEY",
  baseURL: "https://api.portkey.ai",
  defaultHeaders: {
    "x-portkey-beta": "use-responses-api-2026-07-30"
  }
});

const message = await client.messages.create({
  model: "@openai-provider/gpt-4.1",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }]
});

See the Messages API guide for more on using the Messages format across providers, and the Responses API guide for the Responses API specification.

Server-Side MCP Execution

Header value: server-side-mcp-2026-06-01 Enables Portkey to fetch and execute MCP tools on your behalf — directly inside the gateway — rather than delegating execution to the upstream provider. This is required whenever you use the @portkey-mcp prefix in the Responses API or Messages API. When to use it

You are routing through a provider that does not natively support remote MCP tool execution (e.g. AWS Bedrock, Google Vertex AI).
You want MCP credentials and tool invocations to stay within your own VPC and never touch provider infrastructure.
You need per-user attribution, audit logs, and full observability over every MCP tool call.

How to send the header

curl https://api.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-beta: server-side-mcp-2026-06-01" \
  -d '{
    "model": "@your-provider-slug/your-model",
    "tools": [
      {
        "type": "mcp",
        "server_label": "@portkey-mcp/your-mcp-server-label"
      }
    ],
    "input": "your prompt here"
  }'

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",
  }),
});

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

import Portkey from "portkey-ai";

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

from portkey_ai import Portkey

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

See the full Remote MCP guide for complete request examples, authentication options, and a comparison of Portkey-side vs provider-side MCP execution.

SDK Parameter Reference

The x-portkey-beta HTTP header maps to the following SDK parameters:

SDK	Parameter name
Portkey Node SDK	`portkeyBeta`
Portkey Python SDK	`portkey_beta`
OpenAI Node SDK (via `createHeaders`)	`portkeyBeta`
OpenAI Python SDK (via `createHeaders`)	`portkey_beta`
Anthropic Node SDK	`defaultHeaders: {"x-portkey-beta": "..."}`
Anthropic Python SDK	`default_headers={"x-portkey-beta": "..."}`
cURL / raw HTTP	`x-portkey-beta` header

Beta features may change before they are promoted to stable. Breaking changes within the same beta version string will not be made, but the stable API may look different. Check the changelog for updates.

Introduction

Product

Self-Hosting

Support

Currently Available Beta Features

Use Responses API for Messages Transforms

Server-Side MCP Execution

SDK Parameter Reference

​Currently Available Beta Features

​Use Responses API for Messages Transforms

​Server-Side MCP Execution

​SDK Parameter Reference

Currently Available Beta Features

Use Responses API for Messages Transforms

Server-Side MCP Execution

SDK Parameter Reference