MCP Server

The Journeybee MCP server lets AI assistants like Claude manage your partners, leads, deals, and more through the Model Context Protocol. There are two ways to connect, both to the same per-region URL — pick by client:

OAuth 2.1 — for interactive clients (Claude, ChatGPT, Cursor). Sign in and approve access; no install, no API keys, nothing to run locally.
API key — for open-source models, headless runtimes (Ollama, Llama, Mistral, LangChain), and CI. Any MCP-capable client points at the region URL with an Authorization: Bearer header. See Connect with an API key.

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.journeybee.io/mcp`
Australia (AU)	`https://au.mcp.journeybee.io/mcp`

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.

Connect with an API key (open-source models, headless, CI)

Open-source models and headless runtimes can’t do the browser sign-in, so they connect with a Journeybee API key instead of OAuth. The endpoint is the same — the API key is just sent as the Bearer token. Requirements

The API & MCP module (api_mcp) enabled on your company.
An API key from Settings > API Keys in app.journeybee.io (see Authentication). Use a Read key for read-only access; a Write key to create and update.

Configure your client Point any MCP-capable client at your region’s /mcp endpoint over Streamable HTTP, with the key in the Authorization header. Most clients accept a config like this:

{
  "mcpServers": {
    "journeybee": {
      "url": "https://mcp.journeybee.io/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Use the /mcp path on your region’s host from the table above (https://au.mcp.journeybee.io/mcp for Australia). The same key formats the REST API accepts work here — Authorization: Bearer YOUR_API_KEY or Authorization: Api-Key YOUR_API_KEY. To check connectivity without a client, list the tools directly:

curl -sS https://mcp.journeybee.io/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Same guarantees as OAuth: the key is scoped to one company, carries exactly its own Read/Write permission (a read-only key never sees write tools), and reaches only its own region. The only difference is how you obtain the token — a pre-issued key instead of an interactive consent screen.

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

Total: 23 tools — all 207 API endpoints accessible via discovery, common operations optimized with composites.

Composite tools

Start here. Composites combine multiple API calls into a single, high-level operation with formatted markdown output.

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

Workflow tools (multi-step operations)

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

Access control tools

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

Discovery tools

For any operation not covered by composites, use the 3 discovery tools to access all 207+ API endpoints:

`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" })

Returns: parameter names, types, required/optional, descriptions.

`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.
API keys get the same per-request, company-scoped, region-resident guarantees — the only difference is how the token is obtained (a pre-issued key versus an OAuth consent screen), not what it can reach. The server forwards your key to the same regional API as the SDK; it stores no key and shares nothing across tenants.
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.

Getting Started

SDKs & Tools

Embedding

Resources

MCP Server

MCP Server

Connect the hosted server (OAuth)

Connect with an API key (open-source models, headless, CI)

Architecture

Composite tools

Overview tools (get full entity context)

Analytics & search

Workflow tools (multi-step operations)

Access control tools

Discovery tools

`list_endpoints`

`get_endpoint_schema`

`call_endpoint`

Naming conventions

Resources

Dynamic resources (fetched from API)

Static resources (enum values)

Prompts

Error handling

Markdown support

Security

​MCP Server

​Connect the hosted server (OAuth)

​Connect with an API key (open-source models, headless, CI)

​Architecture

​Composite tools

​Overview tools (get full entity context)

​Analytics & search

​Workflow tools (multi-step operations)

​Access control tools

​Discovery tools

​list_endpoints

​get_endpoint_schema

​call_endpoint

​Naming conventions

​Resources

​Dynamic resources (fetched from API)

​Static resources (enum values)

​Prompts

​Error handling

​Markdown support

​Security

MCP Server

Connect the hosted server (OAuth)

Connect with an API key (open-source models, headless, CI)

Architecture

Composite tools

Overview tools (get full entity context)

Analytics & search

Workflow tools (multi-step operations)

Access control tools

Discovery tools

`list_endpoints`

`get_endpoint_schema`

`call_endpoint`

Naming conventions

Resources

Dynamic resources (fetched from API)

Static resources (enum values)

Prompts

Error handling

Markdown support

Security