> ## Documentation Index
> Fetch the complete documentation index at: https://docs.journeybee.io/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Connect AI assistants to Journeybee via the Model Context Protocol
# MCP Server
The Journeybee MCP server lets AI assistants like Claude manage your partners, leads, deals, and more through the [Model Context Protocol](https://modelcontextprotocol.io).
The hosted MCP is **launching soon**. This guide describes how it works — the connect flow below isn't live just yet.
You connect by adding **your region's URL** in your AI client and signing in with OAuth — no install, no API keys, nothing to run locally.
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.
1. 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.
2. The client opens Journeybee's sign-in page. Log in as usual.
3. On the **consent screen**, choose which company the connection may access and click **Allow**.
4. 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 |
**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.
* **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.