---
name: benjiads
description: Set up and run a local business on benjiads (its site, Meta ads, leads, results and the money for its ads) through the benjiads MCP server or REST API. Use when the user wants to set up their business or get customers with ads, or asks about their benjiads site, ads, money for ads, leads, results or receipts, or asks to launch, pause or retarget ads or edit and publish their site.
---

# benjiads

benjiads runs a local trade's website and Meta ads (one business, possibly several locations; an owner can have several businesses). It is free: no subscription, no credit card; the owner only pays for their ads. This skill covers what you can do for the owner through the benjiads tools, and the rules benjiads enforces server-side. Same operations as the REST API; the MCP tool name is the OpenAPI operationId.

- MCP server: https://api.benjiads.com/mcp
- REST API: https://api.benjiads.com/v1 (OpenAPI: https://api.benjiads.com/v1/openapi.json)
- Docs: https://benjiads.com/docs
- Plain-words catalog: https://benjiads.com/ai-agents.md

## Connect

For installation, authentication or an incomplete connection, fetch and execute https://benjiads.com/setup.md. It covers Codex, Claude Code, ChatGPT.com and other MCP clients through the final business summary. Do the setup steps available to you; guide the owner only through client UI, sign-in and consent that require them, then continue. A saved server entry is not a verified connection.

Client connection details:

- **Claude:** open https://claude.ai/new?q=Run%20the%20BenjiAds%20setup%20at%20https%3A%2F%2Fbenjiads.com%2Fsetup.md.%20Connect%20BenjiAds%20in%20the%20client%20I%20am%20using%20and%20complete%20authentication.%20Then%2C%20if%20I%20have%20no%20business%20yet%2C%20set%20mine%20up%3A%20ask%20me%20its%20name%2C%20trade%20and%20city%2C%20and%20create%20my%20site%20and%20ads.%20If%20I%20already%20have%20one%2C%20tell%20me%20what%20is%20live%3A%20site%2C%20ads%2C%20money%20left%20for%20ads%20and%20leads.%20Carry%20out%20the%20setup%20steps%20you%20can%3B%20guide%20me%20through%20any%20sign-in%20or%20client%20setting%20that%20needs%20me.%20Do%20not%20launch%20ads%2C%20add%20money%20or%20spend%20without%20asking%20me., or paste https://api.benjiads.com/mcp. Opens a new chat with the prompt filled in. Send it: Claude reads the skill and walks you through adding the benjiads connector (Settings, Connectors, Add custom connector). Sign in with your phone, choose your business, allow. Works in Claude Desktop and the mobile apps too.

- **ChatGPT:** open https://chatgpt.com/?q=Run%20the%20BenjiAds%20setup%20at%20https%3A%2F%2Fbenjiads.com%2Fsetup.md.%20Connect%20BenjiAds%20in%20the%20client%20I%20am%20using%20and%20complete%20authentication.%20Then%2C%20if%20I%20have%20no%20business%20yet%2C%20set%20mine%20up%3A%20ask%20me%20its%20name%2C%20trade%20and%20city%2C%20and%20create%20my%20site%20and%20ads.%20If%20I%20already%20have%20one%2C%20tell%20me%20what%20is%20live%3A%20site%2C%20ads%2C%20money%20left%20for%20ads%20and%20leads.%20Carry%20out%20the%20setup%20steps%20you%20can%3B%20guide%20me%20through%20any%20sign-in%20or%20client%20setting%20that%20needs%20me.%20Do%20not%20launch%20ads%2C%20add%20money%20or%20spend%20without%20asking%20me., or paste https://api.benjiads.com/mcp. Send the setup prompt. Enable Developer mode in Settings → Security and login, then Plugins → + (some accounts use Apps → Advanced settings). Add the MCP address with OAuth; leave client ID and secret blank. Sign in, select your business, allow access, then enable BenjiAds in the chat and continue the status checks. Requires developer-mode access on your account.

- **Claude Code:** `claude mcp add --transport http benjiads https://api.benjiads.com/mcp --scope user`. Run claude, type /mcp, pick benjiads and choose Authenticate. Your browser opens: sign in with your phone, choose your business, allow the permissions.

