Skip to content

docs: Reorganize CORS documentation #526

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mabuyo merged 3 commits into from
Dec 18, 2025
Merged

docs: Reorganize CORS documentation #526

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8804835
docs: Reorganize CORS documentation
jcaudle Dec 9, 2025
c9e030a
Incorporate review feedback
jcaudle Dec 17, 2025
092fc69
remove filler words
mabuyo Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 46 additions & 70 deletions docs/source/cors.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,68 +1,73 @@
---
title: Configuring CORS
title: Configuring CORS for Apollo MCP Server
---

## Configuring CORS
## Why it matters

Control browser access to your MCP server
When your clients include browsers (for example, Single Page Apps or other browser‑based frontends), you need Cross‑Origin Resource Sharing (CORS) properly configured, otherwise browsers will block requests. Misconfigurations (too permissive or too restrictive) can lead to bugs or security issues. By default, Apollo MCP Server has CORS **disabled**.

Check warning on line 7 in docs/source/cors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/cors.mdx#L7 

Use lowercase for 'single-page apps'. Remove bolding for emphasis. Use active voice and stronger verbs ('must configure', 'cause').

```suggestion
When your clients include browsers (for example, single-page apps or other browser‑based frontends), you must configure Cross‑Origin Resource Sharing (CORS) properly. Otherwise, browsers block requests. Misconfigurations (too permissive or too restrictive) cause bugs or security issues. By default, Apollo MCP Server has CORS disabled.
```

This page shows how to enable and configure CORS for Apollo MCP Server.

---

**This article describes CORS configuration that's specific to Apollo MCP Server**. For a more general introduction to CORS and common considerations, see [MDN's CORS documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).

By default, Apollo MCP Server has CORS disabled. If your MCP server serves tools to browser-based applications, you need to enable CORS and configure one of the following in the `cors` section of your server's YAML config file:

