> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```yaml theme={null}
binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        cors:
          allowOrigins:
          - '*'
          allowHeaders:
          - mcp-protocol-version
          - content-type
          exposeHeaders:
          - Mcp-Session-Id
```

## Fields

<ParamField body="cors" type="object">
  CORS policy configuration.

  <Expandable title="cors fields">
    <ParamField body="cors.allowOrigins" type="string[]">
      List of origins permitted to make cross-origin requests. Use `*` to allow all origins. Each value is matched against the `Origin` request header.

      ```yaml theme={null}
      cors:
        allowOrigins:
        - https://app.example.com
        - https://dashboard.example.com
      ```

      To allow any origin:

      ```yaml theme={null}
      cors:
        allowOrigins:
        - '*'
      ```
    </ParamField>

    <ParamField body="cors.allowHeaders" type="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:

      ```yaml theme={null}
      cors:
        allowHeaders:
        - mcp-protocol-version
        - content-type
        - authorization
      ```
    </ParamField>

    <ParamField body="cors.allowMethods" type="string[]">
      List of HTTP methods permitted for cross-origin requests. Set in the `Access-Control-Allow-Methods` response header.

      ```yaml theme={null}
      cors:
        allowMethods:
        - GET
        - POST
        - OPTIONS
      ```
    </ParamField>

    <ParamField body="cors.allowCredentials" type="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.

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

      ```yaml theme={null}
      cors:
        allowCredentials: true
        allowOrigins:
        - https://app.example.com
      ```
    </ParamField>

    <ParamField body="cors.exposeHeaders" type="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:

      ```yaml theme={null}
      cors:
        exposeHeaders:
        - Mcp-Session-Id
      ```
    </ParamField>

    <ParamField body="cors.maxAge" type="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.

      ```yaml theme={null}
      cors:
        maxAge: "3600"
      ```
    </ParamField>
  </Expandable>
</ParamField>

## Examples

<AccordionGroup>
  <Accordion title="MCP endpoint with permissive CORS">
    Suitable for development or public MCP endpoints:

    ```yaml theme={null}
    policies:
      cors:
        allowOrigins:
        - '*'
        allowHeaders:
        - mcp-protocol-version
        - content-type
        allowMethods:
        - GET
        - POST
        - OPTIONS
        exposeHeaders:
        - Mcp-Session-Id
    ```
  </Accordion>

  <Accordion title="MCP endpoint with strict CORS and credentials">
    Suitable for production when specific origins are known:

    ```yaml theme={null}
    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"
    ```
  </Accordion>

  <Accordion title="From the mcp-authentication example">
    This is the exact CORS configuration from the MCP authentication example:

    ```yaml theme={null}
    policies:
      cors:
        allowHeaders:
        - mcp-protocol-version
        - content-type
        allowOrigins:
        - '*'
        exposeHeaders:
        - "Mcp-Session-Id"
    ```
  </Accordion>
</AccordionGroup>

<Note>
  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.
</Note>