MCP Overview

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

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

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)

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

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

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

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

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

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

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

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

Every tool returns structured JSON, which means AI agents can act on the result without guessing.

Success:

{ "data": { "id": "cl_abc123", "name": "Café du Marché", ... } }

Error:

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

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:

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

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.

List leads sorted by score descending

Claude will pass sort: "score", sort_order: "DESC" automatically.

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

Follow the guide for your AI client: