# MCP Servers

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:

1. **Built-in MCP Server** — Karmaflow.ai exposes its own MCP endpoint so external AI agents (Claude Desktop, Cursor, Windsurf, custom apps) can manage contacts, conversations, and orchestrations programmatically.
2. **External MCP Servers** — Connect third-party MCP servers so your Karmaflow.ai agents gain access to additional tools.

---

## Built-in MCP Server

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**.

### Endpoint

```
https://omni.karmaflow.ai/mcp/{tenantId}
```

### Authentication

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.

### Available Tools

The MCP server exposes the following tools over JSON-RPC 2.0:

#### Contact Management

| 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 |

#### Conversation History

| 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 |

#### Orchestration Management

| 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 |

#### Reporting & Raw Data

| 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.

#### Reference & Catalog

| 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 |

#### Analytics

| 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.

### Building Orchestrations via MCP

External AI agents can build complete orchestrations programmatically by:

1. Calling `get_trigger_catalog` to discover available trigger keys
2. Calling `get_reference_data` to find valid IDs for agents, strategies, campaigns, and lists
3. Composing a steps array and calling `create_orchestration`

Steps are provided as an ordered array of `{ type, name, config }` objects. The server automatically generates `stepId`, `order`, and `connectedTo` fields, linking steps in sequence.

#### Step Types

**Triggers** — What starts the workflow:
- Event trigger, Simple Time, Recurring Schedule, Call End, Chat Session End, Agent Form Submission, Form Endpoint Submission

**Actions** — What the workflow does:
- Send Email, Send SMS, Place Call, Task Agent, Wait, Push to Zapier, Transcript Webhook, Store Read/Write/Clear, Email Collector, For Each, Local List

**Branches** — Conditional routing:
- Outcome Router, If-Then Branch, AI Router

See [Building Workflows](/help/orchestrations/building-workflows) for detailed step configuration reference.

---

## External MCP Servers

Connect third-party MCP servers to extend what your Karmaflow.ai agents can do.

### Managing External Servers

Navigate to **Settings > MCP Servers** to view and manage your configured servers.

### Adding an External MCP Server

1. Click **+ Add Server**
2. Configure the server:
   - **Name** — Descriptive name for the server
   - **URL** — The MCP server endpoint
   - **Authentication** — API keys or tokens required by the server
   - **Application** — Optionally tie the server to a Karmaflow.ai-managed integration so Karmaflow.ai supplies the credentials for you (see below)
3. Click **Save**

### Application Integrations (managed OAuth)

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](/help/integrations/calcom). |
| **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.

### Which Servers You Can Connect

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

### Checking a Server

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. |

### How Agents Use External MCP

When an external MCP server is configured, its tools become available to your AI agents. During supported workflows, agents can:

1. Discover available tools from the MCP server
2. Call tools with appropriate parameters
3. Use the results to inform their responses

### Example Use Cases

- **CRM Integration** — Connect to Salesforce, Pipedrive, or other CRMs
- **E-commerce** — Look up product inventory, pricing, order status
- **Helpdesk** — Query ticket systems like Zendesk or Freshdesk
- **Custom APIs** — Any service that implements the MCP protocol

## Security

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.

<!-- SCREENSHOT: mcp-servers-list.png — MCP servers configuration page -->