Building a Crunchbase MCP Integration

Connect an application to Crunchbase MCP and validate the workflows it will run. Start with the Developer Reference and Reliability, Errors, and Pagination.

Choose the access model

For an interactive integration, each user signs in with their Crunchbase account and needs MCP access. A custom OAuth client identifies your application; it does not by itself grant data access or provide a service account.

For unattended, shared, or headless use, arrange authentication, identity, and data access with your Customer Success Manager before deployment. Do not assume that interactive-seat terms or a client secret authorize shared backend access.

Connect and authenticate

Use https://mcp.crunchbase.com with Streamable HTTP and OAuth 2.1 with PKCE. Clients supporting Client ID Metadata Documents (CIMD) can connect without manual client registration. Dynamic Client Registration (DCR) is not supported.

Otherwise, create a custom OAuth client in Crunchbase under Account Settings → Integrations → MCP. Register the callback URLs your client uses. Up to ten callbacks can be registered; matching is exact, wildcards are unsupported, and HTTPS is required except for localhost or 127.0.0.1. Store the client secret securely.

The current documented endpoints are:

Authorization-code flow with PKCE and refresh tokens is supported. Use returned token metadata and the discovered authentication configuration; do not hard-code an assumed token lifetime, refresh-rotation policy, scope, or client-credentials grant.

For detailed registration instructions, see Connecting AI Tools.

Discover tools for the connected user

Initialize the MCP connection and enumerate available tools. Use the returned input schemas and caller-specific limits. Handle protocol or capability negotiation errors before calling tools.

Separate the model-visible tool definitions from your application's authorization policy. These tools change state:

• cb_list_create creates a list.
• cb_list_add_entities adds members.
• cb_expert_submit_feedback records answer feedback and may trigger an answer rewrite.
• cb_expert_submit_search_feedback records build-search feedback and may trigger a recompiled search.

cb_list_query and cb_list_get read lists. Do not classify every cb_list_* tool as a write. Submit feedback only when it represents the user's reaction.

First successful workflow

1. Call cb_reference with {"path":"index"}.
2. Resolve an entity with cb_entity_autocomplete.
3. Retrieve a small, explicitly selected profile or relationship card.
4. Inspect both protocol-level and payload-level errors before consuming results.
5. Save the request ID, when returned, with your own invocation identifier. Capture the raw result's _meta["cb/data_tokens"] before formatting or extracting structuredContent.
6. Validate the result shape your application needs, including whether requested fields and cards are present. Missing selections may not produce an error.

For a structured location search, inspect entities/organization/fields/location_identifiers and resolve the location with autocomplete. The following request uses the Luxembourg country permalink returned by the location reference:

{"collection_id":"organizations","field_ids":["identifier"],"predicates":[{"field_id":"location_identifiers","operator_id":"includes","values":["luxembourg"]}],"limit":2}

Pass it as the arguments to cb_search_query. For page two, add after_id using the last entity UUID from page one. Follow the traversal checks in Reliability, Errors, and Pagination.

Integrating with an agent platform

An integration needs to preserve Crunchbase's tool names, argument schemas, structured results, and source links through its connector layer. A successful connection is only the first check: verify that the model can choose the right tool and that the application handles partial results and failures.

Preserve entity uuid, entity_def_id, and url where supplied. Keep structured payloads available to application logic even if the user sees a formatted summary. Do not reduce an error response to an empty table, or drop truncated and continuation indicators during formatting.

Allow users to review list writes. If a write times out, inspect the destination before resubmission; exactly-once behavior is not established by these docs.

Validate before rollout

Run this checklist using the same access level your customers will have:

• Complete OAuth connection and a representative read.
• Exercise refresh and reconnect through your client's supported flow.
• Verify schema discovery and caller-specific limits.
• Traverse at least two search pages and two pages of a selected relationship card.
• Handle saved-list continuation with next_after_id, empty pages, missing counts, and repeated cursors.
• Handle an invalid request without rendering it as zero matches. Distinguish search validation, database query timeout, transport timeout, temporary rate limits, and data-token exhaustion.
• Parse Expert rows by column position, preserving entity-identity objects and other JSON values.
• Handle a resolution match whose embedded profile has an error, and a ranked candidate response that still needs selection.
• Check for silently omitted profile fields/cards and enforce application-level payload limits; a multi-card related-entity budget is not a strict total-row cap.
• Preserve truncation, interpretation, source-link fields, and the outer MCP result's _meta.
• Verify per-invocation metering capture with a small charged read, a repeated read, a free reference lookup, and an error with no usable data. Record missing metadata as unknown.
• Handle DATA_TOKENS_EXHAUSTED without a retry loop; inspect the returned allowance or call cb_metering_get_state. Handle other access/rate errors separately.
• Verify approval and recovery behavior for writes in a dedicated test list. Do not use submitted_entity_ids as a per-item newly-added report.
• Confirm that logs contain support details without credentials.

Use Known MCP Limitations to set expectations. Validate with the access level intended for your integration’s users.

Agree operational and data-use terms

Confirm expected volume, concurrency, applicable limits, support contacts, and permitted data use with your account team. Caching, retention, redistribution, and use in model training must follow your agreement; this guide grants no additional rights. Numeric rate limits, service levels, and headless credentials should come from the agreed arrangement rather than assumptions in client code.

Capture and track data-token usage

Keep the raw MCP tool result as well as its structuredContent. The outer result's _meta["cb/data_tokens"] can report consumed (the actual deduction) and exhausted. Neither field belongs inside the profile/search output schema. Test the connector layer: some adapters expose business data but remove _meta.

Record each actual invocation under your own attempt ID, sum each confirmed consumed amount once, and retain a count of unknown attempts. A retry needs a fresh attempt ID and can consume more tokens. Do not count an embedded profile or preview again when it is already included in its parent tool's deduction.

Before a large workflow, call the free cb_metering_get_state tool and find data_mcp_tokens in meters. Use the returned available, status, and reset time when supplied. A balance reading is not a reservation; concurrent requests can use the allowance. Do not infer an exact request charge from a balance difference.

Keep usable data from a successful response that reports exhaustion, then stop further affected data calls. Handle DATA_TOKENS_EXHAUSTED, DATA_TOKENS_DENIED, and DATA_TOKENS_REFUSED separately. Missing metadata, missing amounts, or unknown allowance must not become zero usage or unlimited access.

See Data-Token Metering for raw JSON-RPC and allowance examples, a JavaScript workflow ledger, charging rules, and allowance errors. See Reliability, Errors, and Pagination for error and cancellation handling.