Connect AI tools to Descovo via MCP

Descovo exposes its full API surface through an MCP (Model Context Protocol) server, so AI tools like Claude Desktop and Cursor can discover endpoints, inspect schemas, and execute operations — all without you writing integration code by hand. This page explains which MCP endpoint to connect to, what tools are available, how to configure your client, and how to run the most common Descovo workflows.

MCP endpoint surfaces

Descovo offers three MCP endpoint surfaces. Choose the one that matches your authentication setup.

Endpoint	Auth method	When to use
`/mcp`	API key	Default. Use for scripted or headless agent integrations.
`/mcp/v2`	API key	Full generated-tool surface. Planned for deprecation after v3 validation.
`/mcp/v3`	OAuth / SSO via Clerk	Recommended for interactive agent setups where users log in through the UI.

If you are setting up a personal AI assistant (Claude Desktop, Cursor), use /mcp/v3 for the smoothest login experience. If you are building a backend agent that runs unattended, use /mcp with an API key.

Core MCP tools

Every Descovo MCP endpoint exposes three tools.

search_endpoints

Describe what you want in plain English. Returns ranked endpoint recommendations based on your intent, with optional constraint filtering.

get_endpoint_details_full

Returns the complete input/output schema, required fields, optional filters, rate limits, and credit metadata for a specific operationId.

call_operation

Executes any Descovo operation by operationId. Pass your parameters as a structured JSON payload and receive the API response directly.

Available operationIds

Use these operationId values with call_operation. Pass them to get_endpoint_details_full first if you need the full parameter schema.

operationId	What it does
`companySearch`	Search 47M+ companies by filters (industry, size, country, keywords)
`peopleSearch`	Search 847M+ professional profiles by role, company, and location
`createAudience`	Create a new named audience for bulk enrichment
`buildAudience`	Populate an audience with matching records
`getAudienceStatus`	Poll audience build progress until status is `NORMAL`
`estimateEnrichmentCost`	Get credit cost and time estimate before triggering enrichment
`triggerEnrichment`	Start enrichment on a built audience (charges credits)
`getEnrichmentStatus`	Poll enrichment job progress
`exportCompanies`	Export company records from a completed enrichment
`exportProspects`	Export prospect/contact records from a completed enrichment
`startBatchContactEnrichment`	Start a batch job to enrich a list of contacts
`pollBatchContactEnrichment`	Poll a batch enrichment job by `taskId` and cursor

The full set of operationIds and their exact parameter shapes is available in the OpenAPI spec at /openapi.json. Always call get_endpoint_details_full before constructing complex payloads.

Set up Descovo in your AI client

Claude Desktop
Cursor

Open your Claude Desktop configuration file (claude_desktop_config.json) and add a Descovo MCP server entry.

claude_desktop_config.json

{
  "mcpServers": {
    "descovo": {
      "url": "https://api.descovo.com/mcp/v3",
      "auth": {
        "type": "oauth"
      }
    }
  }
}

If you prefer API key auth instead of OAuth, use the /mcp endpoint:

claude_desktop_config.json

{
  "mcpServers": {
    "descovo": {
      "url": "https://api.descovo.com/mcp",
      "headers": {
        "x-api-key": "sk_live_xxx"
      }
    }
  }
}

Restart Claude Desktop after saving the file. You should see Descovo tools appear in the tool list.

In Cursor, go to Settings → MCP and add a new server entry.

cursor mcp config

{
  "mcpServers": {
    "descovo": {
      "url": "https://api.descovo.com/mcp",
      "headers": {
        "x-api-key": "sk_live_xxx"
      }
    }
  }
}

After saving, open a Composer session and type @descovo or ask the agent to use Descovo tools. Cursor will automatically route relevant requests through MCP.

Recommended workflow

Follow this sequence at the start of every Descovo MCP session. It prevents wrong-tool calls and avoids invalid requests.

Read /llms.txt

Fetch /llms.txt from the Descovo root. It contains global rules about credits, confirmation requirements, async polling intervals, and an overview of the audience workflow. Load these rules before making any API calls.

Discover the right endpoint

Call search_endpoints with a plain-English description of your intent:

{
  "query": "find companies in the US in the AI industry"
}

The tool returns ranked operationId recommendations. If you need to choose between similar operations, see Choose the right API.

Inspect the schema

