Mixedbread ships a polished docs site with a real llms.txt, a programmatic /question endpoint for agents, an OpenAPI-style reference, and SDK pages for Python and TypeScript. But the docs site, the published SDK READMEs, the API reference, and the CLI all disagree with each other on parameters, defaults, limits, and feature shapes — and several reference pages are missing fields the live API actually returns.
1. Python and TypeScript SDK docs disagree with the published packages on defaults and env vars (critical)
Location:/api-reference/sdks/python, /api-reference/sdks/typescript vs. the official mixedbread-ai/mixedbread-python GitHub README, mixedbread-ai/mixedbread-ts GitHub README, and @mixedbread/sdk v0.71.0 on npm.
Problem: The docs site documents max_retries=3, timeout=30.0 seconds (Python) / timeout=30000 ms (TS), and MXBAI_BASE_URL as the base-URL env var. The published packages (GitHub READMEs and the npm page for @mixedbread/sdk@0.71.0) say max_retries=2, a 60-second / 1-minute default timeout, MIXEDBREAD_LOG for log level, MIXEDBREAD_BASE_URL for the base URL, and expose an environment: 'development' | 'production' | 'local' constructor option that the docs site never mentions. Both SDKs are generated by Stainless, so the GitHub/npm values are authoritative.
Consequence: A developer reading only the docs site will mis-calibrate retry budgets, set the wrong env var (the SDK reads MIXEDBREAD_BASE_URL, not the documented MXBAI_BASE_URL — so the docs' env var won't be picked up), miss the environment="local" option entirely, and assume requests die at 30s when they actually run for 60s. Agents that parse the docs to generate Mixedbread client code will produce code whose runtime behavior differs from what the docs page predicts.
The fix: Treat the SDK READMEs as the source of truth and regenerate the SDK docs from the same Stainless spec. Add environment and logLevel / MIXEDBREAD_LOG and MIXEDBREAD_BASE_URL to both SDK pages; correct the default max_retries to 2 and timeout to 60000 ms / 60.0 s.
2. Agentic-search instructions length contradicts the platform Limits page by 2.5x (critical)
Code verification
Runtime snippet checks
Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.
Location:/docs/platform/limits vs. /docs/stores/search/agentic-search.
Problem: The Limits page states "Max agentic search instructions length — 5,000 characters." The Agentic Search parameter reference, on a sibling page, says instructions accepts "up to 2,000 characters." Nothing reconciles the two.
Consequence: A developer building an agentic pipeline writes a 4,800-character system instruction (well within the documented 5,000 limit), only to be rejected by the API; or, more dangerously, the request silently truncates and the agent's behavior drifts. An LLM consuming both pages cannot decide which limit to enforce on user input.
The fix: Establish the real server-side maximum, then make both pages cite the same number with a single canonical link.
3. Question-Answering endpoint declares file_ids must contain exactly two items (critical)
Problem: The published request-body schema lists file_ids as array | array with Minimum items: 2 and Maximum items: 2. The corresponding Search Chunks endpoint reference describes file_ids as an optional inclusion filter that can also take operator forms like ["not_in", ["file_id_1", "file_id_2"]].
Consequence: Read at face value, QA can only ever filter to exactly two file IDs — making single-file QA impossible and 3+ file scopes impossible. This is almost certainly a doc-generator bug (the QA endpoint should mirror Search Chunks), but as written it's a contradiction that will trip up any developer or agent reading the schema literally.
The fix: Regenerate the QA reference from the same source as Search Chunks so file_ids matches the documented array | null shape with inclusion/operator semantics. Remove the spurious Minimum items: 2 / Maximum items: 2 constraint.
4. qa_options appears in every QA example but isn't in the request body schema (critical)
Location:/api-reference/endpoints/stores/search/question-answering and /docs/stores/search/question-answering.
Problem: The QA reference's own code sample calls qa_options={"cite": True, "multimodal": True}, and the docs prose says "By default, Question Answering uses citations and multimodal context. To change behavior, pass qa_options explicitly." But qa_options is not listed in the endpoint's Request Body schema at all. Allowed keys, value types, and defaults are nowhere defined.
Consequence: Developers cannot discover what qa_options accepts beyond the two booleans hinted at in the example. Agents generating QA requests will either omit the option entirely or hallucinate a schema for it. The behavior of cite=False and multimodal=False is unspecified.
The fix: Add qa_options to the request body schema with each field documented (cite: boolean, multimodal: boolean, and anything else the server accepts), defaults, and the citation-tag format produced when cite=True.
5. Search Chunks reference omits cross-cutting parameters the rest of the docs depend on (critical)
Location:/api-reference/endpoints/stores/search/search-chunks vs. /docs/stores/search, /api-reference/sdks/python, /mcp/tools.
Problem: The canonical POST /v1/stores/search reference only documents query, store_identifiers, top_k, and file_ids. Yet:
The Search overview page describes Rewrite Query and multi-store reranking;
The Python SDK page uses search_options={'return_metadata': True, 'rerank': True};
The MCP tools reference exposes filters and search_options on the same /v1/stores/search semantics.
None of filters, search_options, rerank, or rewrite_query appear in the Search Chunks endpoint reference, even though they are first-class options for that endpoint everywhere else in the docs. (Agentic-only knobs like max_rounds / queries_per_round / strict_top_k / media_content correctly belong to a separate /v1/stores/agentic-search surface, so they're out of scope for this page.)
Consequence: The reference page that an agent fetches first to learn what /v1/stores/search accepts is dramatically incomplete. Developers either copy the under-specified example and miss reranking entirely, or hunt across four other pages to assemble a real request. The "one API" homepage promise is undermined by the fact that the API reference for the flagship endpoint is missing most of its parameters.
The fix: Regenerate the Search Chunks reference from the same OpenAPI source as the SDKs so it lists every accepted field with constraints and defaults, with cross-links to the long-form /docs/stores/search/* pages for narrative explanation.
6. Data Models page is missing fields the live Create Store API returns (significant)
Location:/docs/stores/data-models vs. /api-reference/endpoints/stores/manage/create-store.
Problem: The Store Properties table on Data Models lists 14 fields (id, name, description, is_public, metadata, file_counts, expires_after, status, created_at, updated_at, last_active_at, usage_bytes, expires_at, object). The live Create Store response includes config.contextualization.{with_metadata, with_file_context}, config.save_content, usage_tokens, and license — none of which appear on the Data Models page. Conversely, the Stores doc page describes contextualization as false | true | array of fields, but the API response shape is a nested object {with_metadata, with_file_context}. Three different shapes for one feature.
Consequence: Developers writing typed clients or schemas (especially anyone code-generating from the Data Models page) will produce structs that drop real fields like usage_tokens and mis-type contextualization as a boolean when the server actually returns an object. Agents reasoning over the docs will pick whichever shape they saw first.
The fix: Treat the OpenAPI schema as canonical. Regenerate the Data Models table from it, add config, usage_tokens, and license, and rewrite the Stores configuration page so the documented contextualization shape matches the API's nested object.
7. Metadata filter operator vocabulary contradicts itself across two pages (significant)
Location:/docs/stores/metadata-filtering vs. /docs/stores/store-files/metadata-types.
Problem: Metadata Types claims string filtering supports "pattern match (like, not like)". The Metadata Filtering page never documents a like operator at all — it lists starts_with, regex, and a confusingly named inverse not_like (which actually means "does not start with"). The naming is also asymmetric: the positive form is starts_with but the negative is not_like (not not_starts_with).
Consequence: A developer who reads "supports like / not like" tries {"operator": "like", "value": "*foo*"} and gets a 422; an agent generating filters will guess. The inconsistent naming (starts_with vs. not_like) also makes filters harder to read and maintain.
The fix: Pick one vocabulary (starts_with / not_starts_with, or like / not_like with glob semantics), document it in one place, and remove every reference to operators that don't exist server-side.
8. Two upload paths, no page explaining there are two upload paths (significant)
Location:/api-reference/endpoints/files/upload-file vs. /api-reference/endpoints/stores/files/add-store-file vs. /docs/stores/store-files.
Problem:POST /v1/files accepts only file — no metadata, no external_id, no overwrite. All of those live on POST /v1/stores/{store_identifier}/files, which references a file_id from the first call. The Create Files doc page describes external_id, overwrite, and parsing strategies as if they were uploaded options, but the generic /v1/files reference contradicts that. There is no narrative anywhere explaining "upload, then attach to a store" as a two-step flow.
Consequence: A developer reading the docs page expects to pass metadata and external_id directly to upload, finds those fields missing from /v1/files, and has to reverse-engineer that they need a second call to /v1/stores/{id}/files. Agents writing upload code will pick one endpoint or the other and silently drop the metadata.
The fix: Add a "How file uploads work" diagram/section at the top of /docs/stores/store-files that explicitly names both endpoints and the order. Link from each endpoint reference back to the other.
9. Rate Limiting example response has a placeholder URL pointing at the docs page itself (significant)
Location:/api-reference/rate-limits.
Problem: The sample 429 response body uses "url": "https://www.mixedbread.com/api-reference" — the docs page's own URL — rather than the API endpoint that triggered the limit. Combined with the fact that the Error Handling page's "Code Examples" section is empty and the JSON error envelope is never defined anywhere, developers have no canonical example of what a real Mixedbread error body looks like.
Consequence: A developer building error handling copies the example and ends up matching against a URL that will never appear at runtime. Agents that parse the example as ground truth will generate broken retry logic. Worse, since the error envelope (type, url, message, details) isn't documented anywhere as a typed schema, this placeholder is effectively the only "spec" available.
The fix: Fix the placeholder URL (use a representative API endpoint like https://api.mixedbread.com/v1/stores/search) and add a typed Error envelope schema with each field's meaning to the Error Handling page. Fill in the empty "Code Examples" section.
10. Plan rate limits and the Rate Limiting page use incompatible units (significant)
Location:/pricing vs. /api-reference/rate-limits.
Problem: Pricing shows Starter at "100 requests / minute" and Scale at "1,200 queries/min, 360 ingestion/min." The Rate Limiting reference enumerates Read 1,200/min, List 600/min, Write 360/min, Update 480/min, Delete 240/min — with no notion of plan, no statement of which plan these numbers describe, and no mapping between "queries" / "ingestion" (pricing) and Read / Write (rate-limits page).
Consequence: A developer on Starter cannot tell whether "100 requests / minute" overrides every per-operation limit on the Rate Limiting page or stacks with them. A developer on Scale cannot tell whether "360 ingestion/min" is the same number as "Write: 360/min" or a separate bucket. Capacity-planning math is impossible from the public docs.
The fix: Add a "Limits by plan" table to the Rate Limiting page that explicitly states the per-operation limits for Starter / Scale / Enterprise, and make pricing link to it instead of restating different-shape numbers.
11. Pagination reference lists three paginated endpoints; the live API paginates more (significant)
Location:/api-reference/pagination vs. /api-reference/endpoints/files/list-files and similar list endpoints.
Problem: The Pagination page says cursor-based pagination "is used for" exactly three endpoints: List Stores, List Files, List Parsing Jobs. But the changelog adds stores.list_chunks, and Store File listing and parsing-result listing return the same pagination envelope. The "Supported Endpoints" list is treated as exhaustive.
Consequence: Developers don't realize newer list endpoints support cursors, and write code that fetches only the first page. Agents that parse the Pagination page as authoritative will produce code that never paginates past the first result for unlisted endpoints.
The fix: Either generate the supported-endpoints list from the OpenAPI spec, or rewrite the page to say "all list endpoints" and remove the enumeration so it can't drift.
12. Free-tier description on Billing contradicts the Pricing page (significant)
Location:/docs/platform/billing vs. /pricing vs. /changelog.
Problem: Billing says "Mixedbread offers a free tier with monthly allocations for ingestion, queries, and parsing." Pricing's Starter plan, by contrast, gives "$5 in one-time credits" — explicitly one-time, no monthly allocation. The changelog adds a third version: "Free tier users get up to 1000 store files and access to core platform features" — a file count cap that doesn't appear on Pricing (which lists "10 stores" instead).
Consequence: Three different mental models of "free" coexist on the site. A developer evaluating Mixedbread cannot answer "what do I get for free?" without picking one page to trust. This matters for procurement and POC sizing.
The fix: Pick the current truth, put it on the Pricing page, and rewrite the Billing and changelog references to point at it instead of restating numbers.
13. CLI documents a deprecated config key as if it were current (significant)
Location:/cli/configuration, /cli/files.
Problem: The CLI Configuration page documents defaults.upload.contextualization as a configurable boolean with default false, then in the very next paragraph says "Deprecated — This setting is ignored by the CLI and will be removed in a future version." The default JSON config printed lower on the page still includes the deprecated key, with a JavaScript-style // Deprecated… comment embedded inside JSON (invalid JSON). The manifest examples on /cli/files carry the same // comments inside JSON. The Update Store CLI command does not expose --contextualization, so once a store is created, the only documented place to change this setting (mxbai store create --contextualization) is no longer reachable.
Consequence: Users follow the documented config-set command, see no error, and assume contextualization is enabled — but it's silently ignored. The JSON examples won't parse if copy-pasted into a real .json file. Anyone who needs to change contextualization on an existing store has no documented CLI path.
The fix: Remove the deprecated key from every example (or wrap deprecation notices outside the JSON), add --contextualization to mxbai store update, and provide one canonical example of the current store-level configuration command.
14. Grep Store Chunks targets parameter is internally inconsistent (significant)
Problem: The targets parameter is documented as a scalar enum with possible values text and generated, but the same parameter carries a Minimum items: 1 constraint, which only makes sense if the field is an array. The schema doesn't reconcile the two — a developer cannot tell whether the correct request is "targets": "text" or "targets": ["text"].
Consequence: A request crafted from either reading will be wrong half the time. Agents generating Grep calls will either send a scalar to an array-typed field or vice versa and get a 422 with no clue why. This is a request-shape ambiguity on a brand-new product surface.
The fix: Decide whether targets is a single enum value or an array of enum values, fix the schema, and remove the contradictory constraint. If it's an array, add a default (["text", "generated"] or similar).
15. Multipart Upload doc has empty subsections under every customization heading (significant)
Problem: The page has "Custom Threshold," "Custom Concurrency," and "Custom Part Size" as second-level headings with no code, no example, and no prose beneath any of them. Only the bottom "Options Reference" table actually carries the names (threshold, partSize / part_size, concurrency) and defaults. There is no example showing how to pass these options into upload or uploadAndPoll.
Consequence: A developer who needs to tune multipart upload behavior cannot see what argument to pass or what shape it takes. The "it just works" claim in the intro is the only guidance, which is not enough if a 4 GB upload is failing partway through.
The fix: Fill in each subsection with a minimal code sample showing the argument in context (Python and TypeScript), and document the units (MB vs bytes) on each option.
16. MCP Tools reference is missing Store Update entirely (significant)
Location:/mcp/tools vs. /changelog and CLI surface.
Problem: The MCP Tools page enumerates "Tool Categories" as Store Search, Store File Search, Store Create, Store Retrieve, Store List, Store Delete. There is no Store Update tool listed, even though the CLI and SDK both expose store updates and the broader product surface clearly supports it.
Consequence: An agent connected via MCP can create and delete stores but, per the documentation, cannot rename or reconfigure them — forcing destroy-and-recreate workflows for what should be a one-call update. If the tool actually exists on the server but is undocumented, agents won't discover it.
The fix: Either add the missing Store Update tool to the reference (with parameters and an example), or, if it genuinely isn't implemented yet, add it as an explicit "Not yet supported" note so users know to fall back to the REST API or CLI.
17. API Introduction's first curl example contains invalid JSON (significant)
Location:/api-reference.
Problem: The very first authenticated request example in the API Introduction is:
-d '{
"name": "My Knowledge Base",
}'
The trailing comma makes this invalid JSON. This is the first snippet a brand-new developer copies after generating an API key.
Consequence: Pasted as-is, the request fails JSON parsing and returns a 400. The user's first impression of the API is a parse error caused by the docs, not by their own code. Agents generating onboarding code from this page will reproduce the bad comma.
The fix: Remove the trailing comma. Add a lint step to the docs build that JSON-parses every fenced code block whose language is json or bash-with--d '{...}'.
18. Two "Supported File Types" pages give different answers (significant)
Location:/docs/stores/store-files/file-types vs. /docs/parsing/file-types.
Problem: Two identically-titled pages list different supported formats. The Stores page lists Markdown, code (Python/JS/TS/Java/C#/C/C++/Go/HTML/Ruby/Rust/etc.), audio (MP3/WAV/OGG/M4A/etc.), and video (MP4/WebM/MOV/etc.) on top of the document types. The Parsing page lists only Documents, Presentations, Spreadsheets, and Images — none of the code, audio, video, or Markdown formats appear.
Consequence: A developer searching "supported file types" lands on either page essentially at random and reaches the wrong conclusion about whether, say, an .mp3 is supported. Agents indexing both pages will produce contradictory answers.
The fix: If the two pages describe genuinely different surfaces (parsing as an API vs. stores ingestion), say so explicitly at the top of each ("Parsing API accepts the following — Stores ingestion accepts a broader superset; see…"). Better, single-source the table.
19. CLI authentication-order list doesn't say what happens when no key is found (minor)
Location:/cli.
Problem: The CLI Introduction enumerates the API-key lookup order as: command-line flag → MXBAI_API_KEY env var → default key from config file. The list stops there, with no mention of what happens when the env var is unset and no config file exists and no flag was passed. Does the command prompt? Error and exit? Run anonymously against a public store?
Consequence: A new user installing the CLI for the first time has no documented fallback behavior. Scripts that assume "no key = exit nonzero" can't rely on that without testing it.
The fix: Add a fourth bullet: "If none of the above are set, the CLI exits with Error: no API key found (exit code N)" — or whatever the actual behavior is.
20. Vercel integration injects MXBAI_STORE_ID but no SDK page consumes it (minor)
Location:/api-reference/integrations/vercel vs. /api-reference/sdks/python, /api-reference/sdks/typescript.
Problem: The Vercel integration's "Connect Project" step automatically adds two environment variables to the user's Vercel project: MXBAI_API_KEY and MXBAI_STORE_ID. The SDK pages only mention MXBAI_API_KEY and MXBAI_BASE_URL — neither documents MXBAI_STORE_ID as something the SDK reads, so the user has to wire it up by hand (store_identifiers=[os.environ["MXBAI_STORE_ID"]]).
Consequence: Vercel users see a free env var injected and reasonably assume the SDK picks it up. When it doesn't, their first integration attempt does nothing useful. There's no documented pattern for what to call on the SDK once Vercel has provisioned the var.
The fix: Either add a Vercel-specific quickstart that shows the literal store_identifiers=[os.environ["MXBAI_STORE_ID"]] pattern, or have the SDK actually pick the var up by default and document that.
21. Skills page assumes the user already has npx skills (skills.sh) installed (minor)
Location:/docs/skills.
Problem: The Skills install command is npx skills add mixedbread-ai/skills — but skills is a third-party tool (skills.sh) and the page never explains that, never links to it, and never says what to do if you don't already have it. The "Browse the package on skills.sh" link appears below the install command, almost as an afterthought.
Consequence: A developer unfamiliar with skills.sh runs the command, gets a network fetch for an unknown CLI, and has no context for what they're installing or trusting. Agents that try to install on the user's behalf can't reason about whether the tool is safe.
The fix: Add a one-line "Prerequisites" note above the install command: "Requires skills.sh. See installation." Then the rest of the page makes sense.
22. CLI config keys list example output leaks escaped markdown asterisks (minor)
Location:/cli/configuration.
Problem: The "List API Keys" example shows sample output as # \* for the default-marked key (a literal escaped asterisk), which is markdown source rather than rendered output. The CLI obviously doesn't emit \* to a terminal; the docs author wrote \* to keep markdown from italicizing the line and never wrapped it in a code block that would suppress the escape.
Consequence: Trivial trust signal — users see fake-looking output and either copy it verbatim or distrust the page. Easy to miss in review.
The fix: Wrap the output sample in a fenced ``` block so the asterisks render as written, and remove the backslashes.
23. CLI "Get Store Details" by-ID example is identical to by-name (minor)
Location:/cli/stores.
Problem: Under "Get Store Details," both the "Get store by name" and "Get store by ID" examples show the same command: mxbai store get "my-knowledge-base". The by-ID example was never filled in with an actual ID like vs_abc123.
Consequence: A user reading the page can't tell what a Store ID looks like or how the CLI distinguishes the two. Trivial to fix, but reinforces the broader sense that examples weren't proofread.
The fix: Replace the second example with a real-looking UUID/ID form so the contrast is visible.
24. List Files endpoint advertises fuzzy search over a non-existent description field (minor)
Location:/api-reference/endpoints/files/list-files vs. /docs/stores/data-models.
Problem: The q query parameter is documented as "Search query for fuzzy matching over name and description fields." But the File Properties table in Data Models lists no description field on files (only Stores have descriptions). The file object schema on this very endpoint doesn't include description either.
Consequence: Developers can't tell whether files actually have descriptions that they should be setting, or whether q is doing dead matching against a phantom field. Either the field exists and is undocumented, or it doesn't exist and the search description is wrong.
The fix: Either add description to the file object schema (and the upload endpoints that would set it) or correct the q parameter description to say "name" only.
25. QA documentation truncates mid-sentence and never shows the citation tag syntax (minor)
Location:/docs/stores/search/question-answering.
Problem: The "Example Response" section says "May include citation tags like " with empty backticks, and the final line ends "Use indices from to map to sources[n]" — again with empty backticks. The literal citation token format (e.g., [1], <cite id=…>, etc.) is never shown anywhere.
Consequence: Developers parsing QA output to render citations don't know what string to look for. Agents generating UI that links answer text to sources can't extract citations without trial-and-error.
The fix: Show the literal citation tag format with a complete example response that contains both the tag and the matching sources entry it indexes into.
26. Generated metadata and mxjson use different type discriminator vocabularies (minor)
Location:/docs/stores/store-files/generated-metadata vs. /docs/stores/store-files/mxjson.
Problem: The mxjson chunk schema requires type ∈ text | image_url | audio_url | video_url. The Generated Metadata page uses type ∈ markdown | text | pdf | code | audio | video | image — bare names without the _url suffix. Two closely related schemas, one type discriminator name, two incompatible value sets.
Consequence: A developer who has internalized one vocabulary will write the wrong type in the other. Agents asked to "produce mxjson for an image chunk" frequently emit "type": "image" because that's what the metadata page primed them with.
The fix: Either reuse the same vocabulary in both schemas, or clearly explain on each page that "chunk type" and "generated metadata type" are different fields with different value sets.
27. Blog index doesn't list the headline posts the rest of the site cites (minor)
Location:/blog vs. / and /docs/stores/search/rerank.
Problem: The homepage and Rerank docs prominently advertise "mxbai-rerank-v3-listwise" and "Wholembed v3" announcement posts, and the Rerank docs link to /blog/listwise-rerank. But the public blog index lists only three posts and neither of those announcements appears.
Consequence: Developers clicking through from the homepage's "Pushing the frontier of retrieval" section can't find the announcements via blog navigation; they have to know the direct slug. Agents indexing the blog via the listing page miss the most important launches.
The fix: Ensure the blog index lists every published post (including listwise-rerank and the Wholembed v3 announcement), sorted by date.
28. Public Stores concept appears nowhere on the Pricing page (minor)
Location:/docs/stores/stores/public-stores vs. /pricing.
Problem: The Public Stores page explains that searches against a public store (e.g., acme/music) are billed to the caller's API key, not the owner's — and mixedbread/web is billed at a "search with rerank" rate per query. Pricing makes no mention of public stores, of mixedbread/web billing, or of the cross-org cost model.
Consequence: A developer building a SaaS that exposes a public store has to dig two levels deep into docs to discover they won't be charged for outside searches. Conversely, anyone calling mixedbread/web from the pricing page alone has no way to know each call is billed as rerank ($7.50/1K) rather than basic search ($4/1K).
The fix: Add a "Public stores and mixedbread/web" subsection to the Pricing page so the billing model is visible at the point of purchasing decision.
29. Quickstart and concepts pages leak raw template code into rendered Markdown (minor)
Location:/docs/stores/concepts.
Problem: The Concepts page renders the literal string {[1, 2, 3, 4].map((n) => ( as plain text — a JSX/React snippet that was supposed to be evaluated and produce some visual element, but the surrounding template never closed properly. The page also has the matching ))} exposed.
Consequence: Trust signal — the most-read conceptual page in the docs has broken templating that ships to production. Agents fetching the Markdown will see the broken code block and either reproduce it verbatim or refuse to summarize the section.
The fix: Render the intended diagram, or remove the dead JSX. Add a content lint that fails the build when {[ or }} leaks into rendered markdown.
30. MCP install for Claude Code puts the API key in shell history; Claude Desktop docs don't (minor)
Location:/mcp/integrations/claude-code vs. /mcp/integrations/claude-desktop.
Problem: The Claude Code install command embeds --header "Authorization: Bearer YOUR_MIXEDBREAD_API_KEY" directly in the claude mcp add command line, with no warning. The Claude Desktop integration page, by contrast, uses ${MXBAI_AUTH_HEADER} indirection so the key stays in env, not in the args array.
Consequence: A user following the Claude Code instructions ends up with a long-lived API key in their shell history (~/.zsh_history, etc.). The asymmetry suggests the docs author knew this was bad practice in one place but not the other.
The fix: Update the Claude Code page to read the API key from an environment variable, or at minimum add a callout that the literal-key form leaks into shell history.
31. Custom Connector instructions for Claude Desktop don't mention the paid-plan requirement upfront (minor)
Location:/mcp/integrations/claude-desktop.
Problem: Method 1 (Custom Connector) is recommended at the top of the page; the requirement "Custom connectors are available on Claude Pro, Max, Team, and Enterprise plans" appears at the very bottom of that section, after the user has been walked through five steps.
Consequence: Users on Claude's free plan follow the "Recommended" steps and discover at "Add custom connector" that the option doesn't exist for them — and have to scroll back up to find Method 2.
The fix: Move the plan-requirement note to the section heading, above the steps.
32. Typos in core search docs (minor)
Location:/docs/stores/search (Rewrite Query section) and /docs/stores/store-files (Upload Helpers section).
Problem: "to ge the most optimal" (missing "t" in "get"), and "asynchonisly" (should be "asynchronously"). Both are on conceptual pages developers read while building.
Consequence: Minor, but these are the pages an evaluating engineer reads first. Two typos on landing-page docs signal weak proofreading.
The fix: Spell-check pass over the /docs/stores/* tree.
What they do well
Real agent ergonomics where most companies have none:llms.txt, llms-full.txt, and a programmatic /question?q=…§ion=… endpoint specifically advertised to agents — including an explicit "Agent tip" in the Quickstart — is genuinely ahead of the curve.
The endpoint reference exists and is largely structured (request/response schemas, constraints, code samples), which is more than many AI infra startups ship at this stage.
First-party MCP server with both stdio and OAuth flows for Claude Code and Claude Desktop, and a documented mixedbread/web public store for web augmentation — clear thinking about how their product gets consumed by agents.
Top 3 recommendations
Pick one source of truth for SDK and API shapes — the Stainless spec — and regenerate every "docs site" page from it. Today the docs site, the GitHub READMEs, the npm page, and the live API schema all drift independently. Findings #1, #5, #6, #11, and #16 collapse to this one fix.
Reconcile every numerical limit and feature shape that appears on more than one page (agentic instructions length, plan rate limits, free-tier definition, contextualization shape, operator vocabulary, file-types list). These are exactly the contradictions that silently break agent-generated code.
Finish the half-shipped pages — Multipart Upload's empty subsections, Question Answering's truncated citation example and missing qa_options schema, Error Handling's empty Code Examples, the QA endpoint's file_ids: 2..2 constraint, the Grep targets enum-or-array ambiguity, the rate-limit example URL pointing at the docs page, the API Introduction's trailing-comma JSON, and the JSX leak on Concepts. Each one signals "no human read this end-to-end before publish."