MCP Integration: Setup guides for using Klozeo via MCP with Claude Desktop, Claude Code, Cursor, and other tools # Claude Code > Connect Claude Code CLI to your Klozeo lead database via MCP. Claude Code supports MCP servers natively. Klozeo uses the streamable HTTP transport (preferred). 1. Add the Klozeo MCP server to your Claude Code config: ```bash claude mcp add klozeo --transport http https://mcp.klozeo.com/mcp ``` On first connection, Claude Code opens a browser for OAuth authorization. Sign in with your Klozeo account — an API key is issued automatically. 2. Verify the connection: ```bash claude mcp list ``` You should see `klozeo` with status `connected` and 33 tools. 3. Use Klozeo tools in any Claude Code session: ```plaintext /mcp klozeo list_leads query="restaurants in Paris" ``` Or simply describe what you need in natural language — Claude will use the appropriate MCP tool automatically. ## Manual API key setup [Section titled “Manual API key setup”](#manual-api-key-setup) If you prefer to use an existing API key instead of OAuth: ```bash claude mcp add klozeo \ --transport http \ --header "Authorization: Bearer sk_live_your_key" \ https://mcp.klozeo.com/mcp ``` # Claude Desktop > Connect Claude Desktop to your Klozeo lead database via MCP. > **Note:** Claude Desktop requires a manually configured API key — browser-based OAuth is not yet supported by Claude Desktop’s MCP implementation. 1. Open Claude Desktop settings → **Developer** → **Edit Config**. 2. Add the Klozeo MCP server to `claude_desktop_config.json`: ```json { "mcpServers": { "klozeo": { "type": "http", "url": "https://mcp.klozeo.com/mcp", "headers": { "Authorization": "Bearer sk_live_your_key" } } } } ``` Replace `sk_live_your_key` with your actual API key from the [dashboard](https://klozeo.com/dashboard). 3. Restart Claude Desktop. 4. In any new conversation, you’ll see **Klozeo** listed in the tools/context area. You should see 33 tools listed — if you don’t, see Troubleshooting below. 5. Try a natural language query: > *“Find all leads in Paris with a rating above 4 and send me the top 5”* ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) * **Tools not showing:** Restart Claude Desktop after config changes. Make sure you are on Claude Desktop v0.10 or later (which supports remote HTTP MCP servers). * **Auth error:** Verify your `Authorization` header value is correct and the API key has not been revoked from the dashboard. * **Connection refused:** Check that `mcp.klozeo.com` is reachable from your network. # Cline / Roo Code / Smithery > Connect Cline, Roo Code, or Smithery to Klozeo via MCP. ## Cline & Roo Code [Section titled “Cline & Roo Code”](#cline--roo-code) Both Cline and Roo Code support MCP servers via the VS Code extension settings. In your VS Code `settings.json` (`Cmd+Shift+P` → “Open User Settings (JSON)”): ```json { "cline.mcpServers": { "klozeo": { "url": "https://mcp.klozeo.com/mcp", "headers": { "Authorization": "Bearer sk_live_your_key" } } } } ``` Restart VS Code. Klozeo tools appear in the Cline/Roo sidebar under **MCP Tools**. ## Smithery [Section titled “Smithery”](#smithery) Klozeo is available as a managed MCP server on Smithery: 1. Go to [smithery.ai](https://smithery.ai) and search for **Klozeo**. 2. Click **Connect** and authorize with your Klozeo account. 3. Copy the generated connection string (it looks like `https://mcp.smithery.ai/klozeo?apiKey=...`) into the **Server URL** field of your Smithery workspace configuration. ## Goose [Section titled “Goose”](#goose) Add to your Goose config (`~/.config/goose/config.yaml`): ```yaml mcp: servers: - name: klozeo url: https://mcp.klozeo.com/mcp headers: Authorization: "Bearer sk_live_your_key" ``` Restart Goose. Run `goose mcp list` to verify the `klozeo` server appears with 33 tools. # Cursor > Connect Cursor to your Klozeo lead database via MCP. 1. Open Cursor settings (`Cmd+,`) → **Features** → **MCP Servers** → **Add server**. 2. Configure the Klozeo server: | Field | Value | | ----- | ---------------------------- | | Name | `klozeo` | | Type | `http` | | URL | `https://mcp.klozeo.com/mcp` | 3. Click **Save**. Cursor will open your browser for OAuth authorization. 4. Sign in to your Klozeo account. An API key is generated and stored automatically. 5. In any Cursor chat, Klozeo tools are now available. Try: > *“List all leads imported this month and score them”* ## Manual setup (API key) [Section titled “Manual setup (API key)”](#manual-setup-api-key) If OAuth is not available, add the API key as a header in the MCP config (`~/.cursor/mcp.json`): ```json { "mcpServers": { "klozeo": { "url": "https://mcp.klozeo.com/mcp", "headers": { "Authorization": "Bearer sk_live_your_key" } } } } ``` # MCP Overview > Connect Claude, Cursor, and any MCP-compatible AI client to your Klozeo lead database. Klozeo implements the **Model Context Protocol (MCP)** — an open standard that lets AI assistants directly query and manipulate your lead database using natural language. ## Authentication is automatic [Section titled “Authentication is automatic”](#authentication-is-automatic) When you connect for the first time, your MCP client opens a browser window — sign in to your Klozeo account and authorize access. An API key is generated and stored automatically. You won’t need to copy-paste anything. If you prefer to use an existing API key directly (for example, in a CI environment), each client setup guide includes manual instructions. ## Transport [Section titled “Transport”](#transport) Klozeo uses the **streamable HTTP transport** (preferred by default). Claude Desktop is the exception — it requires the **SSE transport** because OAuth is not supported in that client. All other clients (Claude Code, Cursor, Cline, Roo Code, Goose, Smithery) use streamable HTTP. ## Available tools (33) [Section titled “Available tools (33)”](#available-tools-33) ### Leads [Section titled “Leads”](#leads) | Tool | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | | `list_leads` | List leads with filters, sorting, and pagination. Pass `format: csv/json/xlsx` to export all records without pagination | | `get_lead` | Get a specific lead by ID | | `create_lead` | Create a new lead (deduplication automatic) | | `update_lead` | Update lead fields | | `delete_lead` | Delete a lead — requires `confirm: true` | | `create_lead_tag` | Add a tag to a lead (idempotent) | ### Batch Operations [Section titled “Batch Operations”](#batch-operations) | Tool | Description | | -------------------- | ----------------------------------------------------------------------- | | `batch_create_leads` | Create up to 100/500 leads in one call (deduplication applied per item) | | `batch_update_leads` | Apply the same field update to multiple leads | | `batch_delete_leads` | Delete multiple leads — requires `confirm: true` | ### Notes [Section titled “Notes”](#notes) | Tool | Description | | ------------- | ---------------------------------------------- | | `create_note` | Add a timestamped note to a lead | | `list_notes` | List all notes for a lead | | `update_note` | Edit the content of an existing note | | `delete_note` | Delete a note by ID — requires `confirm: true` | ### Attributes [Section titled “Attributes”](#attributes) | Tool | Description | | ------------------ | --------------------------------------------------------- | | `list_attributes` | List all custom attributes for a lead | | `create_attribute` | Add a custom attribute (text, number, bool, list, object) | | `update_attribute` | Update the value of an existing attribute | | `delete_attribute` | Remove a custom attribute — requires `confirm: true` | ### Scoring [Section titled “Scoring”](#scoring) | Tool | Description | | --------------------- | ----------------------------------------------------- | | `list_scoring_rules` | List all scoring rules | | `create_scoring_rule` | Create a new scoring rule with an expression | | `get_scoring_rule` | Get a single scoring rule by ID | | `update_scoring_rule` | Update a scoring rule’s name, expression, or priority | | `delete_scoring_rule` | Delete a scoring rule — requires `confirm: true` | | `update_lead_score` | Recalculate and persist the score for a single lead | | `update_all_scores` | Recalculate and persist scores for all leads | ### Webhooks [Section titled “Webhooks”](#webhooks) | Tool | Description | | ---------------- | -------------------------------------------------------- | | `list_webhooks` | List all webhook subscriptions | | `create_webhook` | Create a new webhook subscription | | `delete_webhook` | Delete a webhook subscription — requires `confirm: true` | ### API Keys [Section titled “API Keys”](#api-keys) | Tool | Description | | ---------------- | -------------------------------------------- | | `list_api_keys` | List all API keys for your account | | `create_api_key` | Create a new named API key | | `delete_api_key` | Revoke an API key — requires `confirm: true` | ### Analytics [Section titled “Analytics”](#analytics) | Tool | Description | | ----------------- | --------------------------------- | | `get_stats` | Get aggregate account statistics | | `list_categories` | List all distinct lead categories | | `list_cities` | List all distinct cities | ## How tool responses work [Section titled “How tool responses work”](#how-tool-responses-work) Every tool returns structured JSON, which means AI agents can act on the result without guessing. **Success:** ```json { "data": { "id": "cl_abc123", "name": "Café du Marché", ... } } ``` **Error:** ```json { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Lead not found.", "status": 404 } } ``` Error codes are stable and machine-readable: `RESOURCE_NOT_FOUND`, `VALIDATION_ERROR`, `UNAUTHORIZED`, `CONFLICT`, `RATE_LIMITED`, `INTERNAL_ERROR`. An agent hitting a rate limit can read `RATE_LIMITED` and decide to retry — it doesn’t have to parse a prose string. ## Destructive operations require confirmation [Section titled “Destructive operations require confirmation”](#destructive-operations-require-confirmation) `delete_lead`, `delete_note`, and `delete_webhook` won’t execute unless `confirm: true` is passed. This means an AI agent can’t accidentally delete a record because it misread your intent — it has to be explicitly instructed to confirm. If `confirm` is missing or false, the tool returns: ```json { "error": { "code": "CONFIRMATION_REQUIRED", "message": "Set confirm: true to delete.", "status": 400 } } ``` In practice, you just tell the AI “delete lead X, confirm it” and it handles the parameter correctly. ## Sorting [Section titled “Sorting”](#sorting) `list_leads` accepts a `sort` parameter (not `sort_by`) for the field name, and `sort_order` for direction (`ASC` or `DESC`). Pass `format: csv/json/xlsx` to export all records without pagination. ```plaintext List leads sorted by score descending ``` Claude will pass `sort: "score", sort_order: "DESC"` automatically. ## Designed for agent reliability [Section titled “Designed for agent reliability”](#designed-for-agent-reliability) Most MCP servers are written for humans to browse — long descriptions, inconsistent verb choices, free-form error strings. That works fine in a UI. In an agentic context, it costs tokens and causes tool selection mistakes. A few specific decisions we made: **Consistent verb prefixes.** Every tool name starts with `list_`, `get_`, `create_`, `update_`, or `delete_`. No synonyms, no exceptions. Models trained on natural language have strong priors on these verbs, which means fewer wrong tool selections and fewer retries. **Short, factual descriptions.** Tool descriptions are capped at 80 characters. Parameter descriptions at 40. No examples, no preamble (“This tool allows you to…”). Just the action and the object. This keeps the tool manifest compact — 33 tools load comfortably within a single context window with room to spare for your actual task. **Machine-readable errors.** Every error has a stable `code` field (`RESOURCE_NOT_FOUND`, `RATE_LIMITED`, etc.). An agent can branch on the code without parsing prose. This matters when building multi-step workflows where one tool’s failure should inform the next step. **Explicit confirmation for destructive ops.** Delete tools require `confirm: true`. An agent that misunderstood “remove duplicates” won’t silently wipe records — it will get a `CONFIRMATION_REQUIRED` error and surface it to you before doing anything irreversible. **Single source of truth for schemas.** Each tool’s parameter schema is defined once and shared across the MCP interface, the API, and the SDK types. Adding or changing a field touches one place — there’s no separate “MCP version” of the schema that can drift out of sync with what the API actually accepts. These aren’t architectural novelties — they’re just the conventions the [MCP spec](https://modelcontextprotocol.io) recommends, applied consistently. The result is a server that agents use correctly on the first try more often, which means less back-and-forth and fewer unexpected outcomes for you. ## Setup guides [Section titled “Setup guides”](#setup-guides) Follow the guide for your AI client: * [Claude Desktop](/mcp/claude-desktop/) * [Claude Code](/mcp/claude-code/) * [Cursor](/mcp/cursor/) * [Cline / Roo Code / Smithery / Goose](/mcp/cline-roo-smithery/)