Skip to main content

MCP Server (Model Context Protocol)

The kenbun MCP Server (kenbun) gives AI assistants like Claude direct access to your lead data, scoring configuration, triggers, segments, deals, and more. Your assistant can query, create, update, and delete kenbun data using natural language — as if it had full access to the kenbun UI.

What is MCP?​

Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external data sources and tools. Once you connect the kenbun MCP Server to an AI assistant, you can ask questions and give instructions in plain language, and the assistant handles the API calls for you.

Capabilities​

The kenbun MCP Server provides over 85 tools covering:

  • Leads — Read lead profiles, scores, events, activity timelines, and score explanations. Create, update, merge, and delete leads.
  • Accounts — View account summaries, buying committee members, and engagement timelines.
  • Events — Ingest new events, list and filter event history, delete events.
  • Scoring — Create and manage rulesets, rules, profile mappings, engagement levels, and profile levels.
  • Segments — List segments, view segment leads and counts, create and update segment rules.
  • Triggers — Create and manage milestone, sequence, surge, and pattern triggers. Pause, resume, and simulate them.
  • Deals — List deals and view deal attribution data.
  • Integrations — Check HubSpot and Slack connection status, view sync errors.
  • Filters — Manage inorganic activity filters.
  • Organization — List and manage Organizational Units and members.

Example Queries​

"Show me the top 10 leads by score"
"Create a scoring rule for demo_request events worth 50 points"
"Which leads are in the High Engagement segment?"
"Explain why lead abc-123 has their current score"
"What deals closed this month and who contributed?"
"Pause the Hot Lead Alert trigger"

Authentication Options​

The MCP Server supports three authentication methods. Personal Access Tokens are recommended for individual use because they authenticate as you, with your permissions.

Personal Access Token (Recommended)

  • Authenticates as your user account with your permissions
  • Generate one from Settings → Integrations → Personal Tokens
  • Token format: kbn_pat_...
  • Use in interactive mode via the authenticate tool, or set in env as KENBUN_AUTH_TOKEN

HTTP Basic Auth (Service Accounts)

  • Use shared organization credentials from Settings → Integrations → Service Accounts
  • Best for shared pipelines where a personal account should not be used
  • Set KENBUN_CLIENT_ID and KENBUN_CLIENT_SECRET

Interactive authentication via the authenticate tool

  • Start the server without credentials and call the authenticate tool from inside your AI assistant
  • Pass your PAT, JWT, or service account credentials as parameters
  • The server validates credentials immediately and stores them for the session
Environment variable names

The environment variables use the KENBUN_ prefix: KENBUN_API_URL, KENBUN_CLIENT_ID, KENBUN_CLIENT_SECRET, KENBUN_AUTH_TOKEN, and KENBUN_OU_ID. The older LEADVIBE_-prefixed names are still accepted as a deprecated fallback, so existing configurations keep working. New setups should use the KENBUN_ names.

Quick Setup​

Developer Integration

The MCP Server setup requires technical knowledge and is intended for developers integrating kenbun with AI assistants. If you are not a developer, contact your engineering team for assistance.

Step 1: Get a Personal Access Token

  1. Go to Settings → Integrations → Personal Tokens in kenbun
  2. Click Create Token
  3. Give it a name (e.g., "Claude Desktop - Work Laptop") and an optional expiry
  4. Copy the token value — it is shown only once

Step 2: Install the MCP Connector

  • Download the kenbun MCP connector from the repository
  • Install its dependencies and build it
  • Enter your kenbun API URL and token in the connector's configuration

Step 3: Configure Your AI Assistant

  • Point your AI assistant (such as Claude Desktop) to the kenbun MCP connector, registered as kenbun
  • Provide your kenbun API URL and token in the assistant's server configuration
  • Refer to the MCP connector's README for detailed setup instructions specific to your AI assistant

Step 4: Test the Connection

  • Restart your AI assistant
  • Ask: "Use the kenbun whoami tool to check my connection"
  • The response will confirm your authentication status and active Organizational Unit

Multi-Tenant Setup (Multiple Organizational Units)​

If your account has access to more than one Organizational Unit, use the built-in session tools to navigate between them:

ToolDescription
authenticateAuthenticate with a PAT, JWT, or service account credentials
whoamiCheck your current authentication status and active OU
list_available_ousList all Organizational Units you have access to
set_active_ouSwitch to a different OU — all subsequent calls use that OU

Example workflow:

"List my available organizational units"
"Switch to the EMEA Sales unit"
"Now show me the top leads in this unit"

Organizational Unit Scoping​

All data access is scoped to your active Organizational Unit. If you have multiple OUs, use set_active_ou to switch between them. If no OU is specified in the environment configuration, the server uses your default OU.

Security Best Practices​

  • Never share your Personal Access Token — it authenticates as you
  • Set expiry dates on tokens — especially for temporary or one-off connections
  • Use descriptive token names — include the assistant name and device (e.g., "Claude Desktop - Laptop")
  • Revoke unused tokens — check Settings → Integrations → Personal Tokens and remove stale entries
  • Use environment variables — never hardcode credentials in configuration files

Troubleshooting​

Authentication Failed

  • Verify your token in Settings → Integrations → Personal Tokens
  • Check that the token has not been revoked or expired
  • Use the whoami tool to diagnose: it reports authentication status without requiring a working session

Connection Errors

  • Verify KENBUN_API_URL is set to the correct kenbun API URL (the older LEADVIBE_API_URL is still accepted as a deprecated fallback)

No Data Returned

  • Check your active OU using the whoami tool
  • Use list_available_ous to confirm which OUs your account can access
  • Switch OUs with set_active_ou if needed

Tool Not Found

  • The server registers as kenbun — ensure your AI assistant configuration references this name
  • Restart the AI assistant after updating the MCP server configuration