CORS

Reference for the CORS policy — Cross-Origin Resource Sharing header management and preflight handling.

The cors policy handles CORS preflight requests and appends configured CORS headers to applicable responses. This is required when MCP clients running in browsers (such as web-based AI agents) need to call Agentgateway from a different origin.

cors is configured under binds[].listeners[].routes[].policies:

binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        cors:
          allowOrigins:
          - '*'
          allowHeaders:
          - mcp-protocol-version
          - content-type
          exposeHeaders:
          - Mcp-Session-Id

Fields

cors · object

CORS policy configuration.

Show cors fields

cors.allowOrigins · string[]

List of origins permitted to make cross-origin requests. Use * to allow all origins. Each value is matched against the Origin request header.

cors:
  allowOrigins:
  - https://app.example.com
  - https://dashboard.example.com

To allow any origin:

cors:
  allowOrigins:
  - '*'

cors.allowHeaders · string[]

List of request headers that browsers are permitted to send in cross-origin requests. Set in the Access-Control-Allow-Headers response header.

Common headers to include for MCP:

cors:
  allowHeaders:
  - mcp-protocol-version
  - content-type
  - authorization

cors.allowMethods · string[]

List of HTTP methods permitted for cross-origin requests. Set in the Access-Control-Allow-Methods response header.

cors:
  allowMethods:
  - GET
  - POST
  - OPTIONS

cors.allowCredentials · boolean

When true, includes Access-Control-Allow-Credentials: true in CORS responses. Required when the browser needs to send cookies or Authorization headers with cross-origin requests.

Do not combine allowCredentials: true with allowOrigins: ['*']. Browsers reject credentialed requests when the allowed origin is a wildcard.

cors:
  allowCredentials: true
  allowOrigins:
  - https://app.example.com

cors.exposeHeaders · string[]

List of response headers that browsers are permitted to access in JavaScript. Set in the Access-Control-Expose-Headers response header.

For MCP, expose the session header so clients can track their session:

cors:
  exposeHeaders:
  - Mcp-Session-Id

cors.maxAge · string

How long (in seconds) browsers may cache the preflight response. Reduces the number of preflight requests sent by browsers. Set in the Access-Control-Max-Age response header.

cors:
  maxAge: "3600"

Examples

MCP endpoint with permissive CORS

Suitable for development or public MCP endpoints:

policies:
  cors:
    allowOrigins:
    - '*'
    allowHeaders:
    - mcp-protocol-version
    - content-type
    allowMethods:
    - GET
    - POST
    - OPTIONS
    exposeHeaders:
    - Mcp-Session-Id

MCP endpoint with strict CORS and credentials

Suitable for production when specific origins are known:

policies:
  cors:
    allowOrigins:
    - https://app.example.com
    - https://dashboard.example.com
    allowHeaders:
    - mcp-protocol-version
    - content-type
    - authorization
    allowMethods:
    - GET
    - POST
    allowCredentials: true
    exposeHeaders:
    - Mcp-Session-Id
    maxAge: "3600"

From the mcp-authentication example

This is the exact CORS configuration from the MCP authentication example:

policies:
  cors:
    allowHeaders:
    - mcp-protocol-version
    - content-type
    allowOrigins:
    - '*'
    exposeHeaders:
    - "Mcp-Session-Id"

Agentgateway automatically handles CORS preflight (OPTIONS) requests and appends the configured headers to all applicable responses. You do not need to configure a separate route for OPTIONS requests.