MCP Developer Reference

Build agents and applications that search Crunchbase, retrieve profiles, answer questions, and save results. This reference describes the MCP tools, their inputs, and how to read their responses.

All tools are served from https://mcp.crunchbase.com over Streamable HTTP. Every call is authenticated and runs as the signed-in user; see Connecting AI Tools for authentication.

Choose a tool

How the tools fit together

The tools form a pipeline that most workflows follow in some order:

1. Understand the schema with cb_reference, or explore what's answerable with cb_expert_query_domain.
2. Resolve names to identifiers with cb_entity_autocomplete or cb_expert_resolve_entity. Crunchbase tools operate on identifiers (UUIDs and permalinks), not display names.
3. Find entities with cb_expert_build_search (natural language) or cb_search_query (explicit criteria), or answer a question directly with cb_expert_query_answer.
4. Retrieve full profiles for the entities that matter with cb_entity_get.
5. Persist results to Crunchbase lists with the cb_list_* tools.

Use Expert tools to express a question in natural language. Use structured tools to control fields, filters, and pagination. For repeatable workflows, compile a search with Expert, review the criteria, then run it through cb_search_query. Results can change as Crunchbase data is updated.

Data-token metering

Read metering from the raw MCP tool result, outside the tool's business payload:

const usage = toolResult._meta?.["cb/data_tokens"];
const consumed = usage?.consumed;   // actual deduction, when confirmed
const exhausted = usage?.exhausted; // inspect the result/error separately

consumed is the number of Crunchbase data tokens actually deducted for this invocation. It is not a remaining balance or an AI-provider token count. It already includes charged nested fetches, such as a returned profile or preview. Add it once per actual invocation; a retry is a new invocation.

A known consumed: 0 differs from an absent value. Missing metadata or a missing consumed amount means your client cannot establish the deduction from this result; do not substitute zero. Some adapters omit _meta when they expose only structuredContent. Preserve the raw result through your connector.

A successful response can report exhausted: true and still contain usable data. Keep that result, then stop further affected calls. An allowance-exhaustion denial also reports exhaustion but withholds data, so inspect isError and the payload's error as well.

See Data-Token Metering for the complete metadata contract, all-tool charging table, allowance fields, workflow ledger example, and allowance errors.

Read tool responses

Keep the raw MCP result separate from the tool's data payload:

• content contains the human-readable summary.
• structuredContent contains the tool's data and payload-level error.
• isError reports a tool failure without usable data. A response with usable partial data can have a payload error while isError remains false.
• _meta contains data-token usage when supplied. See Data-Token Metering.

Do not parse the summary text to reconstruct rows, identifiers, counts, or usage. Check transport and protocol errors first, then isError and structuredContent.error. Preserve error fields that your saved schema does not recognize.

Expert answer rows

columns names the cells in each row by position: rows[i][j] corresponds to columns[j]. Cells can contain scalar values or structured entity identities. Do not assume every cell is a string or a company name.

Illustrative structuredContent, abbreviated to the result fields:

{
  "columns": ["company", "funding_round_count"],
  "rows": [
    [
      {
        "value": "Crunchbase",
        "uuid": "43ac6c2f-65ec-5b40-89d6-ab9d4c4988ef",
        "entity_def_id": "organization",
        "permalink": "crunchbase",
        "url": "https://www.crunchbase.com/organization/crunchbase"
      },
      5
    ]
  ],
  "row_count": 1,
  "truncated": false
}

This abbreviated example illustrates the response format. Values can change as Crunchbase data is updated. Use the identity object's value for display, uuid and entity_def_id for follow-up calls, and url when supplied for a source link. Preserve other JSON cell values without forcing them into strings. row_count is the number of rows returned, not the total size of the underlying dataset.

Also inspect resolved_references, answered_question, truncated, and any feedback prompt before presenting an answer. These fields describe resolution, interpretation, partial results, and next actions.

Profile fields and cards

A profile uses labeled property arrays, rather than a flat object keyed by field ID:

{
  "entity_def_id": "organization",
  "properties": [
    { "field_id": "name", "label": "Name", "value": "Crunchbase" }
  ],
  "cards": []
}

Find a field by field_id and read its value; do not use the translated display label as a stable key. A card can contain host-entity properties or related entities, each with its own properties. Use card_id to identify the card and has_more_entities to plan continuation. Missing fields or cards are not proof of an empty relationship.

