By Ira Bodnar, Ryze AI · Updated · Connector tested November 13, 2026
Quick answer
The main way to connect Windsurf to Meta Ads is the Ryze AI connector. Connect Meta Ads once in a Ryze AI workspace, then put "ryze": {"url": "https://connector.get-ryze.ai/mcp"} under mcpServers in ~/.config/devin/mcp_config.json. Sign in with the Authenticate button in Devin Desktop, or with devin mcp login ryze in Devin CLI, click Allow connection, and ask the agent about your Meta ad accounts.
- In Ryze AI open Integrations, find Meta Ads and click Connect with your Meta login
- In Windsurf open Customize, then MCPs, and add the ryze server with the connector URL
- Click Authenticate on the ryze server (devin mcp login ryze in Devin CLI), then Allow connection on the Ryze AI page
- Ask the agent which Meta ad accounts it can see
Windsurf to Meta Ads at a glance
| Fact | Detail |
|---|---|
| Main way to connect | The Ryze AI connector, kept in Devin's mcp_config.json as one url entry named ryze, or added with devin mcp add in Devin CLI |
| Server address | https://connector.get-ryze.ai/mcp. The same entry also carries the other platforms connected in the Ryze AI workspace |
| Windsurf in November 2026 | Shipped as Devin Desktop since June 2, 2026. Devin Local is the agent that calls MCP tools; Cascade was removed on September 8, 2026 |
| Sign-in | Meta is approved once inside Ryze AI. Windsurf then signs in to Ryze AI through browser OAuth and registers itself, so no client ID is pasted |
| Meta Ads tools | 10 in total: 7 read, 2 write, 1 delete |
| Can it change ads | Yes. One write tool creates and edits campaigns, ad sets, ads and creatives, a second uploads images, and a delete tool deletes or archives. Devin Local asks before each MCP tool call by default |
| Windsurf plan needed | Cognition's MCP pages name none and the Devin pricing page has no MCP row. The admin MCP settings carry the label Teams & Enterprise |
| Ryze AI price | Paid Ads at $89 per month after a 7-day free trial. Adding the connector costs nothing |
| Meta's own option for Windsurf | Meta hosts an ads MCP server at https://mcp.facebook.com/ads. Meta's pages name ChatGPT, Claude, Perplexity and Claude Code; Windsurf is not among them |
| Meta access of the connection | 11 Meta permissions from one Meta login. Organic posting and reading Page comments are outside them, and no tool exports leads |
| Last tested | Connector sign-in checks on November 13, 2026 and 11 Meta Ads calls on November 14, 2026. No step inside Windsurf was run |
Windsurf was renamed Devin Desktop on June 2, 2026; Cognition's changelog, its rename post and its FAQ all give that date. The MCP documentation moved to Devin's site: docs.windsurf.com/windsurf/cascade/mcp redirects to docs.devin.ai, and windsurf.com redirects to devin.ai/desktop, titled Devin Desktop. This guide keeps the name Windsurf because that is what people search for, and uses the menu names and file paths from the current Devin docs. Cascade conversations can no longer be started, so any older step that opens a Cascade MCP panel is out of date. If your install looks different, check which Customize page it shows.
Before you start
- Windsurf (Devin Desktop) on Mac, Windows or Linux. Cognition's MCP documentation names no plan for adding a server. The Devin Local page says Enterprise admins manage MCP registries under MCP & ACP in team settings, and the admin reference lists the MCP allowlist and registry settings under Teams & Enterprise, so on a team account an admin may need to approve the Ryze AI server first.
- A Meta login that can reach your ad accounts. You need a Meta Business account with an ad account and at least Advertiser access on it, ideally granted through Meta Business Manager. The Ryze AI help center asks for Admin access before it allows changes, although Meta's own role table already lets an Advertiser create and edit ads. For a hard read-only setup, connect a Meta login that only has read access.
- A Ryze AI workspace on a plan or free trial. Paid Ads is $89 per month with a 7-day free trial; Agency is $279 per month for agencies. Connecting the connector is free, but the Meta Ads tools need an active plan or trial.
How to connect Windsurf to Meta Ads
Two steps happen in Ryze AI and Meta, four in Windsurf. The connector URL is the same for every user.
Connect Meta Ads in Ryze AI
Create a Ryze AI account or sign in, open Integrations in the left sidebar and find Meta Ads under Advertising. Click Connect, sign in to Meta and approve access with every requested permission checked.
Check the connection
Back in Ryze AI the Meta Ads card shows Connected. There is no ad account to pick: Ryze AI sees every ad account that login can reach. To choose the accounts the agent works with first, click View on the card and use Agent default accounts.
Open the MCP settings in Windsurf
From the Agents window open the Customize page and click MCPs. Use Install MCPs for to pick the scope, for example This computer.
Add the Ryze AI server
Open the config file and add the server under mcpServers: "ryze": {"url": "https://connector.get-ryze.ai/mcp"}. The user file is ~/.config/devin/mcp_config.json and the project file is .devin/mcp_config.json.
Sign in to the connector
Refresh the list under This computer. When the ryze server wants authorization it offers an Authenticate button: click it, finish the Ryze AI sign-in in your browser and click Allow connection. In Devin CLI the matching command is devin mcp login ryze.
Ask your first question
Ask: List the Meta ad accounts you can access with their currency, then show spend, ROAS and CTR for the last 30 days. Approve the tool calls when Windsurf asks.
The Ryze AI help article for Meta Ads covers the Meta side of the connection, and the Ryze AI help article on API keys and the MCP endpoint covers the connector URL.
Sources: Devin Desktop: MCP and customizations, Devin CLI: MCP configuration, Devin Desktop changelog, Ryze AI Meta Ads guide. Checked November 14, 2026.
Config file, Devin CLI and imports
Windsurf now runs on Devin, so the same server can be added in the editor settings, in a config file or from the Devin CLI. Pick the route that matches how you work.
Devin Desktop (Windsurf) config file
{
"mcpServers": {
"ryze": {
"url": "https://connector.get-ryze.ai/mcp"
}
}
}Use ~/.config/devin/mcp_config.json when you want Ryze AI in every project, or .devin/mcp_config.json to keep it with one repository. That project file travels through version control to everyone on the repository; for an entry only you should get, Devin reads the gitignored .devin/mcp_config.local.json. Devin Local supports stdio, Streamable HTTP and SSE with OAuth for each, trying Streamable HTTP first and falling back to SSE on non-auth 4xx errors.
Devin CLI
devin mcp add -s user ryze https://connector.get-ryze.ai/mcp
devin mcp login ryzeThe first command registers the server in your user config. The second opens the Ryze AI sign-in, where you click Allow connection. Run these in a terminal when you prefer not to edit JSON by hand. Leave out -s user and the entry lands in the gitignored local file of the folder you are in.
Servers kept in an old Windsurf file
Cognition's import page says Devin CLI picks up MCP servers from the old Windsurf file ~/.codeium/<channel>/mcp_config.json (the stable channel reads ~/.codeium/windsurf/), so for the CLI an entry there does not need adding twice. That page is written for the CLI. For Devin Desktop the FAQ only says Windsurf settings carry over to Devin Local, so look at the This computer list before you add ryze a second time. Some older Ryze AI pages show the key serverUrl for Windsurf. Only Cognition's page for the JetBrains plugin mentions serverUrl, and the reference that Devin Desktop follows lists url, so this guide uses url.
Sign-in and limits
OAuth uses dynamic client registration by default, so you enter no client ID or secret for the Ryze AI connector. Each MCP client keeps its own OAuth session, so signing in to Ryze AI from another tool does not carry over to Windsurf. The Devin Local page describes Needs authentication for expired credentials only. For the first sign-in, the July 29, 2026 release note gave servers that need authorization an Authenticate button, and the Devin CLI page says an OAuth server asks for a sign-in the first time it is used. Since November 8, 2026 the "..." menu in a session header can also re-authenticate a server.
Windsurf and MCP: the facts in one table
| Topic | What Cognition's documentation says |
|---|---|
| Where you add a server | The MCPs tab of the Customize page in the Agents window, with Install MCPs for set to a scope such as This computer. Its Available list installs servers from MCP registries |
| Config files | User: ~/.config/devin/mcp_config.json, or %APPDATA%\devin\mcp_config.json on Windows. Project: .devin/mcp_config.json. Private override inside a project: .devin/mcp_config.local.json, ignored by git |
| A remote entry | url is the one required field. transport, headers, oauthClientId, oauthClientSecret, oauthResource, oauthScopes, disabled and disabledTools are optional |
| Transports | stdio, Streamable HTTP and SSE. A url goes over Streamable HTTP first; SSE is tried on the same address only after a 4xx that is not about sign-in |
| Sign-in | OAuth with dynamic client registration. A 401 carrying a WWW-Authenticate challenge is treated as a request to sign in, and the server URL travels as the OAuth resource |
| Static keys | A token for a remote server goes in headers. ${env:VAR} and ${file:/path} keep the secret itself out of the file |
| Tool names | mcp__<server>__<tool>. By that pattern the Ryze AI account list would be mcp__ryze__meta_ads__listAdAccounts; this guide did not see the name in Windsurf |
| Approval | Devin Local asks before every MCP tool call. A grant covers one tool or the whole server, for the session or for good |
| Rules and modes | Allow, Deny and Ask rules in Devin Local settings take patterns such as mcp__ryze__*, and deny wins. Bypass Permissions mode skips the prompts unless the organization requires approval |
| Where servers are managed | The This computer list (switch on or off, open the config file, refresh) and, since November 8, 2026, the "..." menu of a session header. Each server logs to its own MCP: <server> channel |
| Admin controls | Allow MCP, MCP allowlist, MCP registry and MCP registry URLs, labeled Teams & Enterprise. A single allowlisted server shuts out every other one |
| Plan | Plans are Free, Pro, Max, Teams and Enterprise. None is named for adding an MCP server |
| JetBrains plugin | Windsurf Plugins for JetBrains add servers under Settings > Tools > Windsurf Settings > Add Server. Cognition says that plugin is in maintenance mode |
Sources: Devin Desktop: MCP and customizations, Devin CLI: MCP configuration, Devin CLI: MCP overview, Devin CLI: config file, Devin CLI: read config from other tools, Devin Local permissions, Devin Local modes, Devin Desktop admin controls, Devin Desktop usage and plans, Devin Desktop FAQ, Windsurf Plugins MCP page. Checked November 14, 2026.
Other clients
The same URL works in other MCP clients. Meta Ads is connected once in Ryze AI, so nothing changes on the Meta side.
Claude Code
Run claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp --scope user, then /mcp inside Claude Code to sign in.
Claude on the web and Desktop
Open Customize, Connectors, click + Add, choose Add custom connector, name it Ryze AI and enter the URL. In Claude you can set write and delete tools to Needs approval under Customize > Connectors > Ryze AI.
Codex
Run codex mcp add ryze --url https://connector.get-ryze.ai/mcp, then codex mcp login ryze.
Cursor
Add the server to ~/.cursor/mcp.json or .cursor/mcp.json.
{ "mcpServers": { "ryze": { "url": "https://connector.get-ryze.ai/mcp" } } }Meta Ads permissions and Windsurf settings
Two things decide what the Windsurf agent can do in Meta: the Meta login you connect in Ryze AI, and the approval behavior in Devin Desktop.
- Which Meta login
- You sign in to Meta from the Integrations page in Ryze AI and approve access with every requested permission checked. The requested scopes are ads_management, ads_read, business_management, pages_show_list, pages_read_engagement, pages_manage_ads, leads_retrieval, catalog_management, instagram_basic, instagram_manage_comments and public_profile.
- Which ad accounts
- One login reaches every ad account it can access. Anything outside that reach is invisible to Windsurf. To add another login, click View on the Meta Ads card and choose Add one more account; a star marks the primary account that the agent uses when you name none.
- Read or write
- Meta's role table lets an Advertiser create and edit ads and limits an Analyst to viewing. The Ryze AI help center sets Advertiser as the minimum and asks for Admin before it allows changes. A Meta login with read access only is the way to guarantee the Windsurf agent cannot change an ad account.
- Approvals in Windsurf
- By default Devin Desktop asks for approval before the agent calls any MCP tool. Approvals set in Ryze AI chat, such as Skip all approvals, apply to the Ryze AI chat and not to Windsurf.
- Team rules
- On Teams and Enterprise, admins manage MCP registries and the MCP allowlist under MCP & ACP in team settings, which can block or approve the Ryze AI server for everyone.
The 11 Meta permissions of the default connection
Windsurf itself only holds a Ryze AI sign-in, whose discovery files name the scopes mcp:read and mcp:write. The Meta permissions stay with the Ryze AI Meta app, which asks for 11 of them when you connect. The list comes from the Ryze AI app, not from a consent screen read for this guide. The middle column is how Meta's permissions reference describes each one.
| Meta permission | What Meta says it allows | Also asked for by Meta's ads MCP server |
|---|---|---|
| ads_read | Pulling Ads Insights reports for ad accounts you own or were given access to | Yes |
| ads_management | Reading and managing those ad accounts: creating campaigns, managing ads, fetching metrics | Yes |
| business_management | Reading and writing through the Business Manager API, such as managing or claiming an ad account | Yes |
| pages_show_list | The list of Pages a person manages | Yes |
| pages_read_engagement | Content a Page posted, follower data, profile picture and Page insights | No |
| pages_manage_ads | Managing the ads tied to a Page | Yes |
| leads_retrieval | Everything a lead ads form captured | No |
| catalog_management | Creating, reading, updating and deleting product catalogs the user administers | Yes |
| instagram_basic | Profile information and media of an Instagram account | Yes |
| instagram_manage_comments | Creating, deleting and hiding comments for the Instagram account linked to a Page | No |
| public_profile | The default public profile fields, which Meta grants to every app | No |
Left out of the request: pages_manage_posts and instagram_content_publish, which Meta requires for organic Page and Instagram posts; pages_read_user_content, which covers what other people write on a Page; and ads_mcp_management, the permission behind Meta's own ads MCP server, since Ryze AI calls the Marketing API directly. Three granted permissions have no tool of their own: leads_retrieval (meta_ads__listLeadForms lists forms, and no tool exports leads), catalog_management (catalog work would go through the Graph read and write tools) and instagram_manage_comments (no documented job uses it). Meta's server in turn asks for facebook_branded_content_ads_brand and instagram_branded_content_ads_brand, which Ryze AI does not.
Meta ad account roles
The Meta role of the connected login caps what the Windsurf agent can do on each ad account. Meta's help center describes three roles.
| Meta role | What Meta says it covers | For the Windsurf agent |
|---|---|---|
| Admin | Viewing ads and reports, creating and editing ads, the payment method and admin permissions | The level the Ryze AI help center asks for before changes |
| Advertiser | Viewing ads and reports, creating and editing ads; no payment method or access changes | The minimum in the Ryze AI help center |
| Analyst | Viewing ads and reports only | Meta's view-only role. Connecting one was not tested for this guide |
Ads that run for a Facebook Page need one more thing on Meta's side: full control or partial access (Ads) on that Page, plus a professional Instagram account connected to it for Instagram ads.
Sources: Meta permissions reference, Meta: ad account roles, Meta Marketing API authorization, Ryze AI Meta Ads guide. Checked November 14, 2026.
Removing access
Inside Windsurf you have four options: turn the ryze toggle off under Customize > MCPs, add "disabled": true to the entry so its tools disappear, delete the entry from mcp_config.json, or run devin mcp remove ryze. Running devin mcp logout ryze forgets the saved sign-in and keeps the server. To end Meta access as well, click View on the Meta Ads card in Ryze AI and disconnect the login.
What Windsurf can do in Meta Ads
The Ryze AI connector exposes 10 Meta Ads tools: 7 read, 2 write and 1 delete. Each runs with the access of the Meta login you connected. By Cognition's naming pattern, Devin shows each one as mcp__ryze__ followed by the name below.
| Tool | Type | What it does |
|---|---|---|
| meta_ads__listAdAccounts | Read | Lists every Meta ad account the connected user can access, with id, name and currency. |
| meta_ads__getAccountSummary | Read | Aggregate metrics for an ad account on Meta's default attribution window. |
| meta_ads__runRawInsights | Read | Raw Insights queries at account, campaign, ad set or ad level, with breakdowns, filters and custom attribution windows. |
| meta_ads__listCreatives | Read | The ad creatives in an ad account. |
| meta_ads__getCreative | Read | One ad creative by id. |
| meta_ads__listLeadForms | Read | The lead generation forms on a Facebook Page. |
| meta_ads__runGraphRead | Read | Any Graph API object or edge, such as paused campaigns, targeting specs or the ad account activity log. |
| meta_ads__runGraphWrite | Write | Creates or updates campaigns, ad sets, ads, creatives and other objects through the Meta Graph API. |
| meta_ads__uploadImageFromUrl | Write | Uploads an image from a URL to an ad account and returns an image hash for a creative. |
| meta_ads__runGraphDelete | Delete | Deletes or archives Meta objects. Its description says it is meant for an explicit item-by-item approved list. |
Approvals in Windsurf
Devin Desktop asks before calling any MCP tool by default, so reads and changes both prompt until you change that. Loosening it for the ryze server also removes the prompt in front of the write and delete tools, so allow only what you need. Archived or deleted Meta objects cannot be restored through Ryze AI. The pacing of edits, creative writes included, comes from Meta; the limits table below and the troubleshooting row on slow creative writes give the numbers. Scheduled tasks in Ryze AI run without an approval step.
To keep the delete tool out of reach, add a Deny rule for mcp__ryze__meta_ads__runGraphDelete in Devin Local settings, or list meta_ads__runGraphDelete under disabledTools in the ryze entry. Both follow Cognition's documentation and were not tried in Windsurf.
Limits in numbers
| Limit | Number |
|---|---|
| Meta call score | Counted per ad account: a read adds 1 point and a write 3. The development tier stops at 60 points and blocks for 300 seconds; Full access stops at 9,000 and blocks for 60 seconds. Points decay over 300 seconds. Errors 17 and 613 |
| Ads management calls per hour | Per ad account: 100,000 on Full access, or 300 plus 40 for every active ad on the development tier. Error 80004 when spent |
| Insights calls per hour | Per ad account: 190,000 on Full access, or 600 plus 400 for every active ad on the development tier, less 0.001 per user error. Error 80000 when spent |
| Edits to one object | By default one every 30 seconds, per app. A faster edit gets error 613, subcode 4841018 |
| Ad set budget changes | daily_budget or lifetime_budget may change 4 times in an hour; the next change is blocked for an hour (error 613, subcode 1487632) |
| Report history | 37 months back. An older start date fails with error 3018 |
| Time slices | time_increment accepts 1 to 90 days, monthly or all_days |
| Freshness | Insights refresh every 15 minutes and stop changing 28 days after they are reported |
| Ryze AI tool inputs | meta_ads__runGraphRead: a path of up to 4,096 characters and fields of up to 2,048. Write and delete paths: up to 512. meta_ads__listCreatives: 100 creatives by default, 1,000 at most |
| Windsurf side | Cognition's pages read on November 14, 2026 give no cap on the number of MCP servers or tools in Devin Local |
This guide could not see which Marketing API access tier the Ryze AI Meta app holds, so both tiers are shown. None of the test responses carried Meta's usage headers or a usage percentage.
Sources: Meta Marketing API rate limiting, Meta Graph API rate limiting, Meta Insights best practices, Meta ad account Insights reference. Checked November 14, 2026.
Meta Ads calls through the connector, tested
These are the 11 Meta Ads calls behind this guide, sent on November 14, 2026 from Claude Code, a different MCP client, through the same connector Windsurf uses. The Meta login behind that workspace reaches real ad accounts, so no account name, ID or number appears here. Ten calls were meant to fail, to capture the exact replies.
| What the call asked for | Tool | Result |
|---|---|---|
| Every ad account the login can open | meta_ads__listAdAccounts | Worked: one entry per account with id, account_id, name and currency |
| The campaigns edge of an ad account, with a made-up field as the only field | meta_ads__runGraphRead | No error: rows holding an id each, plus paging cursors |
| An ad account node, with a made-up field | meta_ads__runGraphRead | No error: the node id alone |
| An object ID that does not exist | meta_ads__runGraphRead | Meta refused it: code 100, subcode 33 |
| act_<id>/not_an_edge_xyz, an edge that does not exist | meta_ads__runGraphRead | Meta refused it: code 2500 |
| A fields string 2,100 characters long | meta_ads__runGraphRead | The connector refused it before Meta saw it: invalid_arguments, maximum 2048 |
| An Insights field name that does not exist | meta_ads__runRawInsights | Meta refused it: code 100 |
| A made-up ad account ID outside the login's reach | meta_ads__runRawInsights | Refused: status not_allowed, carrying Meta error 200 |
| The attribution window 99d_click | meta_ads__runRawInsights | Meta refused it: code 100, listing 26 accepted values |
| A report for January 2020 | meta_ads__runRawInsights | Meta refused it: code 3018, the 37-month limit |
| timeIncrement set to 91 | meta_ads__runRawInsights | Meta refused it: code 100, since 90 is the most |
Worth knowing when the Devin Local agent writes Graph queries for you: the meta_ads__runGraphRead description says one unknown field fails the whole read, yet in both tests the made-up field was skipped and only ids came back. A misspelled Graph field can therefore look like an empty answer, while a misspelled Insights field does raise an error.
First 3 prompts to run
Answers come from your own ad accounts, so each prompt says what comes back and shows no sample numbers.
1. Which ad accounts can the agent see
List every Meta ad account I can access with id, name and currency.
Tools used: meta_ads__listAdAccounts
What comes back: One line per ad account. A missing account means the connected login has no access to it.
2. Spend and ROAS by placement
For my main ad account, run an Insights query for the last 30 days with spend, ROAS and CTR, broken down by placement and age.
Tools used: meta_ads__runRawInsights
What comes back: A table of spend, ROAS and CTR for each placement and age group, from Meta's Insights data.
3. Who changed the account
Read the ad account activity log for the past two weeks and list who changed budgets, status or targeting.
Tools used: meta_ads__runGraphRead
What comes back: Each change with the person, the object and the time, as the activity log records it.
To change something, describe it in plain words, such as pausing a named ad set or adjusting a budget, and keep Windsurf's approval prompt on for the ryze server.
10 jobs to hand to the Windsurf agent
Ten jobs to give the Devin Local agent, each tied to the tool it would use. Only the first one ran on November 14, 2026; the others follow the Ryze AI facts and the tool definitions. A job that changes something waits for your click in Windsurf unless you allowed the tool.
| Job | Ask the agent | Tool | Works on the default connection |
|---|---|---|---|
| Account check | Which Meta ad accounts can you open? Give me id, name and currency for each. | meta_ads__listAdAccounts | Yes. Run on November 14, 2026 |
| Quick account totals | Show spend, ROAS and CTR for my main ad account over the last 14 days. | meta_ads__getAccountSummary | Yes, on Meta's default attribution window only |
| Breakdown report | Break last month's results down by country and device for each campaign. | meta_ads__runRawInsights | Yes, for start dates inside the last 37 months |
| Creative inventory | List the creatives in this ad account with their ids. | meta_ads__listCreatives | Yes. 100 per call unless you ask for up to 1,000 |
| Lead form check | List the lead forms on the Facebook Page with the ID I give you. | meta_ads__listLeadForms | Yes, when the login has a role on that Page. It lists forms, not leads |
| Change log | Read the activity log of this ad account for the last 7 days and group the changes by person. | meta_ads__runGraphRead | Yes |
| Budget change | Raise the daily budget of the ad set I name by 10 percent and show the old and new values. | meta_ads__runGraphWrite | Yes, with an editing role and your approval. Budgets are in minor units, so 5000 means 50.00. Meta allows 4 budget changes per ad set per hour |
| New creative image | Upload the image at this URL to my ad account and give me the image hash. | meta_ads__uploadImageFromUrl | Yes, with the same role and approval. Video goes through meta_ads__runGraphWrite with a video URL |
| Cleanup | Archive the three paused ads I list, one at a time, after I confirm each. | meta_ads__runGraphDelete | Yes. Archived and deleted objects cannot be restored |
| Organic Instagram post | Post this photo to our Instagram account. | None | No. The Ryze AI Meta app does not hold instagram_content_publish |
3 ways to connect Windsurf to Meta Ads
Three ways reach Meta Ads from Windsurf, counting only routes whose own pages name Windsurf. This guide uses the Ryze AI connector as the main way: Devin Desktop needs one url entry, Meta is approved once inside Ryze AI, and no Meta developer app of your own is involved. Supermetrics names Windsurf in its FAQ and Zapier lists it among its MCP clients, so both are described with what they reach. Every setup cell describes the route inside Windsurf. None of the three was run in Windsurf for this guide.
| Way | Runs where | Setup in Windsurf | What it reaches in Meta Ads | Price |
|---|---|---|---|---|
| Ryze AI connector (the main way) | Hosted by Ryze AI at one address | One url entry named ryze in mcp_config.json, or devin mcp add -s user ryze with the address. Sign in with Authenticate in Devin Desktop or devin mcp login ryze in Devin CLI | 10 tools: account lists and summaries, raw Insights with breakdowns, creatives, lead forms, any Graph read, Graph writes, image upload, and delete or archive. Other platforms connected in the same workspace come through the same entry | Paid Ads, $89 per month after a 7-day free trial |
| Supermetrics MCP | Hosted by Supermetrics | Log in at mcp.supermetrics.com, add the endpoint it gives you as its own entry in mcp_config.json and authorize with OAuth 2.0. The product page's FAQ lists Windsurf | Facebook Ads. A Supermetrics help article updated November 12, 2026 says campaigns can be created and updated from an AI tool, each proposed change is shown before it is applied, and new campaigns start paused | Included in Supermetrics plans that have Data API access. 14-day free trial with no credit card |
| Zapier MCP | Hosted by Zapier | Windsurf is on the quickstart's list of further MCP clients. Zapier's steps: add Zapier as a connector and sign in, and it links the client to your default server. Clients with Streamable HTTP can also use a connection token | Zapier has no Meta Ads app page. Three Meta apps have MCP actions: Facebook Lead Ads (1), Facebook Custom Audiences (4) and Facebook Conversions (4). None reads campaign results or edits a campaign | 2 tasks from your Zapier plan for each successful tool call; failed calls use none |
Meta Ads options that do not fit Windsurf
- Meta's ads MCP server at https://mcp.facebook.com/ads. Meta's marketing page lists ChatGPT, Claude and Perplexity as supported AI tools, and its developer page has a command for Claude Code; no Meta page read for this guide names Windsurf. Meta's overview says the server works with any MCP-compatible AI agent, and the marketing page adds that developers can connect other applications with their own Meta app. That route has been open since July 16, 2026: the app gets the use case Create & manage ads with ads MCP server, and sign-in runs through Facebook Login for Business or your own access tokens. Its seven tool categories span reporting, campaign, ad set and ad creation and edits, catalogs, signals and datasets, Business Help Center search, A/B tests and lift studies, and the activity log: 88 tool names on Meta's pages. New campaigns start paused, Meta charges nothing extra to connect, and the connectors are an open beta that not every ad account has yet. It was not tried in Windsurf.
- Meta's Ads CLI (command meta, package meta-ads, version 1.3.1). A terminal tool for macOS and Linux that signs in with a system user access token and creates resources paused by default. Meta's pages name no assistant for it; they speak of developers and AI agents that run shell commands.
- Composio's Metaads toolkit. Its pages name Claude Code, Cursor, ChatGPT, Claude Cowork, Antigravity, Codex, VS Code, OpenCode, OpenClaw, Grok Bot, Grok Build, Kimi Code, Muse and Hermes, but not Windsurf. It lists 99 Meta tools and runs every Meta connection through an OAuth app you register with Meta yourself.
- Pipeboard (pipeboard-co/meta-ads-mcp), hosted at https://meta-ads.mcp.pipeboard.co/ or run from source. Its README names Claude, ChatGPT, Perplexity and Cursor, plus Claude Code and Codex for its CLI. Windsurf is not named. The free plan allows 30 tool runs a week.
- Windsor.ai names Claude, ChatGPT, Microsoft Copilot, Gemini Enterprise and Perplexity, then other clients that support remote MCP servers in general, without naming Windsurf. It reads 656 Meta metrics and 212 dimensions and has 20 write actions that run after you approve them.
- Coupler.io names Claude, ChatGPT, Gemini, Perplexity, Cursor, Copilot, OpenClaw and Claude Code, not Windsurf. The assistant gets read-only answers from Facebook Ads data that Coupler.io syncs on a schedule.
- Meta AI business assistant lives inside Ads Manager. It gives guidance and campaign recommendations there and is not a route for an outside assistant such as Windsurf.
Which one to pick
Ryze AI is the best way to connect Windsurf to Meta Ads when you want Insights reports and campaign edits behind one url entry in Devin Desktop, with three caveats: the tools stop when the Ryze AI plan or trial ends, your Meta data passes through Ryze AI, and organic posts, Page comments and lead export are out of reach. In return the same entry carries the other platforms in the workspace, and the Ryze AI app adds its own chat with approval settings and Managed Campaigns. Supermetrics suits a team that already pays for Supermetrics Data API access. Zapier fits when the job is sending conversion events or keeping a custom audience current. If you want Meta's first-party server and can register a Meta app of your own, Meta's route for other applications is the one to try, knowing Meta publishes no Windsurf steps. Devin reads several named servers from one config file, so adding a second route leaves ryze in place.
Sources: Meta: ads MCP server page, Meta: ads MCP server overview, Meta: ads MCP server get started, Meta: ads MCP server update, July 16, 2026, Meta: Ads CLI overview, Meta: ads AI connectors announcement, Supermetrics MCP, Supermetrics: managing ad campaigns with AI tools, Zapier MCP quickstart, Zapier: Facebook Lead Ads, Zapier: Facebook Custom Audiences, Zapier: Facebook Conversions, Composio Metaads toolkit, Pipeboard meta-ads-mcp, Pipeboard pricing, Windsor.ai Facebook Ads MCP, Coupler.io Facebook Ads MCP, Devin Desktop: MCP and customizations, Ryze AI Meta Ads guide. Checked November 14, 2026.
Windsurf, Meta Ads and MCP: dates that matter
| Date | What happened |
|---|---|
| February 13, 2025 | Windsurf Wave 3 brought MCP servers to Cascade, on individual plans first (Cognition launch post). |
| July 17, 2025 | Windsurf 1.11.0 added the Streamable HTTP transport and MCP authentication in place of access tokens or API keys in the config. |
| April 29, 2026 | Meta put its ads AI connectors, the ads MCP server and the Ads CLI, into open beta. The same day Windsurf 2.1.29 opened Devin for Terminal to all Windsurf users and let Devin Local be switched on. |
| May 4, 2026 | Meta renamed its access levels Marketing API Access Tier and lowered the bar for Full access from 1,500 to 500 calls in 15 days. |
| June 2, 2026 | Windsurf became Devin Desktop (v3.0.12). |
| July 16, 2026 | Meta let any AI application connect to its ads MCP server through your own developer app, and added ads MCP server rules. |
| July 29, 2026 | Devin Desktop 3.6.22 gave servers that need authorization an Authenticate button. |
| September 8, 2026 | Devin Desktop 3.9.19 removed Cascade, leaving Devin Local as the only built-in agent. |
| October 12, 2026 | Devin Desktop 3.10.67 started connecting on MCP protocol revision 2026-07-28. |
| October 27, 2026 | Three Marketing API v26.0 changes reached every version: poll ads ended, applink_treatment=web_only was deprecated for Web and App campaigns, and housing, employment and financial campaigns with constrained targeting must set advantage_audience explicitly. |
| November 4, 2026 | Marketing API v27.0 came out. It was still the current version on November 14, 2026. |
| November 8, 2026 | Devin Desktop 3.12.32 put each session's MCP servers in the "..." menu of the session header. |
| November 10, 2026 | Marketing API v24.0 stopped being available. |
Sources: Devin Desktop changelog, Cognition: Windsurf Wave 3, Cognition: Windsurf is now Devin Desktop, Meta: ads AI connectors announcement, Meta: ads MCP server update, July 16, 2026, Meta Marketing API changelog, Marketing API v26.0, Marketing API v27.0, Marketing API versions. Checked November 14, 2026.
How this guide was tested
Two rounds of checks stand behind this guide: the connector's sign-in answer on November 13, 2026, and Meta Ads calls through the connector on November 14, 2026. Each row names what was run and what came back.
| What was run | What came back |
|---|---|
| Connector address without a sign-in, November 13, 2026 | https://connector.get-ryze.ai/mcp answered HTTP 401 with a WWW-Authenticate header that points to the sign-in details. Cognition's reference says Devin reports such a 401 as a sign-in request instead of falling back to SSE. |
| Sign-in details, November 13, 2026 | Both discovery files loaded. They name the authorize, token and register endpoints, the authorization code and refresh token grants, PKCE with S256, and the scopes mcp:read and mcp:write. The register endpoint is the piece that dynamic client registration in Devin relies on. |
| Tool list in a signed-in MCP client, November 14, 2026 | All 10 meta_ads tools loaded: 7 read, 2 write, 1 delete. Each accepts an optional connection_id. |
| meta_ads__listAdAccounts, November 14, 2026 | Worked. Every ad account came back with id, account_id, name and currency; none of them is shown here. |
| Ten calls built to fail, November 14, 2026 | Eight were refused with a message, all quoted in the errors table below. Two came back with ids only, because the made-up field was ignored. |
| Meta's own server without a sign-in, November 14, 2026 | Not a Ryze AI call. https://mcp.facebook.com/ads answered HTTP 401 with the title Authentication Required and a WWW-Authenticate header naming 10 Meta scopes. Its OAuth metadata lists the authorization code grant, PKCE with S256, token endpoint authentication none and a registration endpoint. |
Not run for this guide: any step inside Windsurf. Neither Devin Desktop nor Devin CLI was opened, so the mcp_config.json entry, the Authenticate button, devin mcp add, devin mcp login and the approval card are described from Cognition's documentation as it read on November 14, 2026. The Meta Ads calls came from Claude Code, another MCP client on the same connector. meta_ads__getAccountSummary, meta_ads__listCreatives, meta_ads__getCreative and meta_ads__listLeadForms were not called, and no Insights read was allowed to succeed, because each would return account data. The two write tools and the delete tool were not run, because they change the ad account. Meta's ads MCP server and Ads CLI were not used with a sign-in.
Windsurf and Meta Ads errors and fixes
Exact error messages from the test
Meta and the connector returned these messages word for word on November 14, 2026, with IDs replaced by <redacted>. If the Devin Local agent shows one of them, the row says what went wrong and what to ask next.
| Message | What it means | What to do in Windsurf |
|---|---|---|
| Unsupported get request. Object with ID '<redacted>' does not exist, cannot be loaded due to missing permissions, or does not support this operation. Please read the Graph API documentation at https://developers.facebook.com/docs/graph-api | Code 100, subcode 33. Meta sends this one answer for two cases: a wrong ID, or an object the connected login cannot see. | Have the agent list ad accounts or campaigns first and reuse an ID from that answer. If the object is real, check the login's access in Meta Business Manager. |
| (#100) not_a_field_xyz is not valid for fields param. please check https://developers.facebook.com/docs/marketing-api/reference/ads-insights/ for all valid values | The Insights API has no field by that name. The tool description lists the usual slips: ROAS is purchase_roas, status, placement and creative are not Insights fields, and landing page views arrive inside actions. | Ask again with a valid Insights field, or read object settings with meta_ads__runGraphRead instead. |
| Meta Graph error (code 200): (#200) Ad account owner has NOT grant ads_management or ads_read permission, refer to https://developers.facebook.com/docs/marketing-api/get-started/authorization/#permissions-and-features for details. | The connector answered with status not_allowed. The Meta login has no access to that ad account, or the ID has a typo. | Pick an ID from meta_ads__listAdAccounts, grant the login access in Meta Business Manager, or add a second Meta login in Ryze AI with View, Add one more account. |
| (#100) action_attribution_windows[0] must be one of the following values: 1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, 1d_ev, dda, default, 7d_view_first_conversion, 28d_view_first_conversion, 7d_view_all_conversions, 28d_view_all_conversions, skan_view, skan_click, skan_click_second_postback, skan_view_second_postback, skan_click_third_postback, skan_view_third_postback, incrementality, incrementality_first_conversion, incrementality_all_conversions, custom, 1d_sequenced, 7d_sequenced, 28d_sequenced | Meta does not accept that attribution window name. The message lists the 26 it does accept. | Choose one from the list. The tool description points to 1d_click, 7d_click, 28d_click and 1d_view, and says Meta returns a key only for windows it still supports. |
| (#3018) The start date of the time range cannot be beyond 37 months from the current date. The earliest start date available for this ad account is 2023-10-14. Set time_range or time_ranges to start on or after that date. | Insights data reaches back 37 months. The earliest date in the message is 37 months before the day of the call, November 14, 2026. | Start the date range inside the last 37 months. |
| (#100) Param name_placeholder must be a number less than or equal to 90 | time_increment, the length of one time slice in days, tops out at 90. Meta prints name_placeholder where the parameter name belongs. | Ask for slices of 1 to 90 days, or monthly, or all_days. |
| Unknown path components: /not_an_edge_xyz | Code 2500. The path names an edge that the object does not have. | Use a real edge such as campaigns, adsets, ads, adcreatives, customaudiences or activities. |
| Too big: expected string to have <=2048 characters | The Ryze AI connector stopped the call with status invalid_arguments before it reached Meta. The fields list of one Graph read is capped at 2,048 characters. | Request fewer fields per call, or split the read in two. |
Other problems
- The server shows Needs authentication
- Click Authenticate in the MCPs list to run the browser authorization again. In Devin CLI, run devin mcp logout ryze and then devin mcp login ryze, and click Allow connection.
- Nothing happens after adding the server
- Refresh the MCP list in Customize, MCPs. Check that the entry sits under mcpServers and the JSON is valid. Running devin mcp list shows what the CLI reads.
- The server works in one project only
- A .devin/mcp_config.json entry applies to that repository. Put the server in ~/.config/devin/mcp_config.json for every project.
- The server stays disconnected on a team account
- When an admin keeps an MCP allowlist, every server outside it fails to connect and its tools are missing. Ask the admin to add the Ryze AI server to the allowlist.
- The agent is off in this folder
- A workspace opened in Restricted Mode has Devin Local and every ACP agent disabled, so the Ryze AI tools cannot run there.
- The Meta connection needs reconnecting
- Meta access expires more often than Google access, for example after two-factor changes or Business Manager role changes. Click Reconnect on the Meta Ads card in Ryze AI and approve every permission again.
- An ad account is missing
- Ryze AI only sees ad accounts the connected login can reach. Check the login's access in Meta Business Manager, or connect another login with View, Add one more account.
- Meta returns a rate limit error
- Meta counts business use case limits per ad account over one hour: error 80000 marks the Insights quota and 80004 the ads management quota, while 17 and 613 come from the per-account call score. Wait and retry with narrower queries.
- Creative writes are slow
- The tool description paces creative writes at about one per 30 seconds per account. Meta's rate-limit page states the rule per object: one edit to the same object every 30 seconds, per app, and a faster one gets error 613, subcode 4841018.
- Changes are rejected
- The Ryze AI help center names Admin access as the level for changes, so reconnect with a login that holds Admin on the ad account. Meta's own role table already lets an Advertiser create and edit ads.
- No Meta Ads tools are listed
- Start a new agent session after connecting. If you linked Meta Ads in Ryze AI after adding the server, authenticate the ryze server again.
- The agent reports that a subscription is required
- The Meta Ads tools run only on an active Ryze AI plan or free trial. Start the trial in Ryze AI, then retry.
Terms on this page
- Devin Local
- The agent inside Windsurf (Devin Desktop) that calls MCP tools. It took over from Cascade.
- mcp_config.json
- Devin's MCP file. Each server is a named entry under mcpServers; this guide names the entry ryze.
- Ad account
- Meta's container for campaigns, creatives, billing and access roles. Its ID is act_ followed by a number.
- Campaign, ad set and ad
- Meta's three levels: the campaign holds the objective, the ad set holds budget, schedule, bidding and audience, and the ad holds the creative.
- Attribution window
- How long after a click or a view a conversion still counts for an ad, such as 7 days after a click.
- Insights API
- The reporting part of Meta's Marketing API. It needs the ads_read permission.
- Business Use Case rate limit
- Meta's hourly call quota, counted per ad account and per kind of work: ads management, Insights, custom audiences or catalogs.
Sources: Devin Local overview, Meta ad account reference, Meta Marketing API overview, Meta Insights API, Meta Graph API rate limiting. Checked November 14, 2026.
Frequently asked questions
How do I connect Windsurf to Meta Ads?
Connect Meta Ads in a Ryze AI workspace, then add the ryze server with the URL https://connector.get-ryze.ai/mcp under mcpServers in ~/.config/devin/mcp_config.json. Click Authenticate in Devin Desktop, or run devin mcp login ryze in Devin CLI, and click Allow connection.
What is the Meta Ads MCP?
It is Meta's own MCP server for ads, hosted at https://mcp.facebook.com/ads and in open beta since April 29, 2026. Meta's pages list ChatGPT, Claude, Perplexity and Claude Code for it, not Windsurf. In Windsurf this guide uses the Ryze AI connector instead, which brings 10 Meta Ads tools through https://connector.get-ryze.ai/mcp.
Is Windsurf the same as Devin Desktop?
Yes. Windsurf was renamed Devin Desktop on June 2, 2026, and Cognition's admin reference says the two names mean the same product. The docs moved to docs.devin.ai, windsurf.com redirects to devin.ai/desktop, and the rename did not change plans or prices.
Does Meta have an MCP server I can use in Windsurf?
Meta hosts one at https://mcp.facebook.com/ads, but none of Meta's pages read for this guide names Windsurf. Meta's overview says it works with any MCP-compatible AI agent, and its marketing page says developers can connect other applications using their own Meta app. It was not tested in Windsurf.
Which Meta Ads connector should I use with Windsurf?
Ryze AI is the best Meta Ads connector for Windsurf when one hosted URL with 10 tools for Insights, creatives and campaign edits matters most, but it needs a Ryze AI plan. Meta's own server needs no Ryze AI plan and suits Meta-only work, though Meta publishes no Windsurf steps for it.
Is there a Meta Ads Library MCP?
Yes. Meta's ads MCP server lists a tool named ads_library_search, and Ryze AI has a separate tool, native__search_ad_library, that searches Meta's public Ad Library without any Meta connection. Neither was called for this guide.
Is the Meta Ads MCP rollout finished?
No. Meta's page for its ads MCP server says the connectors are in open beta and that not all ad accounts have access yet because of a phased rollout. The Ryze AI connector does not go through that server; it calls the Marketing API directly.
Can I manage Google Ads and Meta Ads directly from Windsurf?
Yes, when both are connected in the same Ryze AI workspace. The single ryze entry in mcp_config.json then carries the 16 Google Ads tools next to the 10 Meta Ads tools, and Devin Local asks before each call unless you allowed it.
Which plan do I need for Windsurf?
Cognition's MCP documentation names no plan for MCP servers, and the Devin pricing page has no MCP row. On Teams and Enterprise, admins manage MCP registries and the MCP allowlist in team settings under MCP & ACP.
Is the config key url or serverUrl?
Current Devin docs use url, for example in ~/.config/devin/mcp_config.json. Some older pages show serverUrl for Windsurf, and Cognition mentions it only on the page for its JetBrains plugin. Whether serverUrl still works was not verified, so use url.
Can Windsurf change my Meta ad account?
Yes, through 2 write tools and 1 delete tool that create and update campaigns, ad sets, ads and creatives, upload images and delete or archive objects. Devin Desktop asks before any MCP tool call by default. A Meta login with read access only cannot change anything.
Can I use more than one Meta ad account?
Yes. One login reaches every ad account it can access, and you can add more logins with View, Add one more account in Ryze AI. Agent default accounts sets which ones the agent works with first. Keep separate clients in separate Ryze AI workspaces.
Why does Windsurf show Needs authentication?
Devin Desktop shows that state when the stored OAuth credentials have expired. Click Authenticate to sign in to Ryze AI again; in Devin CLI, run devin mcp logout ryze and then devin mcp login ryze.
Can Windsurf publish Facebook or Instagram posts?
No. The Ryze AI Meta app does not hold pages_manage_posts or instagram_content_publish, so organic Page and Instagram posting is not available. The tools cover ads.
How much does it cost?
Adding the connector costs nothing. The Meta Ads tools need an active Ryze AI plan or trial: Paid Ads is $89 per month with a 7-day free trial, and Agency is $279 per month. Annual billing takes 30% off the first year.
How do I disconnect Meta Ads from Windsurf?
Switch the ryze server off under Customize > MCPs, delete its entry from mcp_config.json or run devin mcp remove ryze. To cut Meta access as well, click View on the Meta Ads card in Ryze AI and disconnect the login.
Sources
- Devin Desktop: MCP and customizations
- Devin CLI: MCP configuration
- Devin CLI: read config from other tools
- Devin Desktop changelog
- Windsurf MCP documentation (redirects to Devin docs)
- Meta: ads MCP server page
- Meta: Ads MCP server overview
- Meta: ads MCP server update, July 16, 2026
- Meta: Marketing API rate limiting
- Meta permissions reference
- Ryze AI help center: Meta Ads
Checked November 14, 2026.