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 using your MCP client's protocol negotiation and enumerate available tools. Use the returned input schemas, including caller-specific limits, rather than treating a saved schema snapshot as universal. Handle protocol or capability negotiation failures explicitly; these pages do not specify a version-support or deprecation guarantee.

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.
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 an invalid request without rendering it as zero matches.
• 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, and source-link fields.
• 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 an agreed test list.
• 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.

Data-token allowance

cb_metering_get_state reports the current user’s Crunchbase data-token allowance, including available/used amounts and reset time when supplied. It does not report every access restriction or rate limit. Budget returned data with explicit fields, focused cards, and small previews. Treat missing or unknown allowance values as unknown, not unlimited. See Reliability, Errors, and Pagination for exhaustion handling.