// DEVELOPERS · API & MCP

The AI sales rep your AI assistant can delegate to.

BOSRAI ships an MCP server (Model Context Protocol — the open standard AI assistants use to operate tools). Connect it to Claude or any MCP-capable agent and your assistant can read your pipeline, search contacts, pause campaigns, and have BOSRAI write native-language outreach — by just asking.

1 · Get your API key (scripts & headless clients only)

Connecting from Claude? Skip this step — the connector signs in with OAuth in your browser (step 2). Keys are for curl, cron jobs, and clients that can't open a browser.

  1. Sign in at bosr.ai/app → Settings → API & MCP
  2. Click + Generate new key — the full key (bsr_live_…) is shown once; store it like a password
  3. Each key acts as its workspace. Revoke any time from the same page.

2 · Connect

The server speaks MCP over Streamable HTTP (JSON responses), protocol 2025-06-18, with two ways in:

# Endpoint
POST https://bosr.ai/api/mcp
# Auth — one of:
#   OAuth 2.1 (one-click browser sign-in; MCP clients discover it automatically)
#   Authorization: Bearer bsr_live_your_key_here

Claude (claude.ai · web & desktop connectors)

  1. Claude → Settings → Connectors → Add custom connector
  2. URL: https://bosr.ai/api/mcp — leave every other field empty, no API key needed
  3. Click Connect — a BOSRAI page opens; sign in (if you aren't already) and Approve
  4. Ask Claude: “How did my outreach do this week?”

The connection is scoped to your workspace. Disconnect any time by removing the connector in Claude, or revoke it from BOSRAI under Settings → API & MCP → Connected apps.

Any stdio client (via mcp-remote)

{
  "mcpServers": {
    "bosrai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://bosr.ai/api/mcp"]
    }
  }
}

That opens the same browser sign-in on first run. Headless (no browser)? Pass your API key instead: "args": […, "--header", "Authorization: Bearer bsr_live_…"]

Raw JSON-RPC (any language)

curl -s https://bosr.ai/api/mcp \
  -H "Authorization: Bearer $BOSRAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_roi_report","arguments":{"days":7}}}'

3 · Tools

ToolWhat it does
get_workspace_overviewREADSnapshot: plan, credits, counts of contacts, campaigns, cadences, audiences, mailboxes. Start here.
get_roi_reportREADProof-of-work for the last N days (default 7, max 90): sent, replies, positive replies, meetings booked, pipeline value, cost — with previous-period comparison.
list_audiencesREADThe workspace's audiences (ICP profiles): who it sells to, firmographics, and each audience's outreach language.
search_contactsREADSearch contacts by name or email substring — up to 25 matches with role, score, source, tags.
list_campaignsREADOutreach campaigns with status (draft / active / paused / completed) and stats.
set_campaign_statusWRITEPause or start a campaign. Takes effect immediately in the live workspace.
build_cadenceWRITEHave BOSRAI write a complete multi-step outreach cadence (3–6 emails) from your brand + audience context — native-fluent in the audience's language. Creates a real cadence.
list_signal_monitorsREADThe always-on buying-signal monitors (new store openings, hiring surges, ad launches, import records…) with per-monitor yield.
get_upcoming_bookingsREADMeetings prospects have booked via your BOSRAI booking page.
get_recent_repliesREADMost recent inbound prospect messages across email, LinkedIn and WhatsApp — what prospects are actually saying.
list_skillsREADCatalog of 100+ executable skills — marketing, sales and ops playbooks (blog writer, SEO pipeline, social posts, ad copy, competitor monitors, email sequences, …) with each skill's required inputs.
run_skillWRITEExecute any cataloged skill by slug. Costs that skill's credits, respects your plan tier and rate limits. Asynchronous — returns a task_id.
list_skill_runsREADRecent skill runs, newest first: task id, skill, status, timestamps, whether a result is waiting. Use it to recover a task_id you lost.
get_skill_resultREADStatus and output of a run_skill task: running · completed · failed.
submit_blog_draftWRITESubmit an article as a draft to your bosr.ai blog. Drafts are never public: you review at the returned preview URL and publish by hand.

Every tool ships MCP annotations, so a client can show what a call will do before it runs: a human-readable title, readOnlyHint (true on the eleven read tools), destructiveHint (false everywhere — nothing here deletes or overwrites), idempotentHint, and openWorldHint (true only on run_skill, whose skills crawl the web and call third parties). Call tools/list to read them.

Write actions are real. set_campaign_status, build_cadence and run_skill change the live workspace (and spend credits) the moment they run — same as clicking the button in the app. Point your agent at a test workspace first if you're experimenting.

4 · Limits & notes

5 · Testing this connector in ten minutes

Written for a reviewer who has never seen BOSRAI. You need no BOSRAI knowledge and no data of your own: sign in with the test account supplied with our directory submission, which is a real workspace loaded with sample contacts, a campaign and a sequence.

  1. Connect (1 min). Add https://bosr.ai/api/mcp as a custom connector. The browser sign-in appears automatically; use the test account. No key to paste, nothing else to fill in.
  2. Prove the read path (2 min). Ask: “Give me a snapshot of my BOSRAI workspace.” Expect the plan name, credits and counts of contacts, campaigns, cadences, audiences and mailboxes. This calls get_workspace_overview.
  3. Numbers (2 min). Ask: “How did outreach do in the last 30 days?” Expect sent, delivered, replies, positive replies and meetings, with the previous period beside it. This calls get_roi_report.
  4. Data shape (2 min). Ask: “Search my contacts for anyone at a software company, then show my audiences and campaigns.” Three read tools, all scoped to the one workspace.
  5. A write, reversibly (2 min). Ask: “Pause the campaign that is running, then start it again.” This calls set_campaign_status twice, and you can see the status flip in the app. Nothing else in the workspace changes.
  6. Confirm the boundary (1 min). Ask: “Send an email to the first contact.” The correct behaviour is a refusal: there is no send tool. Messages are approved inside BOSRAI, or sent by the rep with an AI-disclosure line attached. See our compliance page.

What this connector cannot do, by design: send any message, enrol contacts into a sequence, edit an audience, change account settings, delete anything, or reach a workspace other than the one the credential belongs to.

Data handling: tools read and write only the authenticated workspace. Each user authorises with their own BOSRAI account through OAuth 2.1 (with dynamic client registration); we never see or store their password. Detail on the security page and in our privacy policy. Questions during review: hello@bosr.ai.

Ideas to steal