Agents & MCP

Start with the smallest retrieval that answers the question; add steps only when metrics show ambiguity or thin evidence. Every extra tool call adds latency and failure modes—record traces to prove the depth is worth it.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

The host that runs the agent (your API, a desktop product, or an MCP-capable IDE) decides where tokens live and how tools are exposed. Indexify remains a stateless HTTP API behind both paths.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

Observable retrieval fields (scores, metadata, empty results) let you build refusal and escalation rules. You are responsible for prompt and policy; Indexify supplies evidence and ids for audit.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

Maps the scenario cards in Start here to concrete REST and MCP sequences. Replace https://api.indexify.dev with your account’s base URL from the API reference when different.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

MCP is a transport; authorization is still OAuth2 client credentials for the target project. Every Streamable HTTP request to /api/mcp must include Authorization: Bearer <project_access_token>. The same token authorizes equivalent REST calls to your public API base URL. Minting: Quickstart, Appendix — token matrix.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

Use the Streamable HTTP transport to the URL shown in your Indexify product documentation. Every request must send your project access token as Authorization: Bearer ….

Tip: the snippets are meant to be copy/paste friendly—start with the happy path, then intentionally poke at scopes, missing fields, and bad inputs so you know exactly what your app will see in production.

Map an iterative agentic RAG loop to Indexify MCP tools. The same behavior is available over REST (Retrieval fundamentals, Advanced retrieval, Search diagnostics); MCP is for hosts that already run tool-calling agents.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

Each tool is a thin wrapper around a documented GET or POST on the public API. Parameter names and types follow the OpenAPI schemas—your MCP client may show JSON Schema derived from the server; treat the API reference as the contract of record. Auth: Authorization: Bearer with a project access token on every MCP HTTP request. For connection details see Connecting MCP clients.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

Resolve kbId and documentId before search or structured reads. Related guide: Document ingestion.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

Single-KB search. Tool arguments align with SearchRequest / SearchRequestSettings (OpenAPI): rerank uses { isEnabled: "yes" | "no", topK? }; similarity threshold is not configurable per request. Guide: Retrieval fundamentals, Advanced retrieval, Search diagnostics, MCP agent retrieval loop.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

MCP-only composition on top of POST …/search plus optional chunk reads. Same auth and search:run scope as indexify_search. See MCP agent retrieval loop.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

Typed layout elements and parser artifacts for one documentId. Concepts: Structured document access.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

Parsed body (per Accept / format) vs chunk listing for retrieval windows. Use when search snippets are insufficient (Agent patterns).

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

Document-wide and element-scoped relationship lists (typed edges between parsed nodes).

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).

First-class sections, tables, and figures for one document—useful for navigation UIs and multimodal answers.

Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).