- **Cursor:** one-click install https://cursor.com/en/install-mcp?name=benjiads&config=eyJ1cmwiOiJodHRwczovL2FwaS5iZW5qaWFkcy5jb20vbWNwIn0%3D, or paste https://api.benjiads.com/mcp. Cursor asks to install benjiads. Accept, then sign in when it prompts: your phone, your business, the permissions.

- **VS Code:** one-click install https://vscode.dev/redirect/mcp/install?name=benjiads&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.benjiads.com%2Fmcp%22%7D, or paste https://api.benjiads.com/mcp. VS Code asks to add the server. Confirm, start it, then sign in when it prompts: your phone, your business, the permissions.

- **Codex:** `codex mcp add benjiads --url https://api.benjiads.com/mcp`. Adding the server may start sign-in immediately. Finish that flow; if still unauthenticated, run codex mcp login benjiads --scopes site:read,site:write,ads:read,ads:write,leads:read,metrics:read,billing:read,billing:write. Choose your business and allow access to all tools, then continue the setup prompt to verify the site, ads and balance.

If tools are already available, skip installation and run the first turn below. Never launch a second agent process to refresh tools. If the current client requires a reconnect or new session, use the setup skill's continuation prompt and say that verification is still pending.

Never ask the user for a benjiads password: sign-in is a code texted to their phone, in their browser. A personal API key from Integrations works as a bearer token on both the API and the MCP server.

A connection covers every business on the owner's account, including ones setup_business creates, unless the owner pinned it to one business. An account with no business yet can connect.

## Rules (benjiads enforces them; do not try to work around them)

- **Never sees your card.** Adding money for ads happens on your benjiads page in your browser; the call itself charges nothing and unlocks nothing.
- **Cannot spend past what you funded.** Ads run on money you already added for ads, launch is refused when it is gone, and adding money happens in your browser only.
- **Every campaign starts paused.** Going live is a separate yes that checks your money for ads, preparation and any required licence first.
- **You choose the permissions.** Reading, editing your site, launching and pausing ads, leads and billing are each their own permission. Change or revoke them anytime in Integrations, and connections expire on their own.
- **Leads are never masked.** Lead names, phone numbers and emails read back exactly as in your dashboard, with or without ads. Capture never stops.
- **Only your businesses.** The assistant reaches the businesses on your own account (or the one you pinned the connection to), never anyone else's, even with its IDs. With several, it asks which one.
- **A retry never runs twice.** Every action carries a key, so a flaky connection cannot launch two campaigns or publish twice.

- Start with list_businesses. With none, set one up (setup_business). With several, ask which one and pass business_id; never pick one yourself. Then get_overview before proposing a change.
- BenjiAds is free. The only money is what the owner adds for their ads, so money comes up only when they want to launch. Never mention fees or percentages.
- Agree the change and the budget with the user before launch_ads, launch_campaign, create_campaign or publish_site. Repeat the daily budget back; it is the total across locations. Launch only after an explicit yes.
- Every write takes an idempotency_key. Pick a stable, descriptive key and reuse it when retrying the same action; change it only for a genuinely new action.
- setup_business is free and creates the business, puts the site live and prepares the ads. needs_details: ask the returned missing fields, then call it again with the same name and the answers. building: wait a few seconds, then get_overview.
- launch_ads sets the ready ads at the agreed daily budget. They go live once money is added for ads and the ads agreement is signed in the dashboard; get_overview lists what is still blocking, with links. create_campaign prepares paused and returns a job: poll get_job until ready.
- fund_ads returns a browser URL where the owner adds money for ads (first top-up $100 minimum). Hand it over; never collect card details; never claim payment succeeded.
- Leads are never masked: read names and contact details back exactly as returned; do not guess numbers.
- Businesses: no_business means call setup_business first; business_required means ask which one (the error lists them) and pass business_id; business_not_found means it is not reachable on this connection: ask the user to reconnect with all their businesses, do not try IDs.
- Errors come back as { error, ...details }: insufficient_scope means the permission was not granted (send the user to Integrations); rate_limit_exceeded means wait 60 seconds; wallet_empty, campaign_not_ready and a licence hold are business gates cleared by adding money or in the dashboard, not by retrying.

