Connect an AI agent
Let an agent set up and run a business through the same operations as the REST API.
Remote MCP server
https://api.benjiads.com/mcpUse a client that supports remote MCP over Streamable HTTP. The endpoint supports legacy stateless clients and the 2026-07-28 request protocol. Configure the URL in the client's integrations or MCP settings, then sign in when prompted.
Complete setup in your agent
Copy this into Codex, Claude Code or ChatGPT:
Run https://benjiads.com/setup.md. Connect BenjiAds in this client and complete sign-in. If I have no business yet, set mine up: ask me its name, trade and city. Otherwise tell me what is live: site, ads, money left for ads and leads. Guide me through any client setting or sign-in step that needs me.
The setup skill handles installation, authentication, reconnecting, and then the business setup or summary. Adding the server alone is not a completed setup. On ChatGPT.com, the owner adds the connector and approves OAuth in the browser, then enables BenjiAds in the conversation. A prefilled chat link does not install it.
Install in your client
Each path ends the same way: your browser opens, you sign in with the code texted to your phone (a new number creates the account) and allow the requested permissions. The connection covers all your businesses, including new ones, unless you pin it to one.
# Claude Code, then `/mcp` → benjiads → Authenticate
claude mcp add --transport http benjiads https://api.benjiads.com/mcp --scope user
# Codex CLI
codex mcp add benjiads --url https://api.benjiads.com/mcp
# Only if adding the server did not already complete sign-in:
codex mcp login benjiads --scopes site:read,site:write,ads:read,ads:write,leads:read,metrics:read,billing:read,billing:write- Claude (web, desktop, mobile): Settings → Connectors → Add custom connector, paste
https://api.benjiads.com/mcp, Connect. - ChatGPT: enable Developer mode in Settings → Security and login, then Plugins → +, and add the same address with OAuth. Some accounts use Apps → Advanced settings → Developer mode → Create app/connector. Leave client ID and secret blank for dynamic registration. Sign in, approve access and enable BenjiAds in the chat. Availability depends on account/workspace policy. See the official connection guide.
- Cursor: Add to Cursor, or add
{ "url": "https://api.benjiads.com/mcp" }underbenjiadsinmcp.json. - VS Code: Add to VS Code, or add
{ "type": "http", "url": "https://api.benjiads.com/mcp" }underbenjiadsinmcp.json.
Optionally retain the setup skill for future sessions in the current client:
# Codex
mkdir -p ~/.agents/skills/benjiads-setup && curl -fsSL https://benjiads.com/setup.md -o ~/.agents/skills/benjiads-setup/SKILL.md
# Claude Code
mkdir -p ~/.claude/skills/benjiads-setup && curl -fsSL https://benjiads.com/setup.md -o ~/.claude/skills/benjiads-setup/SKILL.mdClients with custom authorization headers can use a personal API key:
{
"url": "https://api.benjiads.com/mcp",
"headers": {
"Authorization": "Bearer <your-api-key>"
}
}This is the connection information; the enclosing configuration format depends on your client. OAuth clients should discover the authorization server from the WWW-Authenticate challenge.
Discover, then act
Connections request all eight scopes by default, so every tool is available after consent. Explicitly restricted connections remain supported; existing grants keep their approved scopes until reconnected. Business and advertising limits apply to every connection.
The server also offers a prompt named start ("Set up my business"); clients that support MCP prompts show it as a command.
The simple set
Most owners only need these. The API reference gives each REST operation's matching MCP tool name.
| Tool | What it does |
|---|---|
setup_business | Creates a business from what the owner already said — the trade (or their own words in what), the cities, the website if any. The owner's name and the business name are asked when missing (the business name with a suggestion to propose, never invented). The site goes live and the ads are prepared, paused. Free. Returns ready (with a preview link: the page, the ads and the estimate), needs_answer (exactly one question to ask), needs_details (the missing fields a state requires, such as a license number) or building. |
preview_business | A private link (7 days) that shows the owner their page, their ads and the lead estimate on one screen, plus the ad images. |
list_businesses | The businesses on this connection. |
get_overview | Site and status, ads and campaigns, money available for ads, leads, and what is blocking the ads (each blocker with its link). |
launch_ads | Sets the ready ads at a daily budget. They go live once money is added for ads and the ads agreement is signed in the dashboard. |
pause_ads | Pauses every running campaign of the business. |
set_cities | Replaces the service cities, and optionally the radius around them (radius_mi, 5–50 miles): on the site now, and for the next ad launch. |
edit_site | Changes the page the way the owner says it ("shorter headline", "add a line about emergency calls"), with the site builder's own AI editor, on the draft. Returns changed, unchanged or needs_answer (questions to ask the owner). publish: true puts the change live. |
set_header_picture | The big picture at the top of the page: an https image, "trade" for the trade's photo, or "none". On the draft; publish: true puts it live. |
fund_ads | A browser link where the owner adds money for ads (first top-up $100 minimum). |
list_leads | Leads with full contact details. |
Every business tool takes an optional business_id. With one business it can be omitted; with several, business_required lists them and the agent asks the owner which one. no_business means: call setup_business first.
A first turn
- Call
list_businesses. - No business: call
setup_businessright away with what the owner already said. If it answersneeds_answer, ask exactly its one question and call again with the answer. It asks the owner's own name when the account has none (first_name,last_name), then the business name with asuggestionmade of the first name and the trade ("Eddy HVAC"): propose it, and passnameonly as the owner confirms or says it. Share the site link and the preview; offer to launch only when the owner wants customers now. - A business exists: call
get_overviewand report the site, ads, money for ads, leads and blockers. Prepared or paused ads are not live. Failed reads are unavailable, never zero.
Account tools: get_account reads the owner's own name and login phone, update_account changes the name (the business name is update_site's displayName).
Advanced tools (get_workspace, get_site, update_site, save_site_draft, publish_site, list_campaigns, create_campaign, get_job, launch_campaign, pause_campaign, get_metrics, get_workspace_requirements, list_verticals, get_vertical, list_invoices, get_usage) stay available for finer control. In list_campaigns, the money available for ads is remainingCents / 100 in USD; balanceCents is cumulative funding.
If a client needs to reload its tools, continue with:
Continue the BenjiAds setup: call list_businesses. With no business, call setup_business with what I told you and ask me only the one question it returns. Otherwise call get_overview and report the site, the ads, the money available for ads and the leads. Do not launch ads, add money or spend without asking me.
A persistent HTTP 500 at /oauth/register is a server failure before sign-in. Changing scopes or repeatedly reinstalling the server does not fix registration.
Writes and user authorization
Before launching ads, publishing a site or spending on advertising, agree on the intended change and budget with the user. Repeat the daily budget back and wait for an explicit yes. Each write requires an idempotency_key. Reuse that key when retrying the same action.
Example arguments for publish_site:
{
"idempotency_key": "publish-reviewed-homepage-001"
}launch_ads is the simple path. With create_campaign, preparation runs with launch disabled: poll get_job and inspect the saved campaign before calling launch_campaign. A site, license or funding restriction cannot be bypassed by the agent.
Money for ads and owner handoffs
BenjiAds is free. No subscription, no credit card. You only pay for your ads. fund_ads returns a browser URL where the owner signs in, saves a card and adds money for ads. The MCP call itself does not charge a card or activate anything. Bring it up when the owner wants to launch.
License verification, the ads agreement, adding money for ads, and account permissions stay in the owner's dashboard. Agents must not collect card data or fabricate a license verification result.
Tool results and privacy
Every tool declares an outputSchema generated from the same response contract as the REST API. Lead results include useful contact and qualification fields, excluding IP addresses, browser data, attribution payloads and internal chat identifiers. Contacts are returned in full: BenjiAds is free and never masks leads.
Job failures return a safe summary; detailed diagnostics remain in BenjiAds. Clients receive operation receipts in _meta["benjiads/requestId"] and replay markers in _meta["benjiads/replayed"], outside the business data returned to the model.
All admitted calls record private audit activity, so the tools declare readOnlyHint: false even when they only retrieve business information. Scope checks still distinguish reads from edits, publication and advertising actions. Mutations require stable retry keys; ordinary reads record a new operation each time.
Muse and other directories
The MCP endpoint is a general integration. Availability in Muse depends on the platform's connector contract and review. BenjiAds does not currently claim an approved Muse listing or a payment flow completed entirely inside a Muse/Link conversation.