Structured search results use a different shape: entities contains records with the requested field IDs, plus profile URLs when supplied. Do not reuse a profile-property parser for a search result. See Reliability, Errors, and Pagination for validation and traversal rules.

Expert tools

cb_expert_query_answer

Answers a natural-language question using live Crunchbase data. Expert interprets the question, constructs and executes the necessary queries, and returns an answer with supporting results.

Use it for exploratory and analytical questions where you want an answer rather than a result set to process: "How many Series B rounds were announced between 2025-01-01 and 2025-12-31?" or "Who are the most active seed investors in climate tech?"

Keep the returned request_id: it's required to submit feedback via cb_expert_submit_feedback, and negative feedback can trigger the service to rewrite the query and return corrected results.

The required input is question (string). Use one self-contained question with absolute dates. Check error before consuming columns, rows, and row_count. If follow_up_action="collect_feedback", ask the user for their reaction before submitting feedback; do not invent sentiment. Respect truncated; surface answered_question when the answer was narrowed. There is no explicit row-limit, projection, deduplication, or continuation input. truncated=false reports no row-limit truncation; it does not certify exhaustive coverage or correct interpretation.

cb_expert_build_search

Translates a natural-language description of the entities you want into a compiled, structured Crunchbase search, handling field resolution, operator selection, and value formatting automatically.

Use it when you know what you're looking for but not the schema: "US-headquartered healthcare companies that raised a seed round between 2026-07-16 and 2026-10-14 inclusive." A productive pattern for repeatable workflows is to use this tool to discover a compiled search, review its scope, then replay its complete query through cb_search_query. Preserve nested subqueries rather than flattening them into predicates. Reusing a query does not freeze the underlying data.

Inputs are search_query (required string) and preview_limit (optional positive integer; omit or pass null to skip previews). The allowed maximum is caller-specific. Output includes the compiled search, title, url, and optional results. Preview rows may cover only part of the match set; do not assume they are exhaustive. Inspect the compiled scope, then preserve its query, collection_id, and selected fields when continuing through cb_search_query.

cb_expert_query_domain

Answers meta-questions about the shape of the Crunchbase data domain: what entities, fields, and relationships exist, and whether a draft question is answerable. It does not query actual records. It consumes data tokens for processing; guidance responses are not free. Returned guidance values do not add a separate response-value charge.

discover returns a domain map, suggested analytical paths, and example questions. assess returns diagnostics on answerability, clarifications that would improve the question, and recommended reformulations. Prefer cb_reference when you already know which entity or field area to inspect; it returns precise structured answers without an Expert round trip.

cb_expert_resolve_entity

Disambiguates an entity name against the Crunchbase catalog and resolves it to a canonical entity. Returns a single match when confident, otherwise a ranked candidate list.

Use domains for company resolution, not person resolution. A company domain can select the company or produce no candidates when combined with a person collection; do not rely on an explicit error. A personal profile URL can resolve the website owner rather than the person. For people, use the name, an explicit person collection, and relevant context.

This is the right tool for ambiguous inputs ("Scale", "Beacon", "Marc at Andreessen Horowitz"). For simple identifier lookup where ambiguity is unlikely, cb_entity_autocomplete is lighter.

Read resolution and profile outcomes separately. Inspect the outer error first, then disambiguation.result_type:

When automatic profile retrieval is enabled, inspect the separate entity payload and its nested error. Resolution can succeed while the profile fetch fails; an absent outer error does not certify the embedded profile. Passing cb_entity_get: null disables the profile, so entity being absent is expected in that case.

To continue an embedded relationship card, make a separate cb_entity_get call. Use the matched host entity's identifier and entity_def_id, the selected card_id, and the last related entity's UUID as after_id. The embedded options do not accept an after_id cursor.

cb_expert_submit_feedback

Records user feedback on a previous cb_expert_query_answer result.

Negative feedback may trigger Expert to rewrite the query; when it does, the corrected result set is returned in the feedback response. In agent workflows, use this tool to submit the user’s actual reaction; a rewrite or improved answer is not guaranteed.

cb_expert_submit_search_feedback

Records the user’s feedback on a previous cb_expert_build_search result. Use its request_id as subject_request_id; do not use an answer-tool request ID. Required sentiment is "positive", "neutral", or "negative"; optional feedback is up to 1,000 characters. Negative feedback may trigger a recompiled search, returned as search, title, and url.