- Add the origins of those web applications to the server's list of allowed `origins`.
- Use this option if there is a known, finite list of web applications that consume your MCP server.
- Add a regex that matches the origins of those web applications to the server's list of allowed `match_origins`.
- This option comes in handy if you want to match origins against a pattern, see the example below that matches subdomains of a specific namespace.
- Enable the `allow_any_origin` option.
- Use this option if your MCP server is a public API with arbitrarily many web app consumers.
- With this option enabled, the server sends the wildcard (\*) value for the `Access-Control-Allow-Origin` header. This enables _any_ website to initiate browser connections to it (but they can't provide cookies or other credentials).
- If clients need to authenticate their requests with cookies, you _must_ use either `origins`, `match_origins`, or the combination of both options. When using both options, note that `origins` is evaluated before `match_origins`.
## Enabling CORS

The following snippet includes an example of each option (use either `allow_any_origin`, or `origins` and/or `match_origins`):
To enable CORS, add a `cors` section to your Apollo MCP Server YAML config file:

```yaml title="mcp.yaml"
transport:
type: streamable_http
port: 8000

cors:
# Enable CORS support
enabled: true
```

# Set to true to allow any origin
# (Defaults to false)
If `enabled` is not set to `true`, all other CORS options are ignored.

Check warning on line 24 in docs/source/cors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/cors.mdx#L24 

Use active voice.

```suggestion
If `enabled` is not set to `true`, Apollo MCP Server ignores all other CORS options.
```

## Configuring allowed origins

You must specify which browser origins are allowed to access your MCP Server.

Check notice on line 28 in docs/source/cors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/cors.mdx#L28 

Use active voice.

```suggestion
You must specify which browser origins can access your MCP Server.
```

### Allow any origin

```yaml title="mcp.yaml"
cors:
enabled: true
allow_any_origin: true
```

# List of accepted origins
# (Ignored if allow_any_origin is true)
#
# An origin is a combination of scheme, hostname and port.
# It does not have any path section, so no trailing slash.
If you set `allow_any_origin` to `true` (the default is `false`), Apollo MCP Server will respond with `Access-Control-Allow-Origin: *` in all CORS responses. This means that _any_ website can initiate browser connections.

Check warning on line 38 in docs/source/cors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/cors.mdx#L38 

Use present tense ('responds'). Remove italics used for emphasis.

```suggestion
If you set `allow_any_origin` to `true` (the default is `false`), Apollo MCP Server responds with `Access-Control-Allow-Origin: *` in all CORS responses. This means that any website can initiate browser connections. 
```

<Note>Clients will not be able to authenticate with your MCP Server if you set `allow_any_origin` to `true`.</Note>

Check notice on line 40 in docs/source/cors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/cors.mdx#L40 

Use present tense.

```suggestion
<Note>Clients cannot authenticate with your MCP Server if you set `allow_any_origin` to `true`.</Note>
```

### Origins

```yaml title="mcp.yaml"
cors:
enabled: true
origins:
- https://www.your-app.example.com

# List of origin patterns (regex matching)
match_origins:
- "^https://([a-z0-9]+[.])*api[.]example[.]com$" # any host that uses https and ends with .api.example.com
- https://staging.your-app.example.com
```

You can also disable CORS entirely by setting `enabled` to `false` or omitting the `cors` section:
Set `origins` to a list of URLs to restrict access to specific servers. Use this option if you have a known list of web applications accessing your MCP server. An origin is a combination of protocol, hostname, and port. Origins do not include a path, so do not include a trailing slash.

Check warning on line 52 in docs/source/cors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/cors.mdx#L52 

Capitalize 'MCP Server' for consistency with other lines. Use 'omit' for a more direct negative instruction.

```suggestion
Set `origins` to a list of URLs to restrict access to specific servers. Use this option if you have a known list of web applications accessing your MCP Server. An origin is a combination of protocol, hostname, and port. Origins do not include a path, so omit any trailing slash.
```

### Match Origins

```yaml title="mcp.yaml"
cors:
enabled: false
enabled: true
match_origins:
- "^http://localhost:\d+$" # Any localhost url from any port
- "^https://([a-z0-9]+[.])*.api.example.com$" # Any host that uses https and is either api.example.com or a subdomain of it
```

If your MCP server serves exclusively _non_-browser-based clients, you probably don't need to enable CORS configuration.
The `match_origins` configuration option allows you to use a regular expression to set endpoints that can interact with your Apollo MCP Server. While `match_origins` can be used with `origins`, it is always evaluated after `origins`.

Check warning on line 64 in docs/source/cors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/cors.mdx#L64 

Use active voice ('server always evaluates'). Avoid 'allows you to'.

```suggestion
Use the `match_origins` configuration option to set endpoints that can interact with your Apollo MCP Server using a regular expression. Although you can use `match_origins` with `origins`, the server always evaluates it after `origins`.
```

### Passing credentials
## Passing credentials

If your MCP server requires requests to include a user's credentials (e.g., via cookies), you need to modify your CORS configuration to tell the browser those credentials are allowed.

You can enable credentials with CORS by setting the Access-Control-Allow-Credentials HTTP header to `true`.
You can enable credentials with CORS by setting the `Access-Control-Allow-Credentials` HTTP header to `true`.

Check notice on line 70 in docs/source/cors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/cors.mdx#L70 

Use imperative verbs for instructions.

```suggestion
Enable credentials with CORS by setting the `Access-Control-Allow-Credentials` HTTP header to `true`.
```

To allow browsers to pass credentials to the server, set `allow_credentials` to `true`, like so:

Expand All @@ -76,7 +81,7 @@

**To support credentialed requests, your server's config file must specify individual `origins` or `match_origins`**. If your server enables `allow_any_origin`, your browser will refuse to send credentials.

### All `cors` options
## All `cors` options

Check notice on line 84 in docs/source/cors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/cors.mdx#L84 

Apply code font to `cors` as it is a configuration symbol.

```suggestion
## All `cors` options
```

The following snippet shows all CORS configuration defaults for Apollo MCP Server:

Expand Down Expand Up @@ -134,38 +139,9 @@
max_age: 7200 # 2 hours
```

### Origin matching

Apollo MCP Server supports two types of origin matching:

#### Exact origins

Use the `origins` array for exact origin matches:

```yaml
cors:
enabled: true
origins:
- http://localhost:3000
- https://myapp.example.com
```

#### Pattern matching

Use the `match_origins` array for regex pattern matching:

```yaml
cors:
enabled: true
match_origins:
- "^https://localhost:[0-9]+$" # Any localhost HTTPS port
- "^http://localhost:[0-9]+$" # Any localhost HTTP port
- "^https://.*\\.example\\.com$" # Any subdomain of example.com
```

### Common configurations
## Common configurations

#### Development setup
### Development setup

For local development with hot reloading and various ports:

Expand All @@ -177,7 +153,7 @@
allow_credentials: true
```

#### Production setup
### Production setup

For production with specific known origins:

Expand All @@ -190,7 +166,7 @@
max_age: 86400 # 24 hours
```

#### Public API setup
### Public API setup

For public APIs that don't require credentials:

Expand All @@ -201,7 +177,7 @@
allow_credentials: false # Cannot use credentials with any origin
```

### Browser integration example
## Browser integration example

Here's a simple example of connecting to Apollo MCP Server from a browser:

Expand Down