Skip to content

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.

The /mcp endpoint accepts two kinds of credentials:

  • A dashboard API key, sent on each request as Authorization: Bearer <API_KEY> or X-API-Key: <API_KEY>. It gives the full catalogue of 38 tools. Create keys in the API keys dashboard.
  • Browser login (OAuth), for clients that support MCP authorization. Configure only the URL https://mcp.klozeo.com/mcp; the client opens Klozeo in your browser to sign in and approve access. Browser login gives the same twelve tools, scopes and consent as /v1/mcp: read access first, and write access after a separate approval. Tools for keys, webhooks, scoring, attributes, deletions and batches stay available with an API key only. Browser login does not create an API key.

A request with no credential receives 401 with a WWW-Authenticate challenge pointing to /.well-known/oauth-protected-resource/mcp. Protocol messages such as initialize and tool discovery do not consume API quota. The API validates credentials and applies quotas when an actual tool calls it; a quota error is returned as a tool error without closing the MCP session.

The separate /openai/v1/mcp endpoint publishes OAuth discovery at /.well-known/oauth-protected-resource/openai/v1/mcp. Its resource identifier is the exact endpoint URL, without a trailing slash. A request without a valid OpenAI credential receives 401 with a WWW-Authenticate discovery challenge requesting leads:read. Classic API keys are not accepted on this endpoint.

The neutral endpoint https://mcp.klozeo.com/v1/mcp, used by Claude, exposes the same nine tools plus save_leads, list_workspaces and list_statuses (twelve tools) using stateless Streamable HTTP. Its protected-resource metadata is /.well-known/oauth-protected-resource/v1/mcp. The legacy URL remains supported. Each exact URL is a separate OAuth resource: access tokens, refresh tokens and saved consent for one cannot authorize the other. Connecting at the neutral URL requires a fresh read consent and then a separate write step-up. Both URLs share transport rate limits and origin protection; neither accepts classic API keys.

OpenAI authorization uses single-use codes with PKCE S256 and exact resource binding. Codes for this endpoint cannot be exchanged for classic API keys, and its access tokens are rejected on the classic endpoint. Token exchange issues opaque access tokens valid for eight hours, stored only as hashes. Clients registered for refresh_token also receive rotating refresh tokens valid for six months after issuance. Reusing a consumed refresh token revokes its entire family. offline_access is not advertised in protected-resource metadata or challenges. Unsupported requested grant metadata in a registration falls back to authorization_code. An authorization request for https://mcp.klozeo.com/mcp, or with no resource, is bound to https://mcp.klozeo.com/v1/mcp: its tokens work on both URLs.

The OpenAI v1 catalogue contains exactly nine tools: list_leads, get_lead, list_notes, get_stats, list_categories, list_cities, create_note, update_lead and create_lead_tag. The six read tools require leads:read. All three write tools require leads:write. Each call checks the current connection, workspace and role.

Write tools require an owner, admin or editor role and explicit write consent. The first connection grants read access only; authorize again for the write step-up. A viewer is refused with forbidden, without requesting broader scopes.

  • create_note requires lead_id, content and an idempotency_key (1–200 characters). Generate a unique key for each intended note and reuse it with exactly the same input on retries within 30 days. Receipts store only the note ID and an input hash. A retry returns the current note; if it has been deleted, HTTP 410 / NOTE_ALREADY_DELETED returns its ID without text or re-creation. If the parent lead was deleted, the retry returns 404 instead of 410. Reusing the key with a different lead/content returns 409. Keys are scoped to the connected workspace and actor. The daily retention task purges receipts older than 30 days; after purge, the key is treated as a new operation. Do not replay an old operation beyond 30 days. Account deletion also purges receipts. Use a new key to deliberately create another note with identical content.
  • update_lead accepts only name, source, city, country, phone, email, website, category, status and tags. All other fields, null values and an empty update are refused. Supplied fields alone change; an empty string clears a text field and tags: [] clears tags. tags replaces the entire array. On the classic and neutral endpoints, status takes any value up to 50 characters; list_statuses returns the workspace’s status list. The ChatGPT endpoint still offers the five default statuses.
  • create_lead_tag adds one tag atomically, preserving other concurrent additions. Tags are trimmed and must contain 1–64 Unicode characters after trimming. A tag already present is a no-op.