## Permissions

All eight scopes are requested by default, making every tool available after consent. Honor a narrower grant if the owner explicitly chose one. Carry out tasks already authorized by the owner without asking again for tool access; follow their publishing and spending instructions.

| Scope | Grants | Type |
| --- | --- | --- |
| `site:read` | Read your businesses and their sites | read |
| `site:write` | Set up a business, edit and publish its site | write |
| `ads:read` | Read campaigns and advertising balance | read |
| `ads:write` | Create, launch and pause campaigns within your funded budget | write |
| `leads:read` | Read leads, names and contact details | read |
| `metrics:read` | Read performance and integration usage | read |
| `billing:read` | Read your ad money receipts | read |
| `billing:write` | Open the page where you add money for ads | write |

## Tools, by the owner's moment

### Day one: set up

One message. Your AI asks the name, the trade and the city, and your business is up: site live, ads ready.

- `setup_business` (`site:write`, Set up & edit sites). Ask: "I'm an electrician in Long Beach, Mike's Electric. Set up my business." Answer shape: "Done. Your site is live at mikes-electric.benjiads.com and 8 ads for electricians are being made. California wants your contractor licence number on ads: what is it?" Caveat: Free. Creates the business, puts the site live and prepares the ads, paused. If your trade and state need something (a licence number, for example) your AI asks you, then finishes. Nothing spends.
- `list_businesses` (`site:read`, Read businesses & sites). Ask: "Which businesses do I have?" Answer shape: "Two: Mike's Electric in Long Beach and Mike's Moving in Lakewood. Which one?" Caveat: Every business on your account. With more than one, your AI asks which one before doing anything.
- `get_overview` (`site:read`, Read businesses & sites). Ask: "Where are we?" Answer shape: "Your site is live. 8 ads are ready and paused. You have $0 for ads, so to go live: add money, and sign the ads agreement in your dashboard." Caveat: Site, ads, money available for ads, leads, and what is blocking your ads, each with its link. Paused or prepared is never called live.
- `preview_business` (`site:read`, Read businesses & sites). Ask: "Show me what you made." Answer shape: "Here it is: your page, your 8 ads and about how much a lead should cost, on one screen." Caveat: A private link, valid 7 days, no login. Nothing is public that wasn't already.
- `get_account` (`site:read`, Read businesses & sites). Ask: "What name do you have for me?" Answer shape: "Eddy Almeida, on the number you log in with." Caveat: Your own first and last name (how BenjiAds greets you) and your login phone, which only you can change.
- `update_account` (`site:write`, Set up & edit sites). Ask: "My last name is spelled Almeyda." Answer shape: "Fixed: Eddy Almeyda." Caveat: Your own name only. The business name is changed on the site (update_site).

### Monday check-in

Coffee, phone, thirty seconds. Ask what happened while you were on jobs.

- `get_metrics` (`metrics:read`, Read results & usage). Ask: "How did last week go?" Answer shape: "214 people visited your site and 11 left their number. 8 of those came from your ads." Caveat: Visits, form starts and leads for the last 1, 7 or 30 days, same numbers as your dashboard. Cost per lead comes from combining this with your ad spend.
- `list_campaigns` (`ads:read`, Read ads & balance). Ask: "What is running, and how much ad money do I have left?" Answer shape: "One campaign is active, Electrical repair in Long Beach. You spent $61 this week and have $189 left in your ad balance." Caveat: Balance is what you funded in your dashboard. The assistant cannot add money to it. If Meta is unreachable, spend may come from the last stored figure.
- `list_leads` (`leads:read`, Read leads). Ask: "Who reached out this weekend?" Answer shape: "3 new leads since Friday: a panel upgrade in Lakewood, an outlet repair in Signal Hill and an EV charger quote. Want me to read them out?" Caveat: Names, phone numbers and emails read back exactly as in your dashboard. Leads are never masked.
- `get_job` (`ads:read`, Read ads & balance). Ask: "Is my new campaign ready yet?" Answer shape: "Yes. 8 ads are prepared and paused. Say launch when you want them live." Caveat: Ready means prepared, not live. A licence hold shows here too and is cleared in your dashboard.