Call get_endpoint_details_full with the operationId you selected. Review the required fields, optional parameters, and any credit costs before building your payload.

Execute with call_operation

Construct and send your call_operation payload. Check chargeInfo in the response and surface any costs to the user before proceeding to the next step.

Recommended workflows

A. Audience-based enrichment (recommended for scale)

The audience workflow keeps large result sets in Descovo’s database instead of your context window, provides clean async progress reporting, and makes costs transparent before charging.

Create an audience

Call createAudience. Store the audienceId from the response — you will pass it to every subsequent step.

Set search parameters

Call updateAudienceSearchParams with your filters (industry, country, headcount, keywords, etc.).

Build the audience

Call buildAudience. This populates the audience with matching records asynchronously.

Poll until ready

Call getAudienceStatus every 30 seconds until the status field returns NORMAL.

Estimate enrichment cost

Call estimateEnrichmentCost. Show the returned totalCredits and timeEstimate to the user and ask for explicit confirmation before continuing.

Trigger enrichment

Only after the user confirms, call triggerEnrichment. This charges credits and starts the enrichment job.

Poll enrichment progress

Call getEnrichmentStatus every 30 seconds until the job completes.

Export results

Call exportCompanies for company records or exportProspects for contact records, depending on what the user needs.

B. Direct search + light enrichment

Use this workflow for small, ad-hoc lookups.

Call companySearch or peopleSearch to fetch a small page (25–50 results).
Summarize the key fields in the conversation.
If the user wants contact details for a few specific people, call a sync contact-enrich endpoint per person.
If the user wants to scale up beyond a handful of records, propose creating an audience (workflow A) or a batch contact enrichment job (workflow C).

C. Batch contact enrichment

Use this workflow when you have a known list of profiles and need contact details in bulk.

Call startBatchContactEnrichment to submit the list.
Call pollBatchContactEnrichment with the returned taskId and a cursor to check progress.
Use overallStats and pageResults from the poll response to show progress and surface results to the user.

Example call_operation payload

This example runs a company search filtered to AI companies in the United States.

{
  "operationId": "companySearch",
  "params": {
    "body": {
      "apiKey": "sk_live_xxx",
      "searchParams": {
        "keywords": ["artificial intelligence"],
        "headquartersCountryCode": ["US"]
      },
      "pageSize": 25,
      "cursor": null,
      "companyExclusionListIDs": []
    }
  }
}

Pass apiKey in the request body for POST, PATCH, and PUT operations. For GET and DELETE operations, pass it as a query parameter. Check the schema returned by get_endpoint_details_full to confirm placement.

Cost and safety rules

Always follow these rules when using MCP tools that touch credits or trigger async jobs.

Check credits first. Before any large job, retrieve the current credit balance using GET /v1/credits?apiKey=xxx (or the equivalent MCP operation) and report it to the user.
Estimate before charging. For audience enrichment, always call estimateEnrichmentCost before calling triggerEnrichment. Never skip this step.
Get explicit confirmation. State the estimated credit cost and time to the user and ask: “This will cost up to X credits and take about Y. Proceed?” Do not proceed until the user confirms.
Poll, do not spam. Respect documented poll intervals (every 30 seconds). Avoid tight loops that would abuse rate limits.

Get Started

Guides

AI & MCP

Connect AI tools to Descovo via MCP

MCP endpoint surfaces

Core MCP tools

search_endpoints

get_endpoint_details_full

call_operation

Available operationIds

Set up Descovo in your AI client

Recommended workflow

Recommended workflows

A. Audience-based enrichment (recommended for scale)

B. Direct search + light enrichment

C. Batch contact enrichment

Example call_operation payload

Cost and safety rules

Get Started

Guides

AI & MCP

Documentation Index

​MCP endpoint surfaces

​Core MCP tools

search_endpoints

get_endpoint_details_full

call_operation

​Available operationIds

​Set up Descovo in your AI client

​Recommended workflow

​Recommended workflows

​A. Audience-based enrichment (recommended for scale)

​B. Direct search + light enrichment

​C. Batch contact enrichment

​Example call_operation payload

​Cost and safety rules

MCP endpoint surfaces

Core MCP tools

Available operationIds

Set up Descovo in your AI client

Recommended workflow

Recommended workflows

A. Audience-based enrichment (recommended for scale)

B. Direct search + light enrichment

C. Batch contact enrichment

Example call_operation payload

Cost and safety rules