MCP Server
The Journeybee MCP server lets AI assistants like Claude manage your partners, leads, deals, and more through the Model Context Protocol.
The hosted MCP is launching soon. This guide describes how it works — the connect flow below isn’t live just yet.
Connecting requires the API & MCP module (api_mcp) to be enabled for your company. Until it is, the OAuth consent screen won’t issue a token. Ask your Journeybee admin to enable it (Settings → company modules), or contact support.
Connect the hosted server (OAuth)
The hosted server runs one endpoint per region and authenticates with OAuth 2.1 — you log in with your normal Journeybee account and approve access, so there are no API keys to copy.
Use the URL for the region your company’s data lives in:
| Region | MCP URL |
|---|
| Europe (EU) | https://mcp.eu.journeybee.io |
| Australia (AU) | https://mcp.au.journeybee.io |
| United States (US) | https://mcp.us.journeybee.io |
Regions roll out EU first, then AU and US. Your region is the one you signed up in / log in to Journeybee from — if unsure, ask your admin or support. Connecting the wrong region’s URL simply won’t find your account.
- In your AI client (Claude, ChatGPT, or any MCP-compatible client), add a remote MCP server / custom connector with your region’s URL from the table above.
- The client opens Journeybee’s sign-in page. Log in as usual.
- On the consent screen, choose which company the connection may access and click Allow.
- You’re returned to your client, connected. Tokens refresh automatically; revoke access any time by removing the connector.
Access is scoped to the one company you pick at consent, with the same permissions your account has. Nothing is shared across tenants — and your data never leaves its region.
Architecture
The MCP server is organized into four layers:
| Layer | Count | Purpose |
|---|
| Composite tools | 20 | High-level, outcome-oriented operations (1 tool call = complete workflow) |
| Discovery tools | 3 | Browse, inspect, and execute any of 207+ API endpoints on demand |
| Resources | 17 | Read-only configuration data (no tool call needed) |
| Prompts | 10 | Guided workflow templates |
Overview tools (get full entity context)
| Tool | Description |
|---|
getLeadOverview | Lead + notes, tasks, products, contacts, attributions, custom fields |
getDealOverview | Deal + notes, products, commission, payments, tasks, custom fields |
getPartnerOverview | Partner + contacts, notes, custom fields, domains |
getResourceOverview | Resource + content blocks |
getCertificationOverview | Certification + curriculum, enrollments |
getRoomOverview | Room + content blocks |
Analytics & search
| Tool | Description |
|---|
getPipelineSummary | Deal stages with counts and values (currency-converted, filterable by date and partner type) |
searchEverything | Search partners, leads, and deals by keyword in one call |
getCommissionReport | All commission rules with tier/category assignments |
getPartnerCommissions | Commission rules applicable to a specific partner |
whoami | Account info, team size, partner count |
| Tool | Description |
|---|
createLeadWithDetails | Create lead + add tags + assign users |
createPartnerWithContacts | Create partner + add contacts |
updatePartnerDetails | Update partner fields + custom fields in one call |
assignTaskToPartner | Create a task linked to a partner |
createResourceWithBlocks | Create resource + add content blocks |
buildRoom | Create room + add content blocks |
| Tool | Description |
|---|
getRoomAccessSettings | See which tiers, categories, stages, and partnerships can access a room |
getResourceAccessSettings | See which partner types can access a resource |
getCertificationAccessSettings | See certification access settings |
list_endpoints
Browse all available API endpoints grouped by domain.
list_endpoints() # All endpoints
list_endpoints({ domain: "Leads" }) # Just lead endpoints
get_endpoint_schema
Get the full parameter schema for any endpoint before calling it.
get_endpoint_schema({ endpoint: "addLeadTag" })
call_endpoint
Execute any endpoint by operationId.
call_endpoint({
endpoint: "addLeadTag",
args: { uuid: "lead-uuid", tag_uuid: "tag-uuid" }
})
Naming conventions
OperationIds follow predictable patterns:
| Pattern | Example |
|---|
listX | listPartners, listLeads, listDeals |
getX | getPartner, getLead, getDeal |
createX | createPartner, createLead, createDeal |
updateX | updatePartner, updateLead, updateDeal |
deleteX | deletePartner, deleteLead, deleteDeal |
addXY | addLeadTag, addPartnerDomain |
removeXY | removeLeadTag, removePartnerDomain |
Resources
Resources provide read-only configuration data that the AI can reference without making tool calls. Access them through the MCP client’s resource browser.
Dynamic resources (fetched from API)
| Resource | Description |
|---|
| Pipeline Summary | Deal stages with counts and values |
| Partner Stages | Partner pipeline stages |
| Deal Stages | Deal pipeline stages |
| Tiers | Partner tiers |
| Categories | Partner categories |
| Tags | All tags (lead, partner, deal, etc.) |
| Custom Fields | Field definitions with types and options |
| Team Members | Company users with roles |
| Currencies | Available currencies |
| Commission Rules | Commission calculations and scoping |
| Attributions | Lead attribution types |
Static resources (enum values)
| Resource | Values |
|---|
| Partner Types | referral, reseller, distributor |
| Lead Statuses | new, converted, rejected |
| Deal Phases | new, in_progress, won, lost, expired, on_hold |
| Resource Block Types | text, image, video, document, button, embed, powerpoint, files, quiz |
| Room Block Types | text, image, video, document, embed, introduction, action_bar, banner, lead_deal_analytics, goals, link, advanced_search, files, pricing_calculator |
| Room Types | overview, leads, deals, payments, resources, certifications, projects, contacts, messages, custom, and more |
Prompts
Select a prompt template from the MCP client for guided workflows:
- Analyze my pipeline — deal distribution, revenue forecasting
- Partner quarterly review — partner performance summary
- Set up a new partner — step-by-step partner creation
- Create a learning path — certification with resources
- Find and update — search + modify entities
- Commission report — commission rules analysis
- Bulk update leads — batch lead modifications
- Build a portal room — room creation with blocks
- Check access settings — room/resource access audit
- Manage tasks — task creation and assignment
Error handling
When operations fail, the MCP returns actionable error messages:
- Validation errors list the specific fields that are wrong and suggest using
get_endpoint_schema
- Not found errors suggest using
searchEverything to find the entity
- Conflict errors explain what’s blocking the operation (e.g., “Stage in use by 12 deals”)
- Auth errors indicate whether your session is missing/invalid or lacks write permission — reconnect or re-authorize the connector
- Module-disabled errors mean the company’s API & MCP access (
api_mcp) is off (every call fails) or a specific feature module is disabled — contact your admin
Markdown support
All text content fields accept markdown. Use markdown for:
- Notes (lead, deal, partner) — the
content field
- Tasks — the
content field
- Resource text blocks — use the
markdown field
- Room text blocks — use the
markdown field
Markdown is converted to rich text automatically. Supports headings, bold, italic, lists, links, code blocks, blockquotes.
Security
- OAuth 2.1 (Authorization Code + PKCE). Each request carries the caller’s own short-lived token — the server never holds a shared cross-tenant key. Tokens are scoped to the single company chosen at consent and refresh-rotate; revoke by removing the connector.
- Account permissions apply. The connection has exactly the permissions your Journeybee account has — a read-only account can only reach read tools.
- Access requires the API & MCP module (
api_mcp) on your company — enforced on every /v1 call.
- Region-resident. Each region runs its own isolated endpoint; you connect your region’s URL and it only reaches that region’s API and database. A company’s data never crosses regions.
- All data is scoped to your company; the MCP server calls the same public API as the SDK — no additional access, no internal-only tools exposed.
- Tool annotations indicate read-only, destructive, and idempotent operations.
