📚guidebeginner

Windsurf MCP Setup: Connect Gmail, Notion, GitHub & More (2025 Guide)

Configure MCP servers in Windsurf IDE in 5 minutes. Copy-paste configs for Gmail, Notion, PostgreSQL, and 100+ servers. Includes mcp_config.json examples and troubleshooting tips.

ByMCP Directory Team
Published
⏱️10 minutes
windsurfmcpsetupconfigurationcodeiumgmailfilesystemnotionwindsurf-mcpcascademcp-config-jsonwindsurf-ide

The Ultimate Guide to Using MCP Servers in Windsurf IDE

Last Updated: December 2025 Compatibility: Windsurf (Codeium)

Windsurf is rapidly becoming the IDE of choice for developers who want "Flow"—an AI state where the editor acts as a true agent. The secret to unlocking Windsurf's full potential is the Model Context Protocol (MCP).

By connecting MCP servers, you allow Windsurf to leave the text editor and interact with your computer, database, or external APIs (like sending emails or managing GitHub issues).

This guide covers setup, configuration, and a real-world example of connecting Gmail.

How to Configure MCP in Windsurf

Unlike VS Code, which requires an extension, or Cursor, which uses a specific settings pane, Windsurf manages MCP via a JSON configuration file.

Step 1: Locate the Config

  1. Open Windsurf.
  2. Open the Command Palette (Cmd+Shift+P on Mac / Ctrl+Shift+P on Windows).
  3. Type and select: "Windsurf: Configure MCP Servers".
  4. This will open your mcp_config.json file.

Step 2: Add Your Servers

The configuration requires a mcpServers object. Here is the standard structure:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/desktop/allowed-folder"
      ]
    }
  }
}

Real-World Example: How to Send Email in Windsurf

Addressing the popular search query: "how to send email in windsurf"

To let Windsurf draft and send emails, you need the Gmail MCP Server.

1. Prerequisites:

  • Node.js installed.
  • A Google Cloud Project with Gmail API enabled (or a pre-configured auth token).

2. The Configuration:

Add this block to your mcp_config.json:

"gmail": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-gmail"
  ],
  "env": {
    "GMAIL_TOKEN": "your-auth-token-here"
  }
}

(Note: Ensure you check the specific server documentation for the exact environment variable requirements.)

3. The Prompt:

Once saved, open the "Flow" or "Chat" pane in Windsurf and type:

"Check my last 5 emails regarding 'Invoices' and draft a reply to the most recent one confirming payment."

Real-World Example: How to Access Notion in Windsurf

Addressing the popular need: "connect notion to windsurf ide"

The Notion MCP Server is Notion's official hosted server that gives Windsurf secure access to your workspace through OAuth authentication.

1. Prerequisites:

  • Active Notion workspace with appropriate access permissions
  • Node.js installed (for STDIO transport method)

2. Configuration Method 1 - STDIO Transport (Recommended for Windsurf):

Add this block to your mcp_config.json:

"notionMCP": {
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://mcp.notion.com/mcp"
  ]
}

This uses mcp-remote as a proxy to convert Notion's hosted server into a format Windsurf can connect to via STDIO.

3. Configuration Method 2 - Through Notion App (Easiest):

  1. Open Settings in the Notion app
  2. Navigate to Connections → Notion MCP
  3. Select Windsurf from the list of featured tools
  4. Complete the OAuth flow to authorize the connection

4. What You Can Do:

Once connected, you can prompt Windsurf to:

"Search my Notion workspace for all documentation about API authentication"

"Show me all high-priority tasks from the engineering database"

"Read the content of our Q4 roadmap page and summarize key milestones"

"Create a technical spec based on our security guidelines in Notion"

5. Access & Permissions:

Windsurf can only access content you have permission to view in Notion. All operations are scoped to your user permissions - no workspace-wide access beyond what you can already see.

Capabilities:

  • Search: Find content across your entire workspace
  • Database Queries: Retrieve and filter structured data from Notion databases
  • Page Access: Read page content, properties, and hierarchical structure
  • Comments: Access discussion threads and annotations

