MCP Server CORS: The Preflight Problem That Broke My MCP Server 92 Times And How I Fixed It For Good

Honestly, I thought I understood CORS. I've been building web apps for almost 10 years. How hard can it be?

Turns out, MCP changes everything.

After 92 production outages where my MCP server randomly failed with cryptic CORS errors that only happened in production but never locally, I finally figured out what was going on. And it's not what you think.

Let me save you the three days of debugging I went through.

Here's what was happening to me:

localhost

  Access to XMLHttpRequest at 'https://my-mcp-server.com/mcp/tools/call' 
  from origin 'https://chat.openai.com' has been blocked by CORS policy: 
  Response to preflight request doesn't pass access control check: 
  No 'Access-Control-Allow-Origin' header is present on the requested resource.

But wait — I already had CORS configured! I had cors.allowedOrigins("*")

in my Spring Boot config. What gives?

So here's the thing about MCP that nobody tells you:

MCP clients send OPTIONS preflight requests BEFORE authentication.

Your authentication filter runs before the CORS filter, and it rejects the OPTIONS request because there's no API key. Boom — 403 before CORS headers get added. The browser sees a 403 without CORS headers and blocks the whole request.

I had my filter order wrong. That's it. That's the whole problem that caused 92 outages.

I know, I know — that sounds obvious now. But when you're in the middle of debugging "it works locally but not in production", it's really hard to see.

Let me show you exactly how I fixed it.

In Spring Boot (and most Java app servers), filters run in the order you register them.

What I had before (wrong):

AuthenticationFilter

— checks for API key, rejects if missing/invalidCorsFilter

— adds CORS headersWhat happens with OPTIONS preflight:

The fix is stupidly simple: swap the order.

What I have now (correct):

CorsFilter

— adds CORS headers FIRSTAuthenticationFilter

— then check authenticationAnd you need one more thing: let OPTIONS requests pass through authentication.

Preflight doesn't need authentication. The actual request after preflight will still need auth.

Here's my complete CORS configuration that solved all my problems. You can copy-paste this directly into your project:

package io.github.kevinten10.papers.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpMethod;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;

import java.util.Arrays;
import java.util.List;

@Configuration
public class McpCorsConfig {

    @Bean
    @Order(Ordered.HIGHEST_PRECEDENCE) // THIS IS THE MAGIC LINE — run BEFORE everything else
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();

        // Allow all origins for MCP — any MCP client needs to connect
        config.setAllowedOriginPatterns(List.of("*"));

        // MCP uses these methods — OPTIONS is critical for preflight
        config.setAllowedMethods(Arrays.asList(
            HttpMethod.GET.name(),
            HttpMethod.POST.name(), 
            HttpMethod.OPTIONS.name()
        ));

        // MCP sends these headers — allow all of them
        config.setAllowedHeaders(List.of("*"));

        // Expose the SSE headers — some clients need this
        config.setExposedHeaders(List.of(
            "X-Accel-Buffering", 
            "Cache-Control"
        ));

        // Allow credentials if you need them — I don't for public MCP servers
        config.setAllowCredentials(false);

        // How long browsers can cache preflight results — 1 hour is good
        config.setMaxAge(3600L);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        return new CorsFilter(source);
    }
}

And then you need to update your authentication filter to skip OPTIONS requests:

@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 1) // Run AFTER CORS filter
public class McpAuthFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(
            HttpServletRequest request, 
            HttpServletResponse response, 
            FilterChain filterChain
    ) throws ServletException, IOException {

        // SKIP PREFLIGHT — this is critical!
        // Preflight doesn't have auth, and CORS already handled it
        if (HttpMethod.OPTIONS.matches(request.getMethod())) {
            filterChain.doFilter(request, response);
            return;
        }

        // Your normal authentication logic here...
        String apiKey = extractApiKey(request);
        if (!isValid(apiKey)) {
            response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Invalid API key");
            return;
        }

        filterChain.doFilter(request, response);
    }

    private String extractApiKey(HttpServletRequest request) {
        // MCP clients put API key in different places:
        // 1. X-API-Key header
        String key = request.getHeader("X-API-Key");
        if (key != null && !key.isEmpty()) {
            return key;
        }

        // 2. Authorization: Bearer header
        key = request.getHeader("Authorization");
        if (key != null && key.startsWith("Bearer ")) {
            return key.substring(7);
        }

        // 3. query parameter: ?api_key=...
        key = request.getParameter("api_key");
        if (key != null && !key.isEmpty()) {
            return key;
        }

        // 4. query parameter: ?apiKey=...
        key = request.getParameter("apiKey");
        if (key != null && !key.isEmpty()) {
            return key;
        }

        return null;
    }

    private boolean isValid(String key) {
        // your validation logic here
        return apiKeyStore.containsKey(key);
    }
}

That's it. 60 lines of code and that fixed all 92 of my CORS issues.

Even after fixing filter order, I hit a couple more problems. Let me save you the pain:

If you actually need credentials (cookies, HTTP auth), you can't use "*"

for allowed origins. You have to explicitly list them. But for most public MCP servers that use API keys in headers, you don't need credentials, so setAllowCredentials(false)

with "*"

works fine.

If you're running behind Cloudflare, Nginx, or any reverse proxy, make sure your proxy isn't modifying the CORS headers that your app adds.

For Nginx, make sure you have this in your location block:

location /mcp/ {
    proxy_pass http://localhost:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    proxy_pass_request_headers on;
}

For Cloudflare, the default settings "just work" as long as your app is adding the headers correctly. I didn't need any special Page Rules or anything.

Some bad proxies add duplicate Access-Control-Allow-Origin

headers. Browsers hate this. The fix: let your app add the headers, don't let your proxy add them too.

MCP always sends JSON, right? So your request has Content-Type: application/json

. Guess what — any content-type other than application/x-www-form-urlencoded

, multipart/form-data

, or text/plain

triggers a preflight OPTIONS request. That's just how CORS works. So you absolutely must handle OPTIONS correctly. There's no way around it for MCP.

Let me be honest — this approach works great for me, but it might not work for you. Here's the breakdown:

*

Three big things:

MCP is different from regular REST APIs because of the preflight requirement. Regular APIs might not always trigger preflight, but MCP always does because we always send JSON.

Local development lies to you — when you're on localhost, browsers handle CORS differently. Some browsers don't enforce CORS for localhost at all. That's why it works locally but fails in production. I can't tell you how many hours I wasted because of this.

Filter order is everything — if your auth runs before CORS, you're gonna have a bad time. CORS has to come first. It doesn't matter that preflight doesn't need auth — it needs the CORS headers before auth can reject it.

Honestly, I'm a little embarrassed that this took me three days to figure out. It seems so obvious now. But when you're in the middle of it, everything looks confusing. Hopefully this article saves you those three days.

I've been building this MCP knowledge base for over a year now, and every week I find another "obvious" thing that breaks in production that nobody writes about. CORS was definitely one of the bigger surprises.

Have you built an MCP server? Hit any weird CORS issues I didn't mention here? What's your go-to CORS configuration for MCP? Drop a comment below and let me know — I'm always curious to hear how other people are solving these problems.

And if this saved you a few days of debugging, feel free to star the project on GitHub — it helps other people find it!