Descovo

// DOCUMENTATION

Descovo MCP Documentation

Descovo is a B2B data API and hosted MCP server that gives AI agents access to 700M+ professional profiles. Search costs 0 credits. Each reveal attempt costs 1 credit, including not-found results. When available, work email and direct phone are returned together under that credit. No seats, no minimums, no contracts.

New to MCP? Read our guide to the Model Context Protocol.

Get an API keyQuickstart

// QUICK START

Quick Start: Connect the B2B Data API in Three Steps

01

Create an API key

Sign up at descovo.com (no credit card required). Go to your dashboard and generate an API key. It starts with sk_live_.

02

Add to your MCP client

Use the Claude Code command, Cursor config, or HTTP details below. Replace the placeholder with your API key. The generic path requires a client that supports static custom headers.

03

Ask your agent

Tell your agent what you need: "Find VPs of Engineering at fintech companies in NYC with available work email fields." The agent calls Descovo and returns structured results.

// CLIENT SETUP

Connect your MCP client

Descovo uses Streamable HTTP transport. No local installation, no Docker, no npm package. Just a URL and your API key.

Terminal
claude mcp add --transport http \
  --header "x-api-key: sk_live_••••••••••••••••" \
  descovo https://mcp.descovo.com/mcp

Connection details

Endpoint: https://mcp.descovo.com/mcp

Transport: Streamable HTTP

Auth header: x-api-key: sk_live_...

// MCP TOOLS

MCP Server Tools and API Coverage

The MCP server exposes five tools. Your AI agent discovers them automatically and decides which to call based on your prompt.

search_endpoints

Ask for ranked operation candidates from a natural-language intent. Treat the ranking as a suggestion, then verify the chosen operation with its full endpoint details.

When to use: You want candidate operations before confirming the exact operation ID and schema.

list_all_endpoints

Browse every available API operation with a short summary of each.

When to use: You want to explore everything Descovo can do.

list_tag_packs

Browse operations grouped by category (people, companies, jobs, credits, etc.).

When to use: You want to see operations organized by domain.

get_endpoint_details_full

Get the full JSON schema for a specific operation, including all request parameters and response fields.

When to use: You found the operation you need and want exact parameter details before calling it.

call_operation

Execute an allowed operation. Pass the operation ID and a params object with body, path, or query data. The MCP server handles authentication and routing.

When to use: You're ready to run a search, reveal contacts, or check credits.

In practice, most workflows follow this pattern: search_endpoints or list_tag_packs to find the right operation, then get_endpoint_details_full to get the schema, then call_operation to execute it. Your agent handles this automatically.

// SEARCH OPERATIONS

People Search API — 0 Credits

All search operations cost zero credits. Run as many searches as you need to find the right people before committing a credit on a reveal. Count variants (e.g. peopleSearchCount) are also free.

peopleSearch

People Search

Search 700M+ professionals by name, title, seniority, current company, industry, location, and profile keywords.

companySearch

Company Search

Search companies by name, domain, industry, headcount, location, and technology stack.

paginatedCombinedSearch

Combined Search

Search people and companies in a single call with unified filters.

jobPostingSearch

Job Search

Search open job postings by title, company, location, and keywords.

People search filters

The peopleSearch operation is the most powerful. Here are the available filters:

fuzzyName

Filter by a full or partial person name with an anyOf array of {name: "..."} objects.

jobTitleV3

Filter by function and seniority. The MCP-normalized shape uses an include array containing {type: "functional", seniority: [...], keywords: [...]}. Seniority values: senior, staff, principal, lead, manager, head, director, vp, svp, c-suite.

industry

Filter by the supported industry enum with anyOf/noneOf arrays. Examples include "Financial Services", "Software Development", and "Banking".

location

Filter by geography. Uses include/exclude arrays of city, state, or country strings.

currentCompanies

Top-level body field for current-employer narrowing. Pass supported company identifiers; it does not belong inside searchParams.

keywordsV2

Structured Boolean keyword search across profiles using clauses, terms, and operators.

jobStatus

Filter by employment status (e.g. "currently-employed").

pageSize

Top-level body field that controls the number of results returned; it does not belong inside searchParams.

Company headcount is not a direct peopleSearch filter. Use employeeCountV2 in a company search, or combine company and profile criteria with paginatedCombinedSearch.

Example queries

These are the MCP tool call payloads your agent constructs automatically when you ask in natural language. Shown here for reference. See real-world examples in our AI sales prospecting guide.

// VPs of Engineering at fintech companies

call_operation
// Find VPs of Engineering at fintech companies
{
  "tool": "call_operation",
  "arguments": {
    "operationId": "peopleSearch",
    "params": {
      "body": {
        "searchParams": {
          "jobTitleV3": {
            "anyOf": [{
              "type": "functional",
              "seniority": ["vp"],
              "keywords": ["engineering"]
            }]
          },
          "industry": { "anyOf": ["Financial Services"] },
          "country3LetterCode": { "anyOf": ["USA"] },
          "jobStatus": { "status": "currently-employed" }
        },
        "pageSize": 25
      }
    }
  }
}

// Sales directors in New York

call_operation
// Find sales directors in New York
{
  "tool": "call_operation",
  "arguments": {
    "operationId": "peopleSearch",
    "params": {
      "body": {
        "searchParams": {
          "jobTitleV3": {
            "include": [{
              "type": "functional",
              "seniority": ["director"],
              "keywords": ["sales"]
            }]
          },
          "location": { "include": ["New York"] },
          "jobStatus": { "status": "currently-employed" }
        },
        "pageSize": 25
      }
    }
  }
}

// CTOs at companies with 50-200 employees

call_operation
// Find CTOs at companies with 50-200 employees
{
  "tool": "call_operation",
  "arguments": {
    "operationId": "paginatedCombinedSearch",
    "params": {
      "body": {
        "companyConfig": {
          "searchParams": {
            "employeeCountV2": {
              "lowerBoundExclusive": 49,
              "upperBoundInclusive": 200
            }
          },
          "pageSize": 25
        },
        "profileConfig": {
          "searchParams": {
            "jobTitleV3": {
              "anyOf": [{
                "type": "functional",
                "seniority": ["c-suite"],
                "keywords": ["technology"]
              }]
            }
          },
          "pageSize": 25
        }
      }
    }
  }
}

// Keyword search across profiles

call_operation
// Search by keywords across profiles
{
  "tool": "call_operation",
  "arguments": {
    "operationId": "peopleSearch",
    "params": {
      "body": {
        "searchParams": {
          "keywordsV2": {
            "operator": "AND",
            "clauses": [{
              "operator": "OR",
              "terms": ["machine learning", "infrastructure"],
              "negate": false
            }]
          },
          "jobTitleV3": {
            "include": [{
              "type": "functional",
              "seniority": ["senior", "manager", "director"]
            }]
          }
        },
        "pageSize": 25
      }
    }
  }
}

// Company search by domain

call_operation
// Search companies by domain
{
  "tool": "call_operation",
  "arguments": {
    "operationId": "companySearch",
    "params": {
      "body": {
        "searchParams": {
          "domains": ["ramp.com"]
        },
        "pageSize": 25
      }
    }
  }
}

// REVEAL OPERATIONS

Reveal available contact fields

Each reveal attempt costs 1 credit, including not-found results. When available, work email and direct phone are returned together under that credit.

Lite uses a lower-yield lookup. Standard balances speed and coverage. Turbo prioritizes speed, while Exhaustive trades latency for the broadest available provider coverage.

liteContactReveal

Lite Reveal

Lower-yield contact lookup for workflows that prefer the lighter operation.

syncQuickContactReveal

Standard Reveal

Balanced speed and coverage. Queries providers at request time and is the default choice for most use cases.

syncTurboContactEnrichment

Turbo Reveal

Queries providers at request time with optimized parallelism. Use when you want broader coverage without waiting for Exhaustive.

triggerExhaustiveContactEnrichment

Exhaustive Reveal

Queries providers at request time with the broadest available coverage. It is slower and suited to hard-to-find contacts.

// Example: reveal a contact

call_operation
// Reveal a contact's email and phone
{
  "tool": "call_operation",
  "arguments": {
    "operationId": "syncQuickContactReveal",
    "params": {
      "body": {
        "linkedinUrl": "https://www.linkedin.com/in/example-profile",
        "enrichmentType": {
          "getWorkEmails": true,
          "getPersonalEmails": false,
          "getPhoneNumbers": true
        },
        "validateEmails": true
      }
    }
  }
}

What if no data is found?

Each reveal attempt costs 1 credit, including not-found results. A not-found result means no available contact fields were returned for that attempt. Use free search to narrow the people you want before revealing.

// CREDITS

Credit System and Usage-Based Pricing

Search costs 0 credits. Each reveal attempt costs 1 credit, including not-found results. When available, work email and direct phone are returned together under that credit.

Free (0 credits)

  • +peopleSearch / peopleSearchCount
  • +companySearch / companyCount
  • +paginatedCombinedSearch / combinedSearchCount
  • +jobPostingSearch / jobPostingSearchCount
  • +getOrgCredits

1 credit per reveal attempt

  • +liteContactReveal
  • +syncQuickContactReveal
  • +syncTurboContactEnrichment
  • +triggerExhaustiveContactEnrichment

Check your balance

Ask your agent “How many credits do I have left?” or call getOrgCredits directly:

call_operation
// Check your remaining credit balance
{
  "tool": "call_operation",
  "arguments": {
    "operationId": "getOrgCredits",
    "params": {}
  }
}

Pricing tiers

PlanStandard priceCredits
Free$0500/month
Starter$99/month5,000/month
Pro$249/month15,000/month
Growth$699/month50,000/month
Enterprise$1,799/month150,000/month

Search costs 0 credits on all plans. See full pricing for current offers.

// AUTHENTICATION

API key authentication

Getting your API key

  1. Create an account at descovo.com (free, no card required).
  2. Go to your dashboard and click “Create API Key”.
  3. Copy the key. It starts with sk_live_ and is shown only once.

How auth works

Your API key is passed in the x-api-key HTTP header. When you configure the MCP server in your client, the header is set once in your config file and automatically included with every request. You never need to pass it manually in your prompts.

Security best practices

  • Never share your API key publicly or commit it to version control.
  • Use environment variables or your OS keychain when possible.
  • Rotate your key immediately if you suspect it has been compromised. Generate a new key from your dashboard.
  • Each key is scoped to your organization. All team members can share one key, or you can create separate keys per environment.

// BEST PRACTICES

Best Practices for B2B Data Queries

SEARCH FIRST

Search before revealing

Search costs 0 credits. Use it to narrow the people who match your criteria before spending a credit on each reveal attempt.

FILTERS

Use specific filters

The more specific your filters (seniority + function + industry + location), the better your results. Broad searches return more noise. Stack filters to narrow down to exactly the people you need.

CREDITS

Check balance before bulk

Before running a batch of reveals, check your credit balance with getOrgCredits. This prevents your workflow from failing mid-batch when credits run out.

QUICK VS EXHAUSTIVE

Choose the right reveal

Lite uses a lower-yield lookup. Standard balances speed and coverage. Turbo prioritizes speed, while Exhaustive trades latency for the broadest available provider coverage. Each mode costs 1 credit per attempt, including not-found results.

PAGINATION

Use limit and pageSize

Set a reasonable limit (25-50) on searches. Large result sets take longer and you probably only need the top matches. Paginate if you need more.

AGENT TIPS

Let your agent figure it out

You don't need to know the exact parameter names. Describe what you want in natural language and your agent will construct the right call. The MCP tools guide the agent automatically. For inspiration, explore 5 agentic AI workflows you can build today.

// FAQ

MCP Server FAQ

For the full list, see the FAQ page. Here are the most common questions about the MCP server:

Do I need to install anything?+

No. Descovo runs as a hosted MCP server. Configure your MCP client to connect to https://mcp.descovo.com/mcp with your API key in the x-api-key header. No npm package, no Docker, no local process.

Can I use Descovo without MCP, via a regular API?+

Yes. Every operation available through MCP is also available as a REST API endpoint. The current REST contract accepts your sk_live_ key as apiKey: in the query string for GET requests and in the JSON body for POST requests. The x-api-key header is used by the hosted MCP connection.

What MCP clients are supported?+

Descovo currently supports Claude Code, Cursor, and custom MCP clients that accept Streamable HTTP connections with a static x-api-key header. Claude.ai and Claude Desktop custom remote connectors require OAuth, which Descovo does not yet expose.

What happens if a reveal finds no data?+

Each reveal attempt costs 1 credit, including not-found results. A not-found result means no available contact fields were returned for that attempt.

Is there a rate limit?+

Yes, but limits are generous for normal usage. Higher-tier plans get higher rate limits. If you hit a limit, the server returns a standard 429 response; retry after the indicated delay.

Ready to connect?

Get your API key and start searching in under a minute. Free to start, no credit card required. Learn more about the platform overview or browse solutions built on Descovo.

Get started freeSee pricing