Top MCP Servers for Windsurf Users

  • Notion: Access your Notion workspace - search pages, query databases, and read comments directly from Windsurf.
  • PostgreSQL: Let Windsurf query your local DB to write SQL migrations.
  • Git: Allow Windsurf to stage, commit, and push changes contextually.
  • Brave Search: Give Windsurf access to the live internet for documentation lookups.
  • Filesystem: Enable safe file operations within specified directories.

Browse All Windsurf Compatible Servers →

Configuration Best Practices

Security Considerations

  1. Restrict Filesystem Access: Only grant access to specific directories
  2. Use Environment Variables: Never hardcode sensitive tokens in config files
  3. Token Scope Management: Use minimal required scopes for API tokens

Performance Tips

  1. Lazy Loading: Configure only the servers you actively use
  2. Resource Paths: Use absolute paths to avoid resolution issues
  3. Server Monitoring: Check Windsurf's MCP server logs for connection issues

Troubleshooting Common Issues

Server Won't Start

Problem: Server fails to initialize after configuration

Solutions:

  • Verify Node.js is installed and in PATH
  • Check that npx command is accessible
  • Ensure all required dependencies are installed
  • Review Windsurf's developer console for error messages

Permission Denied Errors

Problem: MCP server cannot access specified resources

Solutions:

  • Verify file/directory permissions
  • Check that paths exist and are accessible
  • Ensure environment variables are correctly set
  • Confirm API tokens have required scopes

Slow Response Times

Problem: MCP operations take too long to complete

Solutions:

  • Reduce scope of filesystem access
  • Optimize database queries for PostgreSQL server
  • Check network connectivity for API-based servers
  • Consider using local alternatives where possible

Notion Connection Issues

Problem: Cannot connect to Notion MCP or workspace access denied

Solutions:

  • Ensure Node.js is installed for mcp-remote proxy
  • Verify OAuth flow completed successfully in Notion app
  • Check that you have appropriate workspace permissions
  • Use configuration: npx -y mcp-remote https://mcp.notion.com/mcp
  • Disable popup blockers during OAuth authentication
  • Verify you can access the content in Notion app first

Notion Content Not Found

Problem: Specific Notion pages or databases return not found errors

Solutions:

  • Remember: Windsurf can only see what you can see in Notion
  • Verify you have access to the pages/databases in Notion app
  • Check workspace sharing settings for restricted content
  • Ensure pages aren't in private sections you cannot access
  • Contact workspace admin if you need broader access

Advanced Configuration Examples

Multiple Server Setup

{
  "mcpServers": {
    "notionMCP": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "/Users/username/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgresql"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

Environment-Specific Configuration

Create separate config files for different environments:

  • mcp_config.development.json - Development with verbose logging
  • mcp_config.production.json - Production with restricted access

Try These Integrations

Ready to put this into practice? Here are popular Windsurf integrations:

Next Steps

  1. Explore Server Options: Browse the MCP Directory for 1000+ available servers
  2. Join the Community: Connect with other Windsurf users in MCP forums
  3. Custom Development: Learn to build your own MCP servers
  4. Advanced Integration: Explore game development workflows with Godot integration

Frequently Asked Questions

Q: Does Windsurf support all MCP servers? A: Windsurf supports any MCP server that runs on stdio (standard input/output), which covers the vast majority of available servers.

Q: Can I use multiple MCP servers simultaneously? A: Yes! Configure as many servers as needed in your mcp_config.json file.

Q: How do I update an MCP server? A: When using npx -y, the latest version is automatically fetched. For global installs, run npm update -g <package-name>.

Q: Are there performance impacts? A: MCP servers run as separate processes and only activate when called, so impact is minimal when servers are idle.

Q: How do I connect Notion to Windsurf? A: Use the official Notion MCP server with the configuration: npx -y mcp-remote https://mcp.notion.com/mcp. This uses mcp-remote as a proxy to connect Notion's hosted server to Windsurf via STDIO. Alternatively, configure through the Notion app under Settings > Connections > Notion MCP.

Q: Can Windsurf access my private Notion pages? A: Windsurf can only access Notion content that you have permission to view. All operations are scoped to your user permissions - there's no workspace-wide access beyond what you can already see in the Notion app.

This comprehensive guide provides everything you need to configure and optimize MCP servers in Windsurf IDE. Start with basic configuration, then expand to advanced multi-server setups as your workflow evolves.

← Back to Learn Hub