How to Connect Synup MCP to Codex
Overview
Synup MCP provides a unified Model Context Protocol interface for working with locations, reviews, social media, rankings, listings, campaigns, and analytics through AI agents.
Synup exposes MCP as an HTTP streamable server authenticated with request headers. While Synup's docs currently call out Claude Code, Cursor, and Windsurf, the same HTTP MCP setup works with any Codex client that supports MCP server configuration — including both Codex Desktop and Codex CLI.
Before You Begin
You will need:
- An active Synup account
- A Synup API key from Settings → Integrations
- Codex Desktop or Codex CLI installed
- Permission to use read or write mode as appropriate for your role
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?
Synup MCP supports two access modes that control what the AI can do on your behalf:
read — Query-only access. Claude can pull and analyze your data but cannot make any changes. Use this for testing and exploration.
write — Full read and write access. Claude can respond to reviews, edit settings, launch campaigns, and create content on your behalf.
If you are setting up for the first time, start with read mode and switch to write only when you are ready to take actions.
Option A: Codex Desktop App
Step 1: Try the Desktop Settings UI First
Some versions of Codex Desktop include a built-in MCP settings panel. To check:
- Open the Codex Desktop app
- Go to Settings
- Look for an MCP, Tools, or Connections section depending on your app version
- If available, choose to add a new MCP server and enter the following:
Field | Value |
|---|---|
Name | Synup |
URL | https://mcp-agent.synup.com/mcp |
Header 1 | X-api-key: YOUR_API_KEY_HERE |
Header 2 | X-access-mode: read |
Save the server, fully quit and reopen Codex Desktop, then test the connection with a prompt like:
Which Synup account are you connected to?
Step 2: If the UI Doesn't Support Headers, Use the Config File
If the settings panel doesn't expose custom HTTP headers, configure Synup MCP directly in the Codex config file instead.
Finding the config file on macOS:
The file lives at ~/.codex/config.toml. To open it:
Using Terminal:
bash
code ~/.codex/config.toml
Using Finder:
- Open Finder
- Press Cmd + Shift + G
- Type ~/.codex and press Enter
- Open config.toml in a code editor
If the file doesn't exist yet, create it — Codex will read it on next launch.
Adding the Synup MCP block:
Open config.toml and add the following:
toml
[mcp_servers.synup]
enabled = true
url = "https://mcp-agent.synup.com/mcp"
[mcp_servers.synup.http_headers]
X-api-key = "YOUR_API_KEY_HERE"
X-access-mode = "read"
Replace YOUR_API_KEY_HERE with your actual key. If you need write access, change read to write.
Save the file, then fully quit and relaunch Codex Desktop. Closing a window is not enough — the app only reads the config at startup.
Option B: Codex CLI
Codex CLI uses the exact same config file as the Desktop app, so the setup is identical. Any changes you make to ~/.codex/config.toml apply to both.
Step 1: Open the Config File
bash
code ~/.codex/config.toml
Step 2: Add the Synup MCP Block
toml
[mcp_servers.synup]
enabled = true
url = "https://mcp-agent.synup.com/mcp"
[mcp_servers.synup.http_headers]
X-api-key = "YOUR_API_KEY_HERE"
X-access-mode = "read"
For write access:
toml
[mcp_servers.synup]
enabled = true
url = "https://mcp-agent.synup.com/mcp"
[mcp_servers.synup.http_headers]
X-api-key = "YOUR_API_KEY_HERE"
X-access-mode = "write"
Step 3: Save and Restart
Make sure the TOML formatting is valid, save the file, then close any running Codex CLI session and start a fresh one so the config reloads.
Step 4: Verify the Connection
Try one of these prompts to confirm Synup data is coming through:
Which Synup account am I connected to?
List my first 5 locations
Show my account type and company name
If authentication is working, Codex will return your actual Synup account data rather than an authentication error.
What You Can Do After Setup
Once connected, you can use natural language prompts to work with your Synup data, including:
- Listing and filtering locations
- Reading reviews and interaction stats
- Analyzing rankings and Share of Voice
- Checking listing and citation health
- Reviewing campaigns and social content
- Comparing performance across locations
- Generating summaries and action plans
Troubleshooting & FAQs
Authentication required error on every request. This usually means the headers are missing, not loaded, or not being sent. Verify that the URL is exactly https://mcp-agent.synup.com/mcp, that both headers are present with the correct names, that the API key is valid, and that Codex was fully restarted after the config change.
Codex can see Synup tools but account reads fail. This is an important distinction — it means the MCP server connection exists but authentication is still not working. This is almost always a header or config reload issue. Save the config file again and do a full restart of Codex.
Headers not recognized in the desktop settings UI. If the Codex Desktop UI doesn't cleanly support custom HTTP headers, skip it and use the ~/.codex/config.toml method instead. Both approaches result in the same connection.
Changes to the config aren't taking effect. Codex caches MCP connections and only reads the config at startup. Always do a full quit and relaunch after editing config.toml — closing a settings panel or opening a new tab is not sufficient.
Empty or partial data returned. This may not be an authentication issue. Check that your account actually has the data you're querying, that you're using the correct location IDs, and that results aren't being paginated with only a subset returned by default.