# Connect VS Code to Apogee's MCP server: setup, checks, limits and errors https://www.apogee.ad/developers/mcp/vscode/ (Markdown: https://www.apogee.ad/developers/mcp/vscode.md). Updated 2026-11-03. VS Code (GitHub Copilot agent mode) connects to Apogee's MCP server at `https://app.apogee.ad/mcp` with Apogee's sign-in (OAuth) or an API key. It then works on your Meta, TikTok and Snapchat ad accounts through Apogee's 80 tools: it reads freely, and launches or changes ads only after your explicit yes to a recap. ## At a glance - Server URL: `https://app.apogee.ad/mcp` - Transport: Streamable HTTP, stateless: every request is a `POST` answered with JSON. - Sign-in: Apogee's sign-in (OAuth 2.1 with PKCE): the assistant opens Apogee's page, you log in and click **Authorize**; or an API key (`Authorization: Bearer apk_…`), shown below. - Scopes: **Read** (`read`), **Launch** (`launch`), **Actions** (`actions`): ticked on Apogee's page when VS Code signs in, or chosen when you create the key ([scopes](https://www.apogee.ad/developers/authentication/#scopes)). - Apogee plan: [Pro, Growth or Scale](https://www.apogee.ad/en/pricing/) (not Starter) - Server instructions: On connection, Apogee tells VS Code how to launch: the interview, the recap, your yes ([read them](https://www.apogee.ad/developers/mcp/#instructions)). ## Set it up 1. Run **MCP: Add Server** from the Command Palette, choose **HTTP**, paste `https://app.apogee.ad/mcp` and name it `apogee`. 2. Trust the server when VS Code asks. On the first connection a browser window opens: log in to Apogee and click **Authorize**. 3. Open Copilot Chat in **Agent** mode and ask. Configure it by hand (.vscode/mcp.json (by hand)): ```json { "servers": { "apogee": { "type": "http", "url": "https://app.apogee.ad/mcp" } } } ``` With an API key instead: .vscode/mcp.json, with an API key (VS Code asks for it once and stores it): ```json { "inputs": [ { "type": "promptString", "id": "apogee-key", "description": "Apogee API key", "password": true } ], "servers": { "apogee": { "type": "http", "url": "https://app.apogee.ad/mcp", "headers": { "Authorization": "Bearer ${input:apogee-key}" } } } } ``` Checked on 2026-10-10 against: [VS Code docs: MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers), [VS Code docs: MCP configuration](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration), [GitHub docs: MCP in Copilot](https://docs.github.com/en/copilot/concepts/context/mcp). ## Plans - **On VS Code's side:** Copilot Free, Pro, Pro+ and Max: nothing to turn on. Copilot Business and Enterprise: an admin turns on the **MCP servers in Copilot** policy (off by default). - **On Apogee's side:** the Pro, Growth or Scale plan includes the MCP server, with credits every month (10,000 on Pro, 30,000 on Growth, 100,000 on Scale); Starter does not. A 7-day trial for €1 includes a quarter of the plan's credits ([plans](https://www.apogee.ad/en/pricing/), [credits](https://www.apogee.ad/developers/credits/)). - **Your ad accounts** connected in the Apogee app (Meta, TikTok or Snapchat): VS Code sees exactly what your Apogee account sees. ## Check the connection Ask VS Code, in your own words: 1. "Which Apogee account are you connected to, and with which scopes?" VS Code calls [`whoami`](https://www.apogee.ad/developers/mcp/whoami/): the Apogee account this connection acts as, the credential used (an assistant's connection or an API key) and its scopes. 2. "List my Meta ad accounts on Apogee, then my TikTok and Snapchat ones." VS Code calls [`list_ad_accounts`](https://www.apogee.ad/developers/mcp/list-ad-accounts/), with `platform` set to `tiktok` or `snapchat` for the others. An empty list means no ad account of that platform is connected in the Apogee app. Both are reads: free within the daily free reads, nothing changes. If VS Code does not find Apogee's tools, check that Apogee is turned on where the last step above says. From a terminal: Without a credential the server answers `401` with a `WWW-Authenticate` header pointing to `https://app.apogee.ad/.well-known/oauth-protected-resource/mcp`: that is where OAuth discovery starts. ```bash curl -i -X POST https://app.apogee.ad/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` With your API key in `$APOGEE_API_KEY`, the same `whoami` call VS Code makes: ```bash curl -X POST https://app.apogee.ad/mcp \ -H "Authorization: Bearer $APOGEE_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}' ``` ## What it can do VS Code gets Apogee's 80 tools, filtered by the scopes of its connection: a tool outside them is not even listed. - **Read** (`read`, 54 tools): Read ad accounts, campaigns, ad sets, ads and their numbers on Meta, TikTok and Snapchat, the comments of your ads and the Bridge's stats; follow imports, launches and transfers (nothing is sent). For example: [`whoami`](https://www.apogee.ad/developers/mcp/whoami/), [`list_ad_accounts`](https://www.apogee.ad/developers/mcp/list-ad-accounts/), [`get_account_overview`](https://www.apogee.ad/developers/mcp/get-account-overview/), [`get_top_performers`](https://www.apogee.ad/developers/mcp/get-top-performers/), [`get_platform_overview`](https://www.apogee.ad/developers/mcp/get-platform-overview/), [`get_launch_questions`](https://www.apogee.ad/developers/mcp/get-launch-questions/). - **Launch** (`launch`, 9 tools): Import and upload creatives, prepare and launch ads, run Bridge transfers, create a campaign. For example: [`import_link`](https://www.apogee.ad/developers/mcp/import-link/), [`prepare_launch`](https://www.apogee.ad/developers/mcp/prepare-launch/), [`launch`](https://www.apogee.ad/developers/mcp/launch/), [`prepare_bridge_transfer`](https://www.apogee.ad/developers/mcp/prepare-bridge-transfer/), [`execute_action`](https://www.apogee.ad/developers/mcp/execute-action/). - **Actions** (`actions`, 18 tools): Pause, activate, change budgets and targeting, duplicate, create ad sets and ads from existing posts. For example: [`pause_ad`](https://www.apogee.ad/developers/mcp/pause-ad/), [`update_budget`](https://www.apogee.ad/developers/mcp/update-budget/), [`execute_action`](https://www.apogee.ad/developers/mcp/execute-action/). By effect: 54 only read; 19 prepare a plan or an action; 4 write in Apogee only and 3 change the ad account, after your yes. Every tool, its parameters and its cost: [all the tools](https://www.apogee.ad/developers/mcp/#tools). ## Prompts to start with Replace the [brackets] with your own names. Each prompt ends with Apogee's safety reminder: "Create everything paused, and show me the full recap before you create anything." or "Show me each change and wait for my yes before you make it." ### Launch a folder from your computer Every creative of a folder on your computer, in a new ad set of your testing campaign, with the settings of the last ad set and the last ad launched there. ```text Take every creative in [folder] on my computer and launch them in a NEW ad set in my [testing campaign] campaign of [ad account]. Reuse the settings of the latest ad set and the latest ad launched in that campaign. Create everything paused, and show me the full recap before you create anything. ``` What it asks you: Which ad account, when you have several. The ads it reads from your file names with your naming convention: one ad per creative, its 9:16, 4:5 and 1:1 files together. Confirm or correct them. The new ad set's name. What it copies from the latest ad set (audience, conversion event, bid, budget) and the latest ad (page, Instagram, URL, call to action, texts), and whether anything should change. Which Advantage+ enhancements to turn on: every one you don't pick stays off. Whether to show products from your catalog, when the account has one. The whole recap, then your explicit yes. Note: Needs an assistant that can run commands on your computer to upload the files. In Claude or ChatGPT on the web, put the folder on Google Drive, Dropbox or Frame.io and use the link template. ### Launch files whose names mean nothing Files named IMG_4512.mp4 or final_v3_OK(1).mov, launched without a naming convention: you check the ads, rename them and put them in groups, one ad set per group. ```text Launch the videos in [folder or link] in my [campaign] campaign of [ad account]. The file names mean nothing: group the formats of each creative, show me the ads, let me rename them and put them in groups, one ad set per group. Reuse the settings of the latest ad set and ad of that campaign. Create everything paused, and show me the full recap before you create anything. ``` What it asks you: Which ad account, when you have several. The ads it built: files whose names differ only by their format words (feed and story, 4x5 and 9x16…) are the 4:5, 9:16 and 1:1 of one creative, linked into one ad; every other file is its own ad, named after the file. Link the files of one creative, or split them. A name for each ad, if you want other names than the files'. Which ads go together in a group: each group becomes one ad set (One Concept One Adset). What it copies from the latest ad set and ad of the campaign, and whether anything should change. The whole recap, then your explicit yes. Note: A folder on your computer needs an assistant that can run commands on it (Claude Code, Cursor…). In Claude or ChatGPT on the web, use a Frame.io, Google Drive or Dropbox link. ### Weekly report on every platform Last week on Meta, TikTok and Snapchat, each platform on its own (its own currency, never added up): spend and results against the week before, the best and the worst ads, what the Bridge's copies did, and what to do next. ```text Give me my weekly report for [brand]: the last 7 days against the 7 days before, on Meta ([Meta ad account]), TikTok ([TikTok ad account]) and Snapchat ([Snapchat ad account]), each platform on its own. Spend, ROAS and CPA, the 3 best and the 3 worst ads, and what to scale or cut. Show me each change and wait for my yes before you make it. ``` What it asks you: Your targets (ROAS or CPA) when Apogee does not know them yet: it can remember them in your business profile. Each proposed change (pause, budget up or down) with what it will change, and your OK for each one. ## Guardrails and limits The server enforces them, whatever VS Code is told: - **Your yes before anything changes.** A launch is [`prepare_launch`](https://www.apogee.ad/developers/mcp/prepare-launch/), the recap, then [`launch`](https://www.apogee.ad/developers/mcp/launch/); a change is an action tool, then [`execute_action`](https://www.apogee.ad/developers/mcp/execute-action/); a Bridge transfer is [`prepare_bridge_transfer`](https://www.apogee.ad/developers/mcp/prepare-bridge-transfer/), then [`bridge_transfer`](https://www.apogee.ad/developers/mcp/bridge-transfer/). Nothing is created, changed or transferred before your explicit yes to the whole recap. - **Ads are created paused** unless you ask otherwise. - **A prepared plan or action is valid 24 hours** and runs once. - **Daily budget cap:** a daily budget above 500 in the ad account's currency is refused ([`budget_above_cap`](https://www.apogee.ad/developers/errors/#budget_above_cap)). - **25 launches and Bridge transfers** per ad account in 24 hours through the MCP and the API. - **2,000 units** per assistant connection or API key in 24 hours: a read 1, a change 2, Apogee's AI 5, a launch or a transfer 10. - **MCP requests:** 600 on Pro, 1,200 on Growth and Scale per 15 minutes ([rate limits](https://www.apogee.ad/developers/rate-limits/)). - **Credits:** reads are free up to 5,000 on Pro, 10,000 on Growth and Scale a day; a change on an ad platform, an ad created and Apogee's AI cost credits, only when they succeed ([credits](https://www.apogee.ad/developers/credits/)). - **Each platform on its own:** Meta, TikTok and Snapchat keep their own currency and attribution; Apogee never adds them up. ## Errors and fixes A refused tool call comes back to VS Code as a result with `isError: true` and the reason in words, so it can tell you what to do. The common ones: - [`401`](https://www.apogee.ad/developers/errors/#invalid_api_key): Apogee needs authentication, or every call fails The sign-in was disconnected in Apogee, or its refresh token (valid 60 days) expired: connect again from the authorization step. An access token lasts 1 hour and VS Code renews it on its own. With a key: the key is wrong, revoked or past its end date. Create a new one in [Settings → API](https://app.apogee.ad/home?settings=api) and replace it in `.vscode/mcp.json`. - VS Code sees Apogee but says it cannot launch or change anything The connection lacks a [scope](https://www.apogee.ad/developers/authentication/#scopes), so those tools are not listed. Connect again and keep **Launch** and **Actions** ticked on Apogee's page, or create a key with those scopes. - [`403 upgrade_required`](https://www.apogee.ad/developers/errors/#upgrade_required) The Apogee account is not on a plan with the MCP. It works again as soon as the account is on Pro, Growth or Scale. - The option to add Apogee is missing or greyed out Your organization controls it: an administrator allows it first (see [Plans](https://www.apogee.ad/developers/mcp/vscode/#plans) and the notes under the steps). - [`402 credits_exhausted`](https://www.apogee.ad/developers/errors/#credits_exhausted) This month's credits and the credit packs are used: buy a pack ([credits](https://app.apogee.ad/settings/credits)) or wait for the 1st of the month (UTC). Reads go on. - [`429`](https://www.apogee.ad/developers/errors/#rate_limited) `rate_limited`, `quota_exceeded`, `daily_read_cap` A limit of the list above is reached: wait the seconds the answer gives ([rate limits](https://www.apogee.ad/developers/rate-limits/)). - [`412 meta_not_connected`](https://www.apogee.ad/developers/errors/#meta_not_connected), `platform_not_connected` Apogee's own Facebook, TikTok or Snapchat connection expired, not VS Code's: log in to the Apogee app again, or reconnect the platform there. - [`410 plan_expired`](https://www.apogee.ad/developers/errors/#plan_expired), `409 plan_already_launched` The recap was prepared more than 24 hours earlier, or already ran: ask VS Code to prepare it again. - [`409 same_error_again`](https://www.apogee.ad/developers/errors/#same_error_again) The last launches on this ad account failed with the same error: fix its cause (the platform's message says what), then tell VS Code it is fixed. Every code: [errors](https://www.apogee.ad/developers/errors/). ## Disconnect - **In Apogee:** Settings → MCP → **Connected assistants**, then **Disconnect** next to VS Code. It loses access at once; ads already launched are not touched, and you can connect it again at any time. - **An API key:** [Settings → API](https://app.apogee.ad/home?settings=api) → **API keys**, then **Revoke**. Whatever uses the key stops at once. - **In VS Code:** delete the `apogee` entry from `.vscode/mcp.json`. ## Guides and related pages - [VS Code MCP server: connect Apogee to GitHub Copilot for ads](https://www.apogee.ad/en/blog/vscode-mcp-server/) (English) · [VS Code MCP : brancher Apogee dans GitHub Copilot pour vos ads](https://www.apogee.ad/blog/vscode-mcp-server/) (Français) · [VS Code MCP: conectar Apogee a GitHub Copilot para sus anuncios](https://www.apogee.ad/es/blog/vscode-mcp-server/) (Español) - [Meta Ads MCP: run your ads from Claude, ChatGPT or Cursor](https://www.apogee.ad/en/blog/meta-ads-mcp/): the options for a Meta Ads MCP, compared - [The MCP server](https://www.apogee.ad/developers/mcp/): how a launch works, every tool, prompt templates - [Authentication](https://www.apogee.ad/developers/authentication/): API keys, OAuth, scopes - [Every assistant, for AI agents](https://www.apogee.ad/developers/llms.txt)