MCP (Model Context Protocol) servers allow AI systems to interact with external tools and data sources through a standardized protocol. KarmaFlow supports MCP in two ways:
KarmaFlow provides a tenant-scoped MCP server that external AI clients can connect to. This enables AI agents outside KarmaFlow to read data, manage contacts, and build orchestration workflows programmatically.
https://omni.karmaflow.ai/mcp/{tenantId}
The built-in MCP server uses OAuth 2.0 with PKCE for secure authentication. MCP-compatible clients (Claude Desktop, Cursor, etc.) handle the OAuth flow automatically when you provide the server URL.
Alternatively, API key authentication is supported via the X-API-Key header for programmatic access.
The MCP server exposes the following tools over JSON-RPC 2.0:
| Tool | Description |
|---|---|
list_contacts |
Search and paginate contacts |
get_contact |
Retrieve a single contact by ID |
create_contact |
Create a new contact |
update_contact |
Update contact fields |
| Tool | Description |
|---|---|
list_calls |
List outbound call records |
list_chats |
List chat sessions with logs |
list_sent_emails |
List sent email activity |
list_sent_sms |
List sent SMS messages |
| Tool | Description |
|---|---|
list_orchestrations |
Search and paginate orchestrations (summary view) |
get_orchestration |
Retrieve full orchestration with step graph |
create_orchestration |
Create a new orchestration with auto-linked steps |
update_orchestration |
Replace an orchestration's steps |
delete_orchestration |
Delete an orchestration |
toggle_orchestration_enabled |
Enable or pause an orchestration |
validate_orchestration |
Dry-run validation without saving |
| Tool | Description |
|---|---|
list_call_events |
List raw voice call events with transcripts, durations, call_analysis analytics, and token usage |
list_chat_logs |
List individual chat messages across all sessions |
list_sms_sessions |
List SMS conversation sessions |
list_sms_messages |
List individual SMS messages with direction and sender role |
list_task_agent_logs |
List task agent execution runs with tool calls, execution time, and success/failure |
list_voice_campaigns |
List voice campaign/agent configurations |
list_orchestration_logs |
List orchestration workflow execution logs |
list_session_audit_logs |
List post-session audit records with outcome classification and quality flags |
All reporting tools support pagination (page, pageSize) and date range filtering (startDate, endDate as ISO 8601). Chat sessions include rich analytics data (labels, visitor_profile, account, conversation_outcome, opportunity_metrics, agent_metrics) and voice calls include call_analysis — both are returned in full so consuming AI agents can perform their own analysis.
| Tool | Description |
|---|---|
fire_orchestration_trigger |
Fire a named trigger for a specific contact |
get_trigger_catalog |
List all available trigger keys by category |
get_reference_data |
Get IDs for agents, strategies, campaigns, lists, and forms |
| Tool | Description |
|---|---|
ask_data_analyst |
Ask a natural-language question about your communication activity and get an analyzed answer |
ask_data_analyst is the same AI data analyst that powers the embedded chat on the Neo4j analytics dashboard. It queries the tenant's knowledge graph (topics, threads, organizations, contacts, engagement, replies) and returns a written answer, the cypherQuery it ran, and any chart it generated. Pass a question string; for multi-turn follow-ups, include prior turns in the optional history array ([{ role, content }]). It requires Neo4j analytics to be configured and enabled for the tenant.
External AI agents can build complete orchestrations programmatically by:
get_trigger_catalog to discover available trigger keysget_reference_data to find valid IDs for agents, strategies, campaigns, and listscreate_orchestrationSteps are provided as an ordered array of { type, name, config } objects. The server automatically generates stepId, order, and connectedTo fields, linking steps in sequence.
Triggers — What starts the workflow:
Actions — What the workflow does:
Branches — Conditional routing:
See Building Workflows for detailed step configuration reference.
Connect third-party MCP servers to extend what your KarmaFlow agents can do.
Navigate to Settings > MCP Servers to view and manage your configured servers.
Some external MCP servers don't take a static API key — they use OAuth, and KarmaFlow manages that connection for you. Set the Application field on the server to one of the managed integrations and KarmaFlow injects the right credentials on every request:
| Application | Server URL | Notes |
|---|---|---|
| Cal.com | https://mcp.cal.com/mcp |
Lets agents check availability and book meetings. Connect your account(s) first under Settings > Cal.com, then pick a Cal.com Account on the server. If left unset, the server uses your default connected account. See Cal.com Integration. |
| HubSpot | (HubSpot MCP endpoint) | Uses your connected HubSpot OAuth credentials. |
When Application is set to a managed integration, you do not add an API key on the MCP server itself — KarmaFlow attaches the stored OAuth token for the selected account automatically and refreshes it as needed.
When an external MCP server is configured, its tools become available to your AI agents. During supported workflows, agents can:
All MCP server credentials are stored securely and are only accessible within your tenant context. Each connection is isolated per tenant. The built-in MCP server enforces OAuth 2.0 or API key authentication on every request.