Skip to content

feat: Add CORS configuration for browser-based MCP clients #1059

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

Jump to bottom
Merged
merged 4 commits into from
Aug 21, 2025
Merged

feat: Add CORS configuration for browser-based MCP clients #1059

merged 4 commits into from
Aug 21, 2025
+46 −0

Conversation

jerome3o-anthropic
Copy link
Member

Summary

  • Add CORS middleware to streamable HTTP example servers
  • Configure minimal CORS settings to expose Mcp-Session-Id header
  • Add documentation for CORS configuration in the README

Problem

Browser-based MCP clients cannot access the Mcp-Session-Id header from initialization responses due to CORS restrictions. Without this header, they cannot establish sessions with MCP servers.

Solution

This PR adds Starlette's CORSMiddleware to the example servers and configures it to expose the Mcp-Session-Id header via expose_headers. The configuration is minimal, only allowing the HTTP methods required by the MCP protocol (GET, POST, DELETE).

Changes

  • Add CORSMiddleware import and configuration to:
    • examples/servers/simple-streamablehttp/mcp_simple_streamablehttp/server.py
    • examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/server.py
  • Add CORS configuration section to README under "Streamable HTTP Transport"

Test plan

  • Example servers start successfully with CORS configured
  • Browser-based clients can read the Mcp-Session-Id header from responses
  • CORS headers are properly set on responses
  • Only GET, POST, and DELETE methods are allowed

Reported-by: Jerome

Kludex
Kludex reviewed Jul 4, 2025
View reviewed changes
examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/server.py Outdated
Comment on lines 135 to 142

# Add CORS middleware to expose Mcp-Session-Id header for browser-based clients
starlette_app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Allow all origins - adjust as needed for production
allow_methods=["GET", "POST", "DELETE"], # MCP streamable HTTP methods
expose_headers=["Mcp-Session-Id"],
)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need to wrap the whole application instead of using add_middleware, otherwise 500s don't get in this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@jerome3o-anthropic
feat: Add CORS configuration for browser-based MCP clients
28aaa02 
- Add CORSMiddleware to streamable HTTP example servers
- Configure minimal CORS with Mcp-Session-Id exposed
- Add CORS documentation section to README

This enables browser-based clients to connect to MCP servers by properly
exposing the Mcp-Session-Id header required for session management.

Reported-by: Jerome
@jerome3o-anthropic jerome3o-anthropic force-pushed the jerome/cors-browser-support branch from 7a554e7 to 28aaa02 Compare July 4, 2025 15:22
@felixweinberger felixweinberger requested review from felixweinberger and removed request for felixweinberger July 6, 2025 11:10
@jerome3o-anthropic @Kludex
Update README.md
7b67d78 
Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>
@jerome3o-anthropic jerome3o-anthropic requested a review from Kludex July 7, 2025 12:53
Kludex
Kludex previously approved these changes Jul 7, 2025
View reviewed changes
@felixweinberger felixweinberger removed their request for review July 8, 2025 13:53
felixweinberger
felixweinberger previously requested changes Jul 9, 2025
View reviewed changes
Copy link
Contributor

@felixweinberger felixweinberger left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes to put back in your queue for fixing CI

@Kludex
Copy link
Member

Kludex commented Jul 10, 2025

Requesting changes to put back in your queue for fixing CI

That's a flaky test.

@ihrpr
Copy link
Contributor

ihrpr commented Jul 10, 2025

We still need to address comment in #1059 (comment) for examples, only readme was changed, right?

@felixweinberger
Fix CORS middleware implementation to wrap entire application
992df59 
- Change from add_middleware() to CORSMiddleware wrapper pattern
- Ensures 500 errors get proper CORS headers for browser clients
- Update both streamable HTTP example servers
- Fix README documentation to show complete example

Reported-by: Jerome
@felixweinberger felixweinberger requested review from a team and felixweinberger August 21, 2025 13:09
@felixweinberger felixweinberger dismissed their stale review August 21, 2025 13:11

Dismissing my own review

@felixweinberger felixweinberger requested a review from ihrpr August 21, 2025 13:11
@felixweinberger felixweinberger force-pushed the jerome/cors-browser-support branch from 1792336 to bf7ab5f Compare August 21, 2025 13:14
ihrpr
ihrpr approved these changes Aug 21, 2025
View reviewed changes
Copy link
Contributor

