Connect external tool servers through the Model Context Protocol.
MCP (Model Context Protocol) servers allow AI systems to interact with external tools and data sources through a standardized protocol. Karmaflow.ai supports MCP in two ways:
Karmaflow.ai provides a tenant-scoped MCP server that external AI clients can connect to. This enables AI agents outside Karmaflow.ai 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.ai 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.ai manages that connection for you. Set the Application field on the server to one of the managed integrations and Karmaflow.ai 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.ai attaches the stored OAuth token for the selected account automatically and refreshes it as needed.
Karmaflow.ai speaks MCP the way the specification requires, so any server that follows it connects — including servers that enforce the protocol strictly and refuse shortcuts.
| Server style | What Karmaflow.ai does |
|---|---|
| Streamable HTTP (protocol 2025-06-18 and 2025-03-26) — the current transport, used by servers built on the official MCP SDKs | Runs the full handshake (initialize, then notifications/initialized, then requests), sends the session id and the protocol version the server negotiated on every request, reads answers whether they arrive as JSON or as an event stream, and starts a new session automatically if the server expires the old one. |
HTTP+SSE (protocol 2024-11-05) — the older transport, still served at /sse by many hosted servers |
Detected automatically: Karmaflow.ai opens the event stream, posts to the endpoint the server announces, and reads answers off the stream. |
Bare JSON-RPC — lightweight servers that answer tools/list without an initialize step |
Still supported, as a fallback. |
One thing a server can require that Karmaflow.ai does not do for it: an OAuth sign-in. If a server answers with HTTP 401 and points at OAuth resource metadata, it expects the caller to complete that provider's OAuth flow. Use a managed Application where one exists (see above); otherwise obtain a token from the provider and add it as a custom header, for example {"Authorization": "Bearer <token>"}.
After saving, click the Tools button (the wrench icon) on the server's row. Karmaflow.ai connects with the credentials you configured and lists the tools the server offers. The dialog also names the transport it connected over, for example Connected over Streamable HTTP (2025-06-18) · acme-mcp 1.4.0.
If the connection fails, the dialog shows the server's own answer:
| Message | What it means |
|---|---|
| HTTP 401 Unauthorized or HTTP 403 Forbidden | The server refused the credentials. Check the API key, or the token in your custom Authorization header. The message quotes the server's WWW-Authenticate hint when it sent one. |
| HTTP 404 Not Found or HTTP 405 Method Not Allowed | Nothing MCP answered at that URL. Hosted servers usually end in /mcp or /sse — check the provider's documentation for the exact path. |
| Could not reach the MCP server | DNS, network or TLS failure. The server must be reachable from Karmaflow.ai's servers; one on a private network or on your own machine will not be. |
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.