All three tools declare readOnlyHint: false, destructiveHint: true and openWorldHint: true: successful writes may send note.created or lead.updated webhooks to configured third-party URLs, and delivered webhooks cannot be undone. Notes and tag additions declare idempotentHint: true; their retries do not resend webhooks or duplicate audit entries. update_lead retains idempotentHint: false because each call may resend a webhook. A write’s webhook event is queued in the write’s transaction and delivered, at least once, after it commits. The audit records the authenticated member as actor and the selected workspace. OpenAI tokens never grant the classic catalogue.

get_lead and list_notes on both MCP surfaces require an identifier in the form cl_<uuid>. Malformed identifiers are rejected before calling the API. API connection errors return a generic temporary-unavailability tool error without disclosing internal addresses.

list_notes returns 20 notes by default, at most 50 per page, with next_cursor and has_more; note text is limited to 2,000 characters. Categories and cities return at most 200 values and indicate truncation. Results are JSON text inside MCP content, wrapped in { "data": … }. API quota errors are tool errors and leave the session and tool discovery usable.

Initial consent is limited to read access, including notes. Write access requires an additional explicit consent; it cannot override the user’s workspace role. On the Claude endpoint (/v1/mcp, and /mcp with an OAuth login), the consent page lets you choose one or more workspaces: those you own, and those where you are an active admin, editor or viewer. The ChatGPT endpoint offers the same workspaces but takes one. Tick each workspace the app may reach; the page reloads with the permissions of that selection, so you review them before authorizing, including during write step-up. One app connection reaches exactly the workspaces you ticked, each with your role there: unticking a workspace on a later consent removes it from the connection. Changing the selected workspaces requires the assistant to reconnect. Your dashboard workspace preference does not select them for OAuth. A viewer role in any chosen workspace limits the whole connection to read access, and write access needs an owner, admin or editor role in every chosen workspace. Team access is checked by member ID on every call; the connected app cannot change the workspace, actor or role using headers. Klozeo remembers approved scopes for each member, OAuth client and the workspaces already granted. When several workspaces are available, the workspace choice stays visible. Adding a workspace to a connection always asks for your consent again, and the whole connection then starts again with read access. Removing the invitation or changing its role removes that workspace from the connection and invalidates the remembered agreement; the connection keeps its other workspaces, and one left with none is revoked with its tokens. Reinviting the member or promoting their role requires new consent; it never revives the workspace on an existing connection. The audit records the member who made the change, within the team’s workspace. The screen returns for new scopes, a local callback, revocation, password changes, passkey removal, loss of team access or role, changed callback registration, or six months without token issuance. Each successful issuance extends that inactivity window. For an authenticated tool call missing a required scope, the HTTP 403 response contains the same challenge in WWW-Authenticate and in the JSON-RPC tool result (isError: true, _meta["mcp/www_authenticate"]). Some clients, including the Go SDK, report non-2xx responses as transport errors rather than parsing that tool result. Role refusals do not invite another scope consent.

The classic discovery document at /.well-known/oauth-protected-resource/mcp describes /mcp and advertises its OAuth authorization server. The root /.well-known/oauth-protected-resource returns 404; use the resource-specific URL.

Dynamic registration accepts up to 10 callback URIs per client. Use HTTPS, or HTTP with the exact host localhost or 127.0.0.1 (any callback port is allowed). Credentials and fragments in callback URIs are rejected. Client names are limited to 255 UTF-8 bytes.

The consent page shows the callback host alongside the client name. Check that host before authorizing. Denying consumes the request; restart authorization in your MCP client to try again.

If you are not signed in, Klozeo asks you to sign in first, then brings you back to the same consent page. An authorization request is valid for 10 minutes and can be answered once. Once it has expired, the consent page says so and, if you are signed in, offers to return to your MCP client, which receives error=access_denied with its state.

Every authorization response sent back to your client, successful or not, includes iss=https://mcp.klozeo.com, the issuer of the authorization server metadata (RFC 9207). The metadata advertises authorization_response_iss_parameter_supported: true. Restart authorization in your client to connect again. The same applies when your client reconnects after its access has expired: if your Klozeo session is still active, the consent page appears directly.

The consent page is shown in French when your browser prefers French.

Registration temporarily allows 10 attempts per hour per client IP address (per /64 network for IPv6), including invalid attempts. If the client address cannot be verified, attempts are counted per address and User-Agent, within a shared hourly ceiling. A 429 response includes Retry-After.

Accepted registration requests also trigger cleanup of registrations older than 30 days that have never issued a code. Clients with an active consent request or an outstanding authorization code are retained. Clients already present before this cleanup was introduced are preserved because historical authorization codes may already have been consumed.

