Skip to main content
The lev8 MCP server exposes Entity Search, Contact Search, and credit balance as typed tools for AI clients. It is a local protocol adapter: every tool call uses the public lev8 HTTP API and keeps the same API-key authentication, concurrency limits, idempotency rules, and credit billing.
The current release supports local stdio transport only. It does not provide a hosted MCP URL or OAuth flow. You need a local build of the MCP executable; your lev8 contact can provide the executable or build access.

​
Prerequisites

  • A local lev8 MCP executable.
  • An active API key with the scopes required by the tools you call.
  • The API base URL https://app.lev8.com.
When building from an authorized source checkout, the server entry point is ./cmd/mcp:

​
Configure your MCP client

The server reads its API address and Token from the process environment. The Token is not a tool argument and is never exposed in tool schemas.
Restart the AI client after changing its MCP configuration, then confirm that it lists the five tools below.
Store the complete Token in a local secrets mechanism when your MCP client supports one. Do not commit it to a repository, share the configuration file, pass it as a tool argument, or place it in prompts.

​
Tools

entity_search_create defaults limit to 20. entity_search_fetch defaults pts to 0 and num to 5, with a maximum num of 500.

​
Entity Search workflow

1

Create

Call entity_search_create and save leads_search_id from the structured result.
2

Monitor

Call entity_search_status until the state becomes done or error. You can begin fetching as soon as ready_count is positive.
3

Fetch

Call entity_search_fetch. Advance pts by the returned count until all ready_count results have been read.
A terminal error can still have ready results. Fetch them before closing the task.

​
Idempotency and retries

The MCP server generates a cryptographically random key when entity_search_create or contact_search omits idempotency_key. Supply your own stable key when an Agent workflow may be resumed or replayed. The first release does not automatically retry paid POST operations. If a tool call ends without a known response, resolve or replay the original logical request with the same key rather than starting a second request with a new key.

​
Security boundaries

  • The server connects only to the base URL fixed at process startup; tool inputs cannot select another URL.
  • HTTP redirects are not followed.
  • The adapter does not connect directly to lev8 databases, queues, or caches.
  • API-key validation, billing, task ownership, and concurrency enforcement remain server-side.
  • The adapter does not offer Token creation, listing, or revocation tools.
  • Objective text, search results, contact details, Tokens, and complete HTTP bodies are not written to MCP logs.
  • HTTP and upstream errors are mapped to stable tool errors without exposing response bodies or internal request details.