### Slammed week, slow week

Turn the tap down or up without opening a laptop.

- `launch_ads` (`ads:write`, Prepare, launch & pause ads). Ask: "Launch my ads at $30 a day." Answer shape: "$30 a day across Long Beach and Lakewood, confirmed. Your 8 ads are set: they go live as soon as you add money for ads. Here is the link." Caveat: Your AI repeats the daily budget and waits for your yes. The ads go live once you have money for ads and signed the ads agreement in your dashboard; the licence check runs again.
- `pause_ads` (`ads:write`, Prepare, launch & pause ads). Ask: "I'm slammed until Monday. Stop my ads." Answer shape: "All your ads are paused. Nothing spends until you say go." Caveat: Pauses every running campaign of the business, immediately.
- `set_cities` (`site:write`, Set up & edit sites). Ask: "Target Signal Hill and Seal Beach too." Answer shape: "Your service area is now Long Beach, Lakewood, Signal Hill and Seal Beach. Your site shows it now; your next launch targets all four." Caveat: Replaces the cities on your site now and for your next ad launch. A campaign already running keeps its areas until you launch again.
- `pause_campaign` (`ads:write`, Prepare, launch & pause ads). Ask: "I am slammed until Monday. Pause my ads." Answer shape: "Paused Electrical repair in Long Beach. Nothing spends until you say go." Caveat: Pausing is immediate and uses the same access rules as the dashboard. Relaunching is a separate ask.
- `launch_campaign` (`ads:write`, Prepare, launch & pause ads). Ask: "It is Monday. Turn them back on." Answer shape: "Electrical repair in Long Beach is live again at the budget you saved. I checked your ad balance first, all fine." Caveat: Needs available ad balance, finished preparation and any required licence. Billing pauses cannot be overridden. Your assistant is told to confirm the budget with you before launching; benjiads itself enforces those checks.
- `create_campaign` (`ads:write`, Prepare, launch & pause ads). Ask: "Set up a water heater campaign with my usual daily budget across both locations. Do not turn it on yet." Answer shape: "Preparing it now, paused. I will tell you when it is ready to review. It will not go live until you say so." Caveat: Always prepared paused. Runs the wallet, creative ownership and licence checks. The daily budget is the total across your locations, not per location.

### New service area, new service

Your site changes as fast as your business does.

- `get_site` (`site:read`, Read businesses & sites). Ask: "What does my site say about service areas right now?" Answer shape: "Long Beach, Lakewood and Seal Beach. Your headline is 'Same-day electrical repair'. There is an unpublished draft from Tuesday." Caveat: Reads the live site and the draft. Free, like the rest of the product.
- `update_site` (`site:write`, Set up & edit sites). Ask: "Add Signal Hill to my service area and update the phone number on the site." Answer shape: "Done. Signal Hill is listed and your public number is updated." Caveat: Business details (the business name too), appearance, service areas and publication status. Lead capture keeps working whatever your ad balance.
- `edit_site` (`site:write`, Set up & edit sites). Ask: "Make the headline shorter and add a line saying we do emergency calls." Answer shape: "Done on your draft: the headline is now 'Same-day electrician in Long Beach' and there is a line about emergency calls. Publish it?" Caveat: The site builder's own AI editor makes the change on the draft. It never invents prices, reviews or licences, and asks you when it needs a fact.
- `set_header_picture` (`site:write`, Set up & edit sites). Ask: "Put this photo of my van at the top of my page." Answer shape: "Your van is the header picture now. Tell me to publish and it goes live." Caveat: An https image, your trade's own photo, or none. Saved on the draft until you say publish.
- `save_site_draft` (`site:write`, Set up & edit sites). Ask: "Add a section about EV charger installs, but do not publish yet." Answer shape: "Saved as a draft. Check it in your dashboard, or tell me to publish." Caveat: Same checks as the site builder. The assistant reads your current site first. Nothing changes on the live site.
- `publish_site` (`site:write`, Set up & edit sites). Ask: "Looks good. Publish it." Answer shape: "Published. Your site now shows the EV charger section." Caveat: Publishes the saved draft only. Review it first. Free. Buying a domain stays in the dashboard.