Klozeo serves Streamable HTTP on /mcp. Configure a client that supports this transport, with an API key in the request headers or with browser login. Client-specific setup guides are linked below.

Tool Description
list_leads List lead summaries with combined search and filters, sorting, and cursor pagination (max 100 per page)
get_lead Get a specific lead by ID
create_lead Create a new lead (deduplication automatic); optional enrich fills empty company fields; do_not_contact: true marks it do-not-contact; optional attributes are added or updated on a merge and reported in attribute_changes, except a locked attribute, which is ignored with the reason locked
enrich_lead Fill empty company fields by the stored SIREN (classic only)
update_lead Update lead fields; do_not_contact: true marks the lead do-not-contact, false is refused (DO_NOT_CONTACT_LOCKED): only a person lifts it in the dashboard
delete_lead Delete a lead (requires confirm: true)
create_lead_tag Add a tag to a lead (idempotent)
create_lead_field_lock Lock a field (id, field) so duplicate merges and imports never overwrite it; returns the lead with locked_fields. Owner, admin or editor
delete_lead_field_lock Unlock a field so merges and imports write it again. Owner, admin or editor
create_lead_attribute_lock Lock a custom attribute (lead_id, attr_id from get_lead or list_attributes) so duplicate merges, imports and company enrichment never write it; returns the attribute with "locked": true. Needs an API key with the full scope
delete_lead_attribute_lock Unlock a custom attribute so merges, imports and company enrichment write it again; returns the attribute. Needs an API key with the full scope

get_lead and each list_leads summary return locked_fields. When create_lead or batch_create_leads merges into a lead with locked fields, the result lists the fields it did not write in skipped_locked_fields. update_lead still writes locked fields: a lock only guards against automatic writes. get_lead and list_attributes show "locked": true on each locked custom attribute, and update_attribute still writes it. → Lock Attribute

On the classic endpoint (https://mcp.klozeo.com/mcp), create_lead, update_lead, batch_create_leads and batch_update_leads accept assignee: the email of the workspace owner or an active member. On update_lead and batch_update_leads, null or "" unassigns the lead. Anyone else is refused with assignee_not_member (in a batch, the item fails). A duplicate merge never changes the assignee. The Claude and ChatGPT connectors cannot assign leads.

Tool Description
batch_create_leads Create up to 100/500 leads in one call (deduplication applied per item; do_not_contact is never lifted by a merge; each item accepts attributes)
batch_update_leads Apply the same field update to multiple leads
batch_delete_leads Delete multiple leads (requires confirm: true)
Tool Description
create_note Add a timestamped note to a lead
list_notes List a page of notes for a lead (20 by default; follow next_cursor while has_more)
update_note Edit the content of an existing note
delete_note Delete a note by ID (requires confirm: true)
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)
Tool Description
list_scoring_rules List all scoring rules
create_scoring_rule Create a scoring rule; the expression reads fields, tags (has_tag), custom attributes (attr) and dates, and an unknown name is refused
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
Tool Description
list_webhooks List all webhook subscriptions
create_webhook Create a new webhook subscription
delete_webhook Delete a webhook subscription (requires confirm: true)
Tool Description
list_api_keys List all API keys for your account
delete_api_key Revoke an API key (requires confirm: true)

Create keys in the dashboard API Keys page. Keys are displayed only once; the MCP server cannot create or retrieve an existing raw key. Replace YOUR_API_KEY in configuration examples with the key you saved.

Tool Description
get_stats Get aggregate account statistics
list_categories List all distinct lead categories
list_cities List all distinct cities
list_statuses List the workspace’s lead statuses in order, with lead counts and values outside the list

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

Section titled “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.

list_leads accepts sort_by for the field name and sort_order for direction (ASC or DESC). The API keeps a stable order using creation time and lead ID to break ties. Keep the same search, filters, and sorting when requesting another page.

List leads sorted by score descending

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

search matches part of the lead name and combines with every entry in filters. Filters use logic.operator.field.value, for example:

{
"search": "Atelier",
"filters": ["and.eq.city.Lyon", "and.gte.score.80"],
"sort_by": "score",
"sort_order": "DESC",
"limit": 2
}

On text fields, including text attributes (attr:<name>), eq and neq are case-insensitive and treat %, _, and \ as literal characters. For example, and.eq.city.lyon finds Lyon, while and.eq.city.Ly% does not; neq excludes the same matches. On numeric fields (rating and score), equality remains numeric. contains keeps its current case-insensitive substring matching with SQL wildcards (% and _).

