Known MCP Limitations

Use these limitations when designing an integration. For handling patterns and examples, see Reliability, Errors, and Pagination.

Area	Current constraint	What to do
Search validation	Some invalid requests return a generic HTTP 400 message without identifying the offending field.	Check each field and operator through `cb_reference`; simplify one predicate at a time.
Error envelope	Transport, MCP, and tool-payload errors are separate layers.	Check all layers before reading result rows.
Empty results	Zero rows may arrive without predicate, coverage, or access diagnostics.	Validate identifiers and scope; do not equate zero matches with absence in the real world.
Expert answer shaping	The question input has no explicit row-limit, selected-field, deduplication, or continuation parameter.	Use natural language to express intent; use structured search when you need explicit retrieval controls.
Expert interpretation	Expert can narrow the answered question.	Surface `answered_question` when supplied.
Profile selections	Unknown or unavailable fields/cards can be omitted without an error.	Validate selections and compare requested versus returned content; missing does not mean empty.
Related-entity budget	`related_entity_limit` is not a strict combined row cap across multiple cards.	Select cards explicitly and enforce application-level payload safeguards.
Input limits	Validation can occur in the client or server, and out-of-range handling varies by input.	Use supported values; do not rely on rejection or normalization of invalid values.
Entity resolution	Company domains are unsuitable for person lookups and may yield the wrong entity or no candidates.	Use a person collection, name, and context for person resolution.
Card continuation	No per-card total or effective page-size field is exposed. Single-card responses are capped at 100 or a lower applicable card/access limit; continuation can reflect budget clipping or an exactly full page.	Fetch one card at a time, inspect the flag, and guard against empty pages and repeated cursors.
Multi-page consistency	Records and counts can change between page requests.	Keep the query unchanged, deduplicate UUIDs, and label interrupted traversals as incomplete.
Request correlation	Request IDs are useful for support but are not an application-level uniqueness guarantee. Some tools do not expose one.	Record your own invocation ID, timestamp, and tool name as well.
Write retries	List creation and feedback are non-idempotent. Adding members to a list is marked idempotent; submitted IDs still do not confirm newly added members.	Check existing lists before retrying creation. Verify membership after an uncertain addition, and avoid automatically repeating feedback.
Data-token metadata	Per-request deduction is outside the business payload, in the raw result's `_meta["cb/data_tokens"]`. Some connectors omit it.	Preserve and test outer metadata. A missing `consumed` amount is unknown, not zero. See Data-Token Metering.
Allowance and concurrency	A meter reading is not a reservation; other connections can use the same allowance.	Use per-result deductions for attribution, not before/after balance differences. Unknown allowance is not unlimited.
Successful exhaustion	A usable response can consume the remaining balance and report `exhausted: true`.	Keep the returned data and stop further affected calls; inspect errors separately.
Cancellation and retries	A disconnected call can still complete a charge; a retry can consume tokens again.	Track actual attempts separately and record unconfirmed charges as unknown.

Access and generated guidance

Programmatic access. A registered OAuth client identifies your application; it does not provide a service identity. Arrange unattended or shared access with your Customer Success Manager.

Knowledge Center answers. Follow citation links for supporting information. For implementation details, use the current Developer Reference and the tool schemas returned by your connection.

Guidance examples

Prefer the live per-field reference when constructing predicates. Identifier filters need returned UUIDs or permalinks; do not copy display names such as "San Francisco" into identifier-valued predicates.

A relationship subquery requires the appropriate relationship collection and nested query shape. If an example cannot be validated for your use case, obtain a compiled search with cb_expert_build_search, review its scope, and replay it through cb_search_query.

Reporting a problem

Contact your account team or Customer Success Manager with the UTC timestamp, client/version, tool name, redacted arguments, error code/message, and request ID when available. Describe whether the problem is a failed call, an unexpected interpretation, or an incomplete traversal.