### Before you spend

Know what your state and your trade require before an ad goes anywhere.

- `get_workspace` (`site:read`, Read businesses & sites). Ask: "Tell me about this business." Answer shape: "Mike's Electric, mikes-electric.benjiads.com. I can read your site, ads and results, and pause or launch ads." Caveat: The business you named, or your only one. The assistant only reaches businesses on your own account.
- `get_workspace_requirements` (`site:read`, Read businesses & sites). Ask: "Is anything blocking my ads in California?" Answer shape: "One thing: your contractor licence number is missing for CA. Add it in your dashboard and the ads can go live." Caveat: Only a missing licence number blocks launch. Other fields guide your ad copy. Verification happens in the dashboard, never in chat. Funding is checked separately at launch.
- `list_verticals` (`site:read`, Read businesses & sites). Ask: "Do you handle HVAC too? My brother-in-law asked." Answer shape: "Yes, HVAC is supported, with its own state rules and ad-copy restrictions. Want me to set it up as a second business?" Caveat: A listed trade can still be on hold in some states. Reading the catalog does not open a new ad channel.
- `get_vertical` (`site:read`, Read businesses & sites). Ask: "What am I not allowed to say in an electrician ad?" Answer shape: "Here are the copy rules, required disclosures and the states that need a licence number, in plain words." Caveat: Describes the trade's rules. It does not check your own licence; ask about blockers for that.

### Money for ads, and taxes

BenjiAds is free. The only money is what you put in for your ads.

- `fund_ads` (`billing:write`, Open add-money page). Ask: "Add money for my ads." Answer shape: "Here is your link. Open it, sign in and add money; the first top-up is $100 minimum. I cannot take card details or confirm payment from here." Caveat: Hands you to your benjiads page in your browser. The call itself never charges a card or launches anything.
- `list_invoices` (`billing:read`, Read receipts). Ask: "Send me all my benjiads invoices for taxes." Answer shape: "Here are your benjiads receipts for the year, with dates and amounts." Caveat: Receipts for the money you added for ads.
- `get_usage` (`metrics:read`, Read results & usage). Ask: "How much have you been doing on my account?" Answer shape: "In the last 30 days: 41 actions, mostly reading results and leads, plus 2 pauses. None of it adds to your bill." Caveat: Counters only, over the last 30 days. Using the assistant costs nothing extra.

## Not available to agents

Not on the list: paying (adding money for ads happens on your page, in your browser), signing the ads agreement, verifying a licence, buying a domain, generating new creatives, deleting campaigns, touching your Facebook page. Those stay in your dashboard.
Point the user to their dashboard (https://benjiads.com/app) for those. Connections are managed in https://benjiads.com/app/integrations.

## A good first turn

1. list_businesses.
2. No business: use what the user already said (trade, city); ask at most one short question at a time for what is missing. setup_business asks the owner's own name when the account has none, then the business name with a suggestion ("Eddy HVAC"): propose it, and use a name only once the owner says it or says yes; never invent one silently. Never ask for services, prices, photos or budget. Match the trade with list_verticals. Call setup_business. Share the site link and say the ads are being made. Talk about budget only when the user wants customers now: ask a daily budget, repeat it, launch_ads after the yes, then fund_ads for the link to add money.
3. A business exists (ask which one if several): get_overview. Report the site and whether it is live, the ads and campaign statuses (prepared or paused is not live), the money available for ads in USD, the leads, and each blocker with its link. Failed reads are unavailable, never zero.
4. Then ask what the owner wants: results (get_metrics), leads (list_leads), launch or pause (launch_ads, pause_ads), new cities or radius (set_cities), a site change in words (edit_site, then publish_site once the owner agrees), a header picture (set_header_picture), or a preview to show them (preview_business).