The default limit is 50. Values above 100 are capped at 100; zero or negative values use the default. Each response contains data.leads with only id, name, city, score, and status, plus count, has_more, and an optional next_cursor inside data. Pass next_cursor as cursor on the next call. Use get_lead for the full record. list_leads does not support format or unpaginated exports.

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

Follow the guide for your AI client:

save_leads is available on https://mcp.klozeo.com/v1/mcp only; the ChatGPT endpoint /openai/v1/mcp does not list it and refuses it. It saves 1–50 leads the user gives the assistant, for example contacts pasted into the conversation, in one call. It needs leads:write and an owner, admin or editor role; members of a Free workspace and viewers are refused.

  • Each lead accepts only name (required), email, phone, website, city, country, source, category, tags and do_not_contact (true only). Any other field, a null value or a wrong type refuses the whole call before anything is saved. Set a status afterwards with update_lead.
  • A lead with the same email, or the same phone and a similar name, updates the existing lead instead of creating one. Only non-empty fields update existing values, and the existing name is kept. Tags are added, never replaced. Locked fields are kept. do_not_contact can be set but is never cleared. SIREN and source_id cannot be sent, so they never match. A lead with the same name and city as an existing one is still created, and flagged as a possible duplicate of it. So is a lead with the same phone whose name is not similar enough to merge, for example “Boulangerie Martin SARL” next to “Boulangerie Martin”: without an email or SIREN, Klozeo cannot tell they are the same company, so you decide.
  • The result lists, for each lead in order, its outcome (created, merged, potential_duplicate or rejected), the lead ID, the ID of the existing lead a possible duplicate resembles (potential_duplicate_id), the names of the fields a merge changed or skipped because they are locked, and an error code with its help text for a rejected lead. It never repeats contact details. A rejected lead does not stop the others: an empty name, an invalid website, a field that is too long, more than 20 tags or a tag that is empty or over 64 characters, or the plan’s lead limit (merges still work at the limit). Tags are stored exactly as sent, commas and quotes included.
  • idempotency_key (1–200 characters) is required. Reusing it with the same leads within 30 days returns the original result with replayed: true and saves nothing again; a lead deleted since is reported, never recreated. The same key with different leads returns 409. Retry rejected leads with a new key.
  • Saves fire the configured leads.created and leads.updated webhooks, once per call. The receipt that makes retries safe keeps the connection’s workspace, member and endpoint, the lead IDs, outcomes and a fingerprint of the input, never contact values or conversation text, and is deleted after 30 days.

save_leads declares readOnlyHint: false, destructiveHint: true, openWorldHint: true and idempotentHint: true.

When the workspace has no leads at all, list_leads and get_stats on the Claude endpoint return a next_step string next to data: for an owner or editor, an invitation to paste contacts to save; for a viewer or a member of a Free workspace, a note that access is read-only and the workspace owner adds leads. A search that matches nothing in a workspace that has leads returns no next_step. The ChatGPT endpoint never returns next_step.

An assistant connection reaches the workspaces chosen when it was authorized. On https://mcp.klozeo.com/v1/mcp (and /mcp with an OAuth token):

  • list_workspaces returns the connection’s workspaces: id, name (the label shown on the consent screen) and role, the role the connection acts with there. The role is checked live: it is the lower of the role you approved and your current one, so a member of a Free workspace is listed as viewer. It needs leads:read.
  • Every other tool accepts an optional workspace_id, an id from list_workspaces. With one workspace, a call without it acts there, exactly as before, and results are unchanged.
  • With several workspaces, a call without workspace_id fails with WORKSPACE_REQUIRED and tells the assistant to call list_workspaces and pass workspace_id. Klozeo never remembers a current workspace between calls.
  • A workspace_id outside the connection’s workspaces fails with RESOURCE_NOT_FOUND, whether it is unknown or belongs to another account.
  • With several workspaces, each successful result adds workspace (id and name) next to data: the workspace the call acted in.
  • Your role is checked in the workspace each call names: a write in a workspace where you are a viewer is refused even if you can write in another.

The ChatGPT endpoint /openai/v1/mcp and classic API keys keep one workspace and have neither list_workspaces nor workspace_id.

The OpenAI resource /openai/v1/mcp uses a separate OAuth connection. Its first consent grants leads:read. Requesting leads:write later requires an additional consent screen, remembered for that OAuth client and the approved scopes. Local callbacks always show the screen. Access tokens last 8 hours. Clients registered for the refresh_token grant receive a refresh token valid for 6 months after each rotation; clients must replace both tokens together and never retry a consumed refresh token. Reusing one revokes that token family and requires reconnecting, even when the replay names a different registered OAuth client.

After consent is invalidated or removed, authorization starts again with read access, even if a previous connection still exists. Write access requires a new explicit step-up. Visiting an authorization link with another registered callback shows a read consent screen without removing the agreement for the original callback.

Open Dashboard → MCP → Connected applications to revoke a connection. The workspace owner and admins see every connection to the selected workspace: the member, the application, the member’s role there and the last use. They can revoke any of them. This removes only this workspace from the connection, which keeps its other workspaces and its tokens; a connection left with none is revoked, with its access and refresh tokens. Editors and viewers see only the connections they made, with the workspaces each reaches and their role in each; revoking one disconnects all of them and invalidates its tokens. A password change or removing a passkey invalidates them too. In a Free workspace, members are viewers. A missing or expired token returns 401. Missing scopes return 403 insufficient_scope; role restrictions return 403 without requesting a scope upgrade. An active ban on either the user or the workspace owner blocks access; an expired temporary ban does not. Team access is restricted to the workspace with an active membership.

Dashboard API keys keep their behavior on /mcp. OAuth tokens cannot be used as REST API keys. The nine-tool OpenAI catalogue supports the three safe writes after explicit write consent; the neutral endpoint adds save_leads, list_workspaces and list_statuses.

The classic endpoint’s 401 responses point to /.well-known/oauth-protected-resource/mcp in WWW-Authenticate, with error="invalid_token" when credentials were presented. Invalid Basic credentials and tokens in the URL receive the same discovery challenge, without revealing whether a key exists.

When connecting from ChatGPT without an account, you can create one if sign-ups are open. Verify your email using the confirmation message to return to the Klozeo consent screen. Your first connection starts with read-only access, even if the application requests write access. During a sign-up pause, sign in with an existing account or join the waitlist from the login page.

An authorization request expires 10 minutes after it starts, including time spent creating an account and verifying your email. If it expires, your verified account remains active: return to ChatGPT and connect Klozeo again to start a new authorization request.

Claude hosted connector: stable OAuth identity

Section titled “Claude hosted connector: stable OAuth identity”

On the OAuth endpoint https://mcp.klozeo.com/v1/mcp, choose Use Claude’s published identity when adding a custom connector in Claude. Klozeo supports Claude’s Client ID Metadata Document (CIMD) at https://claude.ai/oauth/mcp-oauth-client-metadata. The consent screen shows the client identity host and name, and the callback host. The first authorization is read-only; writing requires a separate explicit consent, remembered for that client and workspace under the normal revocation rules.

ChatGPT’s published identity, https://chatgpt.com/oauth/client.json, is also accepted, so a ChatGPT app created with the default OAuth settings connects without dynamic registration. Any other client that publishes an HTTPS Client ID Metadata Document (Claude Code, VS Code and other MCP clients) is accepted the same way. A local callback on localhost or 127.0.0.1 may use any port, as desktop and command-line clients pick one when they start. Dynamic registration remains available.

For an HTTPS client metadata identity (CIMD), Klozeo shows the metadata host separately from the app name. Other registered app names are self-declared and marked unverified; always check the callback host before granting access. CIMD authorization always asks for confirmation, including when write permission was previously granted. A remembered write grant can still offer write access on that screen. Existing dynamically registered clients keep their remembered consent behavior.

If the identity provider’s metadata is temporarily unavailable, Klozeo can use its last validated copy for up to 24 hours after cache expiry. Without one, the OAuth endpoint responds with HTTP 503 and temporarily_unavailable; retry later. An authorization code is preserved when metadata fetching fails transiently.

The ChatGPT and neutral connections return the same {data: ...} object in text and structured content. Lead pages contain at most 100 summaries and can be smaller to fit the response size budget; always use next_cursor to continue. Notes retain their creation date and cursor; long content has content_truncated: true. Categories and cities return at most 200 complete values within the response size budget. count is the returned count, total the available count, and truncated indicates omitted values. These two tools have no pagination parameter. Lead details include the workspace’s address, state, postal code and description. Successful writes return the affected ID even if response validation encounters a problem after the write; do not retry a successful write to repair its response.