@ihrpr ihrpr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@ihrpr ihrpr merged commit 09e3a05 into main Aug 21, 2025
21 checks passed
@ihrpr ihrpr deleted the jerome/cors-browser-support branch August 21, 2025 13:34
rbehal pushed a commit to gumloop/gumloop-mcp that referenced this pull request Sep 25, 2025
@dvlpjrs @felixweinberger
@yurikunash @pamelafox @ihrpr @Kludex @davenpi @functicons @dingo4dev @LucaButBoring @only-weng @clareliguori @lukacf @chughtapan @yannj-fr @pcarleton @sreenaths @jbkkd @joesavage-silabs @glinf @dsp-ant @mous222 @maxisbey @claude @jerome3o-anthropic @dragonier23 @keurcien @timesler @sandangel @justin-yi-wang @monkeywithacupcake @pja-ant @reidg44 @eleftherias @cclauss @pchoudhury22 @owengo @olivierhub @stevebillings @mssalvatore
[GMLP-5458] Sync upstream (#5)
0206b4d 
* Add regression test for stateless request memory cleanup (modelcontextprotocol#1140)

* Implement RFC9728 - Support WWW-Authenticate header by MCP client (modelcontextprotocol#1071)

* Add streamable HTTP starlette example to Python SDK docs (modelcontextprotocol#1111)

* fix markdown error in README in main (modelcontextprotocol#1147)

* README - replace code snippets with examples - add lowlevel to snippets (modelcontextprotocol#1150)

* README - replace code snippets with examples - streamable http (modelcontextprotocol#1155)

* chore: don't allow users to create issues outside the templates (modelcontextprotocol#1163)

* Tests(cli): Add coverage for helper functions (modelcontextprotocol#635)

* Docs: Update CallToolResult parsing in README (modelcontextprotocol#812)

Co-authored-by: Felix Weinberger <fweinberger@anthropic.com>

* docs: add pre-commit install guide on CONTRIBUTING.md (modelcontextprotocol#995)

Co-authored-by: Felix Weinberger <fweinberger@anthropic.com>

* fix flaky fix-test_streamablehttp_client_resumption test (modelcontextprotocol#1166)

* README - replace code snippets with examples -- auth examples (modelcontextprotocol#1164)

* Support falling back to OIDC metadata for auth (modelcontextprotocol#1061)

* Add CODEOWNERS file for sdk (modelcontextprotocol#1169)

* fix flaky test test_88_random_error (modelcontextprotocol#1171)

* Make sure `RequestId` is not coerced as `int` (modelcontextprotocol#1178)

* Fix: Replace threading.Lock with anyio.Lock for Ray deployment compatibility (modelcontextprotocol#1151)

* fix: fix OAuth flow request object handling (modelcontextprotocol#1174)

* update codeowners group (modelcontextprotocol#1191)

* fix: perform auth server metadata discovery fallbacks on any 4xx (modelcontextprotocol#1193)

* server: skip duplicate response on CancelledError (modelcontextprotocol#1153)

Co-authored-by: ihrpr <inna@anthropic.com>

* Unpack settings in FastMCP (modelcontextprotocol#1198)

* chore: Remove unused prompt_manager.py file (modelcontextprotocol#1229)

Co-authored-by: Tapan Chugh <tapanc@cs.washington.edu>

* Improved supported for ProtectedResourceMetadata (modelcontextprotocol#1235)

Co-authored-by: Paul Carleton <paulcarletonjr@gmail.com>

* chore: Remove unused variable notification_options (modelcontextprotocol#1238)

* Improve README around the Context object (modelcontextprotocol#1203)

* fix: allow to pass `list[str]` to `token_endpoint_auth_signing_alg_values_supported` (modelcontextprotocol#1226)

* Remove strict validation on `response_modes_supported` member of `OAuthMetadata` (modelcontextprotocol#1243)

* Add pyright strict mode on the whole project (modelcontextprotocol#1254)

* Consistent casing for default headers Accept and Content-Type (modelcontextprotocol#1263)

* Update dependencies and fix type issues (modelcontextprotocol#1268)

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

* fix: prevent async generator cleanup errors in StreamableHTTP transport (modelcontextprotocol#1271)

Co-authored-by: David Soria Parra <167242713+dsp-ant@users.noreply.github.com>

* chore: uncomment .idea/ in .gitignore (modelcontextprotocol#1287)

Co-authored-by: Claude <noreply@anthropic.com>

* docs: clarify streamable_http_path configuration when mounting servers (modelcontextprotocol#1172)

* feat: Add CORS configuration for browser-based MCP clients (modelcontextprotocol#1059)

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>
Co-authored-by: Felix Weinberger <fweinberger@anthropic.com>

* Added Audio to FastMCP (modelcontextprotocol#1130)

* fix: avoid uncessary retries in OAuth authenticated requests (modelcontextprotocol#1206)

Co-authored-by: Felix Weinberger <fweinberger@anthropic.com>

* Add PATHEXT to default STDIO env vars in windows (modelcontextprotocol#1256)

* fix: error too many values to unpack (expected 2) (modelcontextprotocol#1279)

Signed-off-by: San Nguyen <vinhsannguyen91@gmail.com>
Co-authored-by: Felix Weinberger <fweinberger@anthropic.com>
Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>

* SDK Parity: Avoid Parsing Server Response for non-JsonRPCMessage Requests (modelcontextprotocol#1290)

* types: Setting default value for method: Literal (modelcontextprotocol#1292)

* changes structured temperature to not deadly (modelcontextprotocol#1328)

* Update simple-resource example to use non-deprecated read_resource return type (modelcontextprotocol#1331)

Co-authored-by: Claude <noreply@anthropic.com>

* docs: Update README to include link to API docs for modelcontextprotocol#1329 (modelcontextprotocol#1330)

* Allow ping requests before initialization (modelcontextprotocol#1312)

* Python lint: Ruff rules for pylint and code complexity (modelcontextprotocol#525)

* Fix context injection for resources and prompts (modelcontextprotocol#1336)

* fix(fastmcp): propagate mimeType in resource template list (modelcontextprotocol#1186)

Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>

* fix: allow elicitations accepted without content (modelcontextprotocol#1285)

Co-authored-by: Olivier Schiavo <olivier.schiavo@wengo.com>

* Use --frozen in pre-commit config (modelcontextprotocol#1375)

* Return HTTP 403 for invalid Origin headers (modelcontextprotocol#1353)

* Add test for ProtectedResourceMetadataParsing (modelcontextprotocol#1236)

Co-authored-by: Paul Carleton <paulcarletonjr@gmail.com>
Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>
Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>

* Fastmcp logging progress example (modelcontextprotocol#1270)

Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>

* feat: add paginated list decorators for prompts, resources, and tools (modelcontextprotocol#1286)

Co-authored-by: Claude <noreply@anthropic.com>

* Remove "unconditionally" from conditional description (modelcontextprotocol#1289)

* Use streamable-http consistently in examples (modelcontextprotocol#1389)

* feat: Add SDK support for SEP-1034 default values in elicitation schemas (modelcontextprotocol#1337)

Co-authored-by: Tapan Chugh <tapanc@cs.washington.edu>
Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>

* Implementation of SEP 973 - Additional metadata + icons support (modelcontextprotocol#1357)

* Merge upstream/main with custom filtering

---------

Signed-off-by: San Nguyen <vinhsannguyen91@gmail.com>
Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>
Co-authored-by: yurikunash <143175350+yurikunash@users.noreply.github.com>
Co-authored-by: Pamela Fox <pamela.fox@gmail.com>
Co-authored-by: Inna Harper <inna.hrpr@gmail.com>
Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>
Co-authored-by: Ian Davenport <49379192+davenpi@users.noreply.github.com>
Co-authored-by: Dagang Wei <functicons@gmail.com>
Co-authored-by: Felix Weinberger <fweinberger@anthropic.com>
Co-authored-by: Stanley Law <stanleylkal@gmail.com>
Co-authored-by: Luca Chang <131398524+LucaButBoring@users.noreply.github.com>
Co-authored-by: leweng <leweng@nvidia.com>
Co-authored-by: Clare Liguori <liguori@amazon.com>
Co-authored-by: lukacf <luka@peltarion.com>
Co-authored-by: ihrpr <inna@anthropic.com>
Co-authored-by: Tapan Chugh <chugh.tapan@gmail.com>
Co-authored-by: Tapan Chugh <tapanc@cs.washington.edu>
Co-authored-by: Yann Jouanin <4557670+yannj-fr@users.noreply.github.com>
Co-authored-by: Paul Carleton <paulcarletonjr@gmail.com>
Co-authored-by: Sreenath Somarajapuram <somarajapuram@gmail.com>
Co-authored-by: Omer Korner <omerkorner@gmail.com>
Co-authored-by: joesavage-silabs <159480754+joesavage-silabs@users.noreply.github.com>
Co-authored-by: Gregory L <gregory.linford@mistral.ai>
Co-authored-by: David Soria Parra <167242713+dsp-ant@users.noreply.github.com>
Co-authored-by: Moustapha Ebnou <155577789+mous222@users.noreply.github.com>
Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Jerome <jerome@anthropic.com>
Co-authored-by: xavier <84836280+dragonier23@users.noreply.github.com>
Co-authored-by: keurcien <keurcien.luu@gmail.com>
Co-authored-by: Tim Esler <tim.esler@gmail.com>
Co-authored-by: San Nguyen <22189661+sandangel@users.noreply.github.com>
Co-authored-by: Justin Wang <89049861+justin-yi-wang@users.noreply.github.com>
Co-authored-by: jess <jessachandler@gmail.com>
Co-authored-by: Peter Alexander <pja@anthropic.com>
Co-authored-by: Reid Geyer <12072650+reidg44@users.noreply.github.com>
Co-authored-by: Eleftheria Stein-Kousathana <eleftheria.kousathana@gmail.com>
Co-authored-by: Christian Clauss <cclauss@me.com>
Co-authored-by: pchoudhury22 <pchoudhury22@apple.com>
Co-authored-by: owengo <owengo@users.noreply.github.com>
Co-authored-by: Olivier Schiavo <olivier.schiavo@wengo.com>
Co-authored-by: Steve Billings <billings.steve@gmail.com>
Co-authored-by: Mike Salvatore <mike.s.salvatore@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ihrpr ihrpr ihrpr approved these changes

@felixweinberger felixweinberger felixweinberger left review comments

@Kludex Kludex Kludex left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@jerome3o-anthropic @Kludex @ihrpr @felixweinberger