Windsurf MCP Troubleshooting: Auth Headers Not Being Sent

Windsurf connects to Corcava MCP but tool calls fail? This Windsurf-specific troubleshooting guide helps you fix cases where the server connects but tool calls fail due to missing authorization headers. Learn how to verify header configuration and get a working example.

Understanding the Problem

Windsurf may successfully establish a connection to the MCP server, but when making tool calls, the Authorization header isn't being sent, causing tool calls to fail with 401 errors.

Symptom Pattern

• MCP server appears in Windsurf as "connected"
• Tools may appear in the tools list
• But tool calls fail with 401 Unauthorized
• Error indicates missing or invalid Authorization header

Step 1: Verify Header Configuration

Check that your Windsurf MCP configuration includes the Authorization header:

Correct Windsurf Config Format

Working Windsurf Config

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Critical points:

• headers object must be present
• Authorization key must be exactly "Authorization" (case-sensitive)
• Value must be "Bearer " followed by your API key (with space)
• No extra spaces or formatting issues

Common Configuration Mistakes

Note: The JSON examples below contain inline // comments for explanation only. These comments are not valid JSON and must be removed when creating your actual configuration file.

Missing Headers Object

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp"
      // Missing "headers" object
    }
  }
}

Fix: Add the headers object with Authorization key. Note: The example above contains an explanatory comment (not valid JSON) - remove the comment line when creating your config.

Wrong Header Key Name

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "authorization": "Bearer YOUR_API_KEY"  // Wrong case
        // or
        "Auth": "Bearer YOUR_API_KEY"  // Wrong name
      }
    }
  }
}

Fix: Use exactly "Authorization" (capital A, rest lowercase). Note: The example above contains explanatory comments (not valid JSON) - remove the comment lines when creating your config.

Missing Bearer Prefix

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "YOUR_API_KEY"  // Missing "Bearer "
      }
    }
  }
}

Fix: Include "Bearer " prefix: "Bearer YOUR_API_KEY". Note: The example above contains an explanatory comment (not valid JSON) - remove the comment when creating your config.

Step 2: Check Windsurf Settings UI

If using Windsurf's settings UI (not JSON file), verify the header is configured correctly:

Settings UI Configuration

In Windsurf Settings → MCP Servers:

1. Find the Corcava MCP server entry
2. Check "Headers" or "Authentication" section
3. Verify "Authorization" header is present
4. Value should be: Bearer YOUR_API_KEY
5. Save the settings
6. Restart Windsurf if required

Settings UI vs JSON File

Configuration Source

Windsurf may use either:

• Settings UI: Configured through Windsurf's settings interface
• JSON file: Configured in a config file (location varies)

Ensure you're checking the correct configuration source. Changes in one may not reflect in the other.

Step 3: Test Header Transmission

Verify that Windsurf is actually sending the Authorization header:

Diagnostic Steps

Test if headers are being sent:

1. Try a simple tool call: "List my projects"
2. If it fails with 401, check the error message
3. Error should indicate missing Authorization header
4. Compare with working curl test (see below)

Compare with curl Test

Test with curl (Should Work)

curl -H "Authorization: Bearer <API_KEY_PLACEHOLDER>" \
  https://app.corcava.com/mcp

If curl works but Windsurf doesn't, it's a Windsurf header transmission issue.

Step 4: Working Example Snippet

Here's a complete, working Windsurf configuration example:

Complete Working Config

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your actual Corcava API key.

Multiple Servers Example

If you have multiple MCP servers:

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CORCAVA_API_KEY"
      }
    },
    "other-server": {
      "url": "https://other-server.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_OTHER_API_KEY"
      }
    }
  }
}

Step 5: Restart Windsurf

After fixing the header configuration, restart Windsurf to apply changes:

Restart Steps

1. Save your configuration (JSON file or Settings UI)
2. Completely quit Windsurf
3. Wait a few seconds
4. Reopen Windsurf
5. Test with a simple tool call

Step 6: Verify Header is Sent

After restarting, verify tool calls work:

Test Tool Calls

Try these test prompts:

• "List my Corcava projects" (tests list_projects)
• "Show me my tasks" (tests list_tasks)
• "What MCP tools are available?" (tests tool discovery)

If these work, headers are being sent correctly. If they fail with 401, headers are still not being transmitted.

Expected Behavior

When headers are working correctly:

• Tool calls succeed (not 401 errors)
• You get actual data back (projects, tasks, etc.)
• No "unauthorized" or "missing header" errors

Quick Fix Checklist

Before Escalating

• ✅ Config includes headers object
• ✅ Authorization key is exactly "Authorization" (case-sensitive)
• ✅ Header value is "Bearer YOUR_API_KEY" (with space after Bearer)
• ✅ API key is active and not revoked
• ✅ Config file is valid JSON (if using JSON file)
• ✅ Settings saved in Windsurf (if using Settings UI)
• ✅ Windsurf has been fully restarted after config changes
• ✅ Tested with curl - works (verifies API key is valid)

Still Having Issues?

If headers still aren't being sent after all steps:

• Check Windsurf version (update to latest if outdated)
• Review Windsurf logs for MCP-related errors
• Try removing and re-adding the MCP server configuration
• See 401 Unauthorized for general auth troubleshooting
• Check Tools Not Listed for connection issues
• Contact Windsurf support with specific error messages

Related Troubleshooting

• 401 Unauthorized - General authentication troubleshooting
• Tools Not Listed - Fix issues when tools don't appear
• Windsurf Setup - Review Windsurf MCP setup guide
• Troubleshooting Index - Browse all troubleshooting guides