Synup MCP Troubleshooting Guide

Most Synup MCP issues fall into one of three categories:

• Authentication problems: the API key is missing, incorrect, or not being sent
• Configuration problems: the config file has formatting errors or the server block is in the wrong place
• Data problems: the connection is working but the query isn't returning what you expect

Identifying which category you're in first will save you a lot of time.

Authentication Issues

API Key Not Working

The most common cause is an extra space before or after the key value, or a typo introduced during copy-paste.

What to check:

• Verify the header name is exactly X-api-key with no variation in casing or spelling
• Confirm there are no leading or trailing spaces around the key value
• Make sure you're using the full key as it was generated — it should be a long alphanumeric string
• If you're unsure whether the key is still valid, go to Settings → Integrations in your Synup account and regenerate it, then update your config with the new key

Authentication Fails on Every Reconnect

If the connection works once but fails every time you reopen your tool, this is usually a restart issue rather than a key issue.

Fix: Restart your IDE or terminal application completely rather than just closing and reopening the session. Config changes sometimes require a full restart to take effect properly.

Headers Not Being Sent

Some client config formats require headers to be specified in a particular way. If the tool is connecting to the MCP server but every request comes back with an authentication error, the headers may not be included in the actual requests being made.

What to check:

• For Cursor: headers go inside the "headers" block in mcp.json alongside "url" and "type"
• For Windsurf: headers go inside the "headers" block in mcp_config.json
• For Codex: headers go in a separate [mcp_servers.synup.http_headers] block in config.toml
• For Claude Code: headers are passed as --header flags in the terminal command

After verifying the format, save the file and do a full restart of the client.

Connection Issues

MCP Server Won't Connect

If the server fails to connect entirely, the most likely causes are a wrong URL or an incomplete restart.

What to check:

• Confirm the endpoint URL is exactly https://mcp-agent.synup.com/mcp with no trailing slash or typo
• Make sure the client was fully restarted after the config was saved — closing a window or tab is not sufficient
• Check the config file for JSON or TOML formatting errors (see the section below)

Config File Errors Preventing Connection

A single formatting mistake in your config file will prevent the entire file from loading, which means none of your MCP servers will connect — not just Synup.

For JSON-based configs (Cursor, Windsurf):

• Check for missing commas between server blocks
• Check for unclosed brackets or braces
• Make sure all strings are wrapped in double quotes
• Paste the entire contents of your config file into jsonlint.com to validate it before restarting

For TOML-based configs (Codex):

• Check that section headers use the correct format: [mcp_servers.synup] and [mcp_servers.synup.http_headers]
• Make sure string values are wrapped in double quotes
• Verify there are no duplicate section headers

For Claude Code:

• Run claude mcp list in your terminal to confirm the server was registered successfully
• If it doesn't appear, re-run the claude mcp add command

Data Issues

Empty Results Returned

If the connection is working and authentication is passing but queries return nothing, this is usually a data availability or pagination issue rather than a connection problem.

What to check:

• Confirm your Synup account actually has the data you're querying — for example, if you're asking for reviews, make sure reviews exist for the locations in question
• Run a broad query first such as "list all my locations" to confirm data is accessible before running more specific queries
• Check whether you're querying the correct location by running get_all_locations to verify the location IDs in your account

Only Partial Data Returned

Synup MCP returns the first 50 results by default for large data sets. If you have more than 50 locations, reviews, or other records, the initial query will only return a subset.

Fix: Ask your AI client to fetch the next page using pagination. Location IDs in Synup are Base64 strings in the format Location:12345 — make sure you're passing the correct format when querying specific locations.

Queries Timing Out

For accounts with 100 or more locations, broad queries that request a large amount of data at once can time out before completing.

Fixes:

• Narrow the date range — query 7 days of data instead of 90 days
• Filter by a specific location rather than pulling all locations at once
• Break large requests into smaller sequential queries

Tool-Specific Issues

Claude Code

/mcp command not found You need to be inside an active Claude Code session to use /mcp. Type claude in your terminal first to start a session, then type /mcp inside that chat interface — it will not work in your regular terminal prompt.

command not found: claude after installation Your npm global bin directory is not in your system PATH. Run npm config get prefix in your terminal, then add that path followed by /bin to your shell's PATH variable. On macOS with zsh, add export PATH="$(npm config get prefix)/bin:$PATH" to your ~/.zshrc file and run source ~/.zshrc.

npm EACCES permission error during installation Run the following to fix npm cache permissions, then retry the install:

bash

sudo chown -R 501:20 "/Users/$(whoami)/.npm"

Cursor

One-click install link didn't work Make sure Cursor is already open before clicking the link. If it still doesn't work, use the manual config method by editing ~/.cursor/mcp.json directly.

Synup MCP not appearing in the tool list after setup Open ~/.cursor/mcp.json and confirm the Synup block is nested correctly inside the "mcpServers" object. If it is placed at the wrong nesting level the server will be ignored entirely.

Windsurf

Server listed but returning no data Check that "disabled" is set to false in your mcp_config.json block. Also verify the Synup block is correctly nested inside "mcpServers" rather than outside it.

Config folder doesn't exist Create it from Terminal with:

bash

mkdir -p ~/.codeium/windsurf

Then create mcp_config.json inside that folder and add the Synup block.

Codex

Config changes not loading in the IDE extension The Codex CLI and Codex IDE extension share the same ~/.codex/config.toml file. If changes aren't reflected in one of them, make sure you fully restarted both the CLI session and the IDE extension after saving the config.

TOML syntax error breaking all MCP servers Because the CLI and IDE extension share one config file, a TOML formatting error breaks both simultaneously. Validate your TOML at tomlint.com before restarting if you're unsure about the formatting.

General Checklist

If you've worked through the above and things still aren't connecting, run through this checklist before reaching out to support:

• API key has been copied correctly with no extra spaces
• Both X-api-key and X-access-mode headers are present
• The endpoint URL is exactly https://mcp-agent.synup.com/mcp
• Config file has been validated for formatting errors
• The correct field name is used — "type" in JSON configs, section headers in TOML
• The client was fully quit and relaunched after saving the config, not just reloaded
• For large accounts, pagination or date range filtering has been applied to avoid timeouts