Windsurf Setup Guide

Prerequisites

Setup (3 Minutes)

Step 1: Add Adspirer to Your MCP Config

Windsurf stores MCP server configs at ~/.codeium/windsurf/mcp_config.json. Create or edit that file:

{
  "mcpServers": {
    "adspirer": {
      "type": "streamable-http",
      "url": "https://mcp.adspirer.com/mcp"
    }
  }
}

If you already have other MCP servers configured, add the "adspirer" entry to the "mcpServers" object. The "type": "streamable-http" is important — it tells Windsurf to use HTTP transport with real-time progress streaming.

Step 2: Restart Windsurf

MCP configs load on startup. Close Windsurf completely and reopen it.

Step 3: Authenticate

Open Windsurf's AI chat (default hotkey: Cmd+Shift+I or Ctrl+Shift+I) and say:

Check my connected ad platforms

Windsurf will prompt you to authorize Adspirer. Your browser opens automatically for OAuth 2.1 sign-in. Connect your ad accounts (Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads) and approve permissions.

Step 4: Verify the Connection

After authenticating, Windsurf should show you a table of your connected accounts with names, IDs, and connection status. If you see your ad platforms listed, you're ready to go.

What You Can Do

100+ tools across 4 ad platforms, accessible from Windsurf's AI chat:

Plus 8 automation tools for scheduling, monitoring, and cross-platform reporting.

Example Prompts

What to ask Windsurf once you're connected:

Google Search Campaign

Create a Google Search campaign for my fitness app:
- Product: personal training app with AI workout plans, $14.99/mo
- Target: fitness enthusiasts aged 25-45
- Budget: $60/day
- Research keywords with CPC data first
- Include negative keywords for free workout searches

Google PMax Campaign

Set up a PMax campaign for my online store:
- Product: handmade ceramic mugs, $34 average order
- Target ROAS: 400%
- Product images: [paste URLs]
- Write 5 headlines and 4 descriptions
- Connect to my Merchant Center feed

Meta Ads Campaign

Launch a Meta video campaign for my meal prep service:
- Target: busy professionals aged 28-42, interests in healthy eating and meal planning
- Budget: $45/day
- Video URL: [paste URL]
- Write 3 primary text variations
- Optimize for sign-ups

LinkedIn Ads Campaign

Create a LinkedIn campaign for my HR tech startup:
- Product: AI-powered applicant tracking system
- Target: HR Directors and Talent Acquisition VPs
- Company size: 500-10,000 employees
- Budget: $100/day
- Goal: demo requests
- Image URL: [paste URL]

Wasted Spend Audit

Audit all my ad accounts for the last 30 days:
- Google: keywords with spend but zero conversions
- Meta: ads with frequency > 4 and declining CTR
- LinkedIn: audience segments with CPA above $80

Prioritize actions by potential monthly savings.

Agent Skills (Coming Soon)

For now, Windsurf has full access to all 100+ Adspirer tools. You just need to be more explicit in your prompts about the workflow you want — for example, "research keywords before suggesting a campaign" instead of assuming the AI will know to do that automatically.

Safety Features

• All campaigns created PAUSED: Review before they spend money
• User confirmation prompts: Windsurf asks before actions that affect spend
• OAuth 2.1 with PKCE: No passwords or API keys stored locally
• Connection verification: Tools check that you're managing the correct account

Troubleshooting

Windsurf doesn't recognize Adspirer tools

Check your MCP config file:

cat ~/.codeium/windsurf/mcp_config.json

Make sure the JSON is valid (no trailing commas, proper quotes). Verify the "type" is set to "streamable-http". Restart Windsurf after any config changes.

"Connection failed" error

Your firewall or network might be blocking the MCP connection. Try:

• Whitelisting mcp.adspirer.com in your firewall
• Checking if your company VPN blocks external HTTP connections
• Testing with a different network to isolate the issue

OAuth flow not opening in browser

Some browser settings block automatic redirects. Try:

• Manually visiting adspirer.ai and signing in first
• Checking your default browser settings (Windsurf uses your system default)
• Disabling browser extensions that block pop-ups

Tools returning errors or "limit exceeded"

Check your account status at adspirer.ai. Free accounts get 10 tool calls/month. If you've hit the limit, upgrade to Plus ($25/mo for 50 calls) or Pro ($75/mo for 100 calls).

Config file doesn't exist

If ~/.codeium/windsurf/mcp_config.json doesn't exist, create the directory structure first:

mkdir -p ~/.codeium/windsurf
echo '{"mcpServers":{"adspirer":{"type":"streamable-http","url":"https://mcp.adspirer.com/mcp"}}}' > ~/.codeium/windsurf/mcp_config.json

FAQ

What's the difference between Windsurf and Cursor?

Both are AI-powered code editors with MCP support. Cursor is built on VS Code and has mature Cursor Rules support. Windsurf is built by Codeium with a different AI model and UX. Choose based on which editor you prefer — both work equally well with Adspirer.

Can I use Windsurf Flow mode with Adspirer?

Yes. Windsurf Flow (the multi-step agentic mode) has full access to Adspirer tools. You can ask Flow to analyze campaigns, generate reports, and save the output as files in your project — all in one autonomous task.

Will skills be available for Windsurf?

Yes. Skills support is in development and will be added to the ads-mcp GitHub repo soon. Follow the repo for updates.

Can I manage multiple ad accounts?

Yes. Connect multiple Google Ads accounts, multiple Meta Business Managers, etc. Use the switch_primary_account tool to change which account you're managing, or specify the account ID in your prompts.

How much does Adspirer cost?

Pricing is based on tool calls, not ad spend. Free tier: 10 calls/month. Plus: $25/mo for 50 calls. Pro: $75/mo for 100 calls. See full pricing details.

Related Documentation

• Claude Code Setup Guide
• Cursor Setup Guide
• Codex Setup Guide
• OpenClaw Setup Guide
• Google Ads Integration
• Pricing & Plans
• All Documentation