Both feedback tools change state. Submit only the user’s actual reaction. Check error, feedback_outcome_kind, rewrite_attempted, and rewrite_succeeded when supplied: acceptance does not guarantee a successful rewrite. Outcomes include accepted, forbidden, not_actionable, original_not_found, rewrite_failed, rewrite_returned, and service_unavailable.

Structured tools

cb_reference

The schema reference for everything else. Returns Markdown documentation for a given path; call with an empty path (or "index") for the full navigable index. Every response lists the paths you can drill into next; use them verbatim rather than constructing your own. An unrecognized path returns the index and may include a closest-match hint.

The per-field path is the single most important call when constructing structured queries: it is the authoritative source for which operators a field accepts and what its values look like.

cb_entity_autocomplete

Searches Crunchbase entities by name and returns matching identifiers with short descriptions. This is how you obtain valid identifiers before calling other tools.

Beyond companies and people, use it to resolve filter values: locations (collection_ids="locations") and categories (collection_ids="categories") before using them in search predicates. See Working with identifiers.

cb_entity_get

Retrieves the full profile for one already-identified entity: fields (financials, leadership, locations, categories) plus relationship cards (funding rounds raised, investments made, employees, and so on).

Card pagination. The continuation flag can also reflect budget clipping and is not a per-card total. Scope to one card; guard against repeated cursors and empty pages. See Reliability, Errors, and Pagination for termination rules.

A true has_more_entities means completeness has not been established; it can also occur when a card exactly fills its limit and the next page is empty. Fetch the next page by calling again with card_ids set to that single card, after_id set to value.uuid from the last related entity’s properties item whose field_id is "identifier", and field_ids=[].

A single card returns at most 100 entities per request, and some cards or access levels impose lower limits that a larger budget cannot override. Use structured search or a reviewed compiled search when card limits prevent retrieving the full relationship.

Response validation. Unknown or unavailable profile fields and cards may be omitted without an error. Validate selections with cb_reference and compare requested fields/cards with the response. A missing card is not an empty relationship. Use explicit card_ids and client-side row or payload safeguards; the combined response can exceed related_entity_limit when multiple cards are included. Do not rely on out-of-range values being rejected or handled consistently.

Payload discipline. Profiles and relationship cards on well-connected entities can produce large responses. Do discovery through cb_search_query with explicit field_ids, and reserve cb_entity_get for the entities that survive screening, scoping follow-ups tightly with card_ids and field_ids=[].

cb_search_query

Executes a structured search and returns matching entities with the requested fields. Use it for explicit filters and controlled traversal. Repeated queries can return changed data; there is no snapshot-isolation guarantee.

Resolve before you filter. For every field used in a predicate or sort, call cb_reference('entities/<ed>/fields/<field_id>') first. It returns the valid operators, example predicates, enum values, and live sample data. Incorrect operators and value formats can cause failed or silently empty searches.

Validation errors. Some rejected searches return only a generic HTTP 400 message. Check each field, operator, identifier value, and query shape against its field reference. Inspect the payload's error even when the outer MCP result does not flag an error. See Reliability, Errors, and Pagination.

Result URLs. Each entity in the results carries a url field linking to its Crunchbase profile. Surface these links when presenting results; they're the user's path from an AI answer back to the source.

The following example finds Seed and Series A funding rounds announced on or after June 1, 2026 for US organizations. Each result is a funding round, not a unique company; deduplicate funded_organization_identifier.uuid if building a company list:

{
  "collection_id": "funding_rounds",
  "predicates": [
    {"field_id": "announced_on", "operator_id": "gte", "values": ["2026-06-01"]},
    {"field_id": "investment_type", "operator_id": "includes", "values": ["seed", "series_a"]},
    {"field_id": "funded_organization_location", "operator_id": "includes", "values": ["united-states"]}
  ],
  "field_ids": ["identifier", "announced_on", "investment_type", "money_raised", "funded_organization_identifier"],
  "order": [{"field_id": "announced_on", "sort": "desc"}],
  "limit": 50
}

Note the location value: "united-states", an identifier, not "United States". See the next section.

Working with identifiers

Crunchbase tools operate on identifiers: UUIDs and permalinks. Display names are for humans; identifiers are for queries. Three rules keep searches reliable:

• Never fabricate an identifier. Obtain them from cb_entity_autocomplete, cb_expert_resolve_entity, or previous results.
• Identifier-valued filter fields expect identifier values. Location fields such as location_identifiers and funded_organization_location take permalinks like united-states or united-kingdom. A display name like "United States" can return zero rows without an error. Resolve locations first with cb_entity_autocomplete(query, collection_ids="locations") and use the returned permalink. The same applies to categories (collection_ids="categories").
• When a search unexpectedly returns zero rows, loosen one filter at a time, starting with identifier-valued filters. An unresolved location or category value can cause silent empty results.

For money predicates, follow the field reference’s value format, such as numeric USD amounts (15000000, not "$15M"). Returned money values may be objects containing currency and converted amounts. Use ISO-formatted dates, such as "2026-06-01".

List tools

Lists save research in Crunchbase. Visibility and modification depend on the caller's access and the list's permissions. The tools below are free list operations; separate profile or data lookups still use tokens.

cb_list_query

Call with {} to discover lists available through the caller's list metadata. The response contains company_lists, with list_id, name, ownership/sharing fields, and identifiers_collection details such as entities_count when available.

This tool returns saved lists with an identifiers collection. Do not assume this is a catalog of every Crunchbase list type, or assume every returned list can be modified. Inspect is_owner, is_modifiable, and errors as appropriate.

cb_list_create

Creates an empty static list with an identifiers collection. Input is {"name":"My research list"}. On success, keep the returned list_id and list_name; populate the list through cb_list_add_entities.

An uncertain create response is not permission to create another list. Check existing lists before retrying.

cb_list_add_entities

Takes a list UUID in list_id and an array of entity UUIDs in entity_ids. Discover the destination through cb_list_query and use identifiers returned by data tools.

The response can include list_id, submitted_entity_ids, response_status, and error. submitted_entity_ids reports what was submitted, not which members were newly added. It can be present on an error response; do not treat it as an item-by-item acceptance report or a count of new members.

Check the payload's error and reported status. If exact membership matters, verify the destination with cb_list_get, including subsequent pages. This response does not provide a per-ID newly-added or already-present result.

cb_list_get

Reads list member identifiers. Input is a list UUID in list_id, with optional after_id for continuation.

The current page size is 50 identifiers and the tool has no input to change it. Follow next_after_id until it is absent or a successful page is empty. A cursor indicates a possible continuation, not a guarantee of more members. Guard against repeated cursors and pages that make no progress.

For the complete loop, see Saved-list pagination.

Only cb_list_create and cb_list_add_entities modify lists; cb_list_query and cb_list_get are reads. The feedback tools also record state. Obtain authorization for intended writes and inspect the destination before retrying an uncertain write.

Utilities

cb_knowledge_center

Answers questions about Crunchbase products, integration setup, coverage, and account topics. Takes a required question string (up to 1,000 characters), and returns answer, citation sources, and a request ID when available. It does not retrieve market records, but it consumes data tokens for processing. Returned answer values do not add a separate response-value charge. Follow citation links for setup details. Use this Developer Reference for MCP arguments and Connecting AI Tools for OAuth endpoints.

cb_metering_get_state

Returns the current user's Crunchbase data-token allowance. Call with {}; this check is free. Read structuredContent.meters and select meter_id="data_mcp_tokens", rather than assuming array order.

The returned state can include limit, used, available, status, scope, period, related_tools, upcoming_meter_refresh, and a per-meter warning. Status is available, exhausted, or unknown. Missing amounts and unknown status do not mean unlimited access; a missing reset time does not establish when the allowance resets. Check the payload's error first.

This tool reports a current account-level reading, not a reservation or a price quote. Other connections can use the same allowance, so before/after balance differences are not reliable per-request attribution. Use the raw result's _meta["cb/data_tokens"].consumed for each confirmed deduction.

On DATA_TOKENS_EXHAUSTED, inspect the error's exhausted_meters when supplied; it uses the same meter-state shape. Use this tool when that field is absent or to re-check after allowance is restored. Do not discard usable data from a successful response solely because it reports exhaustion.

This check does not enumerate all rate limits or access restrictions. An empty meters array is not proof of unrestricted access. See Data-Token Metering for field definitions and response examples.

Programmatic access

The tools above are documented as your AI assistant uses them through an interactive, user-authenticated connection. Crunchbase also offers options for programmatic MCP access: headless agents, backend services, and automated workflows that connect without an interactive user session.

These arrangements have their own authentication, identity, and data-access considerations, so they're set up individually; contact your Customer Success Manager for guidance before building against the server programmatically.

Integration guidance

See Building a Crunchbase MCP Integration, Reliability, Errors, and Pagination, and Known MCP Limitations. Discover the connected caller's live tool schemas for exact inputs and access-dependent limits.