How to Connect Synup MCP to Windsurf

Overview

Synup MCP gives you direct access to your Synup data inside Windsurf, letting you query locations, pull reviews, analyze rankings, manage listings, and more through natural language without leaving your editor. Once connected, you can prompt Windsurf's AI to work with your Synup account the same way you would in any other MCP-enabled client.

Windsurf uses a single JSON config file to manage MCP servers, and setup takes just a few minutes.

Before You Begin

You will need:

An active Synup account
A Synup API key from Settings → Integrations
Windsurf installed on your machine

How to Get Your Synup API Key

Log in to your Synup account at app.synup.com
Navigate to Settings in the left sidebar
Click Integrations
Copy your existing API key or generate a new one
Keep it somewhere safe — treat it like a password and do not share it publicly

Which Access Mode Should You Use?

read — Query-only. Windsurf can pull and analyze your Synup data but cannot make any changes. Recommended when setting up for the first time.

write — Full access. Windsurf can respond to reviews, post to social media, launch campaigns, and make changes on your behalf.

Start with read mode and switch to write only when you are ready to take actions.

Step 1: Find the Config File

Windsurf stores its MCP configuration in a file called mcp_config.json. Its location depends on your operating system:

macOS / Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Opening it on macOS using Terminal:

bash

code ~/.codeium/windsurf/mcp_config.json

Opening it on macOS using Finder:

Open Finder
Press Cmd + Shift + G
Type ~/.codeium/windsurf and press Enter
Open mcp_config.json in a code editor

Opening it on Windows:

Press Windows + R to open the Run dialog
Type %USERPROFILE%\.codeium\windsurf and press Enter
Open mcp_config.json in a code editor such as VS Code or Notepad++

If the file or the folder doesn't exist yet, create it — Windsurf will read it on next launch. On macOS you can create it from Terminal in one step:

bash

mkdir -p ~/.codeium/windsurf && code ~/.codeium/windsurf/mcp_config.json

Step 2: Add the Synup MCP Block

If the file is empty or brand new, paste in the following:

json

{

"mcpServers": {

"synup": {

"url": "https://mcp-agent.synup.com/mcp",

"type": "stdio",

"disabled": false,

"headers": {

"X-api-key": "YOUR_API_KEY_HERE",

"X-access-mode": "read"

}

If the file already has other MCP servers configured, add the Synup block inside the existing "mcpServers" section like this:

json

{

"mcpServers": {

"some-other-server": {

...

"synup": {

"url": "https://mcp-agent.synup.com/mcp",

"type": "stdio",

"disabled": false,

"headers": {

"X-api-key": "YOUR_API_KEY_HERE",

"X-access-mode": "read"

}

Replace YOUR_API_KEY_HERE with the key you copied from Synup Settings → Integrations. Change read to write if you need full access.

Step 3: Save and Restart Windsurf

Save the file and fully quit Windsurf, then reopen it. Windsurf only reads the MCP config at startup so closing a panel or tab is not sufficient — you need a full restart.

Step 4: Verify the Connection

Once Windsurf restarts, open a new chat and try one of these prompts:

Which Synup account am I connected to?

List my first 5 locations from Synup

Show my account info from Synup

If authentication is working, Windsurf will return your actual Synup account data. If you see a connection or authentication error, refer to the troubleshooting section below.

What You Can Do After Setup

Once connected, you can use natural language in Windsurf to work with your Synup data, including:

Listing and filtering locations
Pulling reviews and responding at scale
Checking listing status and citation health
Analyzing keyword rankings and Share of Voice
Reviewing campaign performance
Posting to Google Business Profile and Facebook
Comparing performance across your location portfolio
Generating summaries and action plans

Troubleshooting & FAQs

Authentication error on every request. This almost always means the API key is missing, incorrect, or not being sent. Verify that YOUR_API_KEY_HERE has been replaced with your actual key, that the header names are exactly X-api-key and X-access-mode, and that Windsurf was fully restarted after saving the config.

Windsurf shows a config error on launch. This is usually a JSON formatting issue. A missing comma, mismatched bracket, or stray character will prevent the config from loading entirely. Paste your mcp_config.json contents into jsonlint.com to check for errors before restarting Windsurf.

Synup MCP doesn't appear in Windsurf's tool list. Open mcp_config.json and confirm the Synup block is nested correctly inside the "mcpServers" object and not outside it. Also check that "disabled" is set to false and not true.

The server is listed but returning no data. Make sure your Synup account actually has data in the area you're querying. For large accounts, results may be paginated and only a subset is returned by default — ask Windsurf to fetch the next page or filter by a specific location.

Changes to the config aren't taking effect. Windsurf caches MCP connections and only reloads them at startup. Always do a full quit and relaunch after editing mcp_config.json — opening a new Windsurf window or reloading a project is not sufficient.

I want to switch from read to write mode. Open mcp_config.json, change "X-access-mode": "read" to "X-access-mode": "write", save the file, and fully restart Windsurf.