# Redpine Connect: agent setup guide Redpine Connect searches research and data and returns passages with citations. It also provides integration tools through MCP. Use this guide to connect the system the user intends, then verify that connection before reporting success. ## First choose the intended connection - **An application or existing system:** follow the API and SDK path below. This applies even when you are a coding agent with shell access or MCP support. The application must be able to call Redpine independently of your chat session. - **You, the agent:** follow the MCP or CLI path so the client or runtime running you can use Redpine tools. - **Both:** complete and verify each path separately. Connecting your own MCP client does not configure the application's credentials or code. Use the user's request and project context to choose. If the goal is still unclear, ask: "Should Redpine be available inside your application, or as tools I can use in this chat?" Ask for the client or language only if you cannot identify it from the existing environment. ## Path A: integrate an application or existing system ### 1. Inspect the project and choose a client Identify the language, dependency manager, existing Redpine configuration and where the application needs search results. Follow the project's architecture and reuse an existing integration where possible. Prefer the official SDK for Python (`redpine-sdk`), TypeScript (`@redpine-ai/sdk`) or Go (`github.com/redpine-ai/redpine-sdk-go`). Read the current installation and usage instructions at https://docs.redpine.ai/docs/sdks.md; do not guess an installation command from a package name. For another language, use HTTPS and the request schemas at https://docs.redpine.ai/openapi.json. ### 2. Configure sandbox credentials Ask the user to create a sandbox key (`sk_test_`) at https://app.redpine.ai/api-keys if no suitable key is configured. Have them provide it through the application's environment or secret manager as `REDPINE_API_KEY`. Never invent a key, commit it, include it in a URL, print it in logs, or bundle it into browser code. A browser application should call its own backend, which holds the Redpine key. The API base URL is `https://api.redpine.ai`. REST requests use `Authorization: Bearer `; `X-API-Key` is also supported. These examples assume `REDPINE_API_KEY` is already set securely in your shell environment. Sandbox requests return synthetic fixtures at no cost. They verify integration behaviour, not live content quality or access to third-party integration tools. See https://docs.redpine.ai/docs/sandbox.md. ### 3. Discover collections and make a sandbox request List collections using the SDK or this free REST request: ```bash curl "https://api.redpine.ai/api/v1/search/collections" \ -H "Authorization: Bearer $REDPINE_API_KEY" ``` Use an exact `name` from the returned collections. Never infer a collection name from the question. If none are available, report that access is needed. Replace `COLLECTION_FROM_LIST` below with a returned name: ```bash curl -X POST "https://api.redpine.ai/api/v1/search/query" \ -H "Authorization: Bearer $REDPINE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"collection": "COLLECTION_FROM_LIST", "query": "your search query"}' ``` Provide `query` and either `collection` or `collections` (an array of at most five names), never both collection fields. Use the SDK equivalents from https://docs.redpine.ai/docs/sdks.md and https://docs.redpine.ai/docs/search.md. ### 4. Wire the application's actual call path and verify it Connect the SDK or HTTP call to the requested feature. Handle results, citations, empty responses and API errors through the application's existing conventions. Run the feature through its real application boundary with the sandbox key, not just a standalone cURL command. Check the response's `queryId`, results and `X-Billing-Mode: sandbox` header where available; do not describe fixture results as live research. Run the project's relevant checks. When the user is ready for live data, configure a live key (`sk_live_`) through the same secret mechanism and list its accessible collections again. Live searches can incur charges. A free preview lets you check real relevance and estimated cost before paying to unlock results: https://docs.redpine.ai/docs/preview-unlock.md. Do not silently turn a setup check into a paid search or unlock. ## Path B: connect yourself as an agent ### 1. Configure the client that actually runs you Check whether Redpine is already connected and usable. Otherwise identify your client or runtime and fetch its exact instructions from https://docs.redpine.ai/docs/mcp.md. Use its supported setup command or configuration; do not implement OAuth or MCP JSON-RPC by hand. The remote MCP endpoint is: ``` https://api.redpine.ai/mcp ``` Use Streamable HTTP. Clients with OAuth support discover authentication from the server; complete the browser approval for the intended organisation. Registration alone is not authorization: some clients need a separate login command or a Login action in settings. If the client supports static headers, it can instead send `Authorization: Bearer ` or `X-API-Key: `. Keep keys in the client's supported secure configuration. Shell access does not guarantee that you can add tools to the current session. If configuration requires a user action or client reload, explain the exact step and report the connection as pending until you can verify it. Preserve other servers when updating client configuration. If your runtime cannot use MCP but can run shell commands, the Redpine CLI is an alternative. Follow https://docs.redpine.ai/docs/mcp.md#redpine-cli for installation and login, then use `redpine collections` to verify access. A CLI connection lets you run commands; it does not add native MCP tools to the current chat. ### 2. Verify authentication and collection access Inspect the tools actually advertised by your runtime (`tools/list` for MCP). Tool exposure can differ by client. Follow the returned names and schemas. Where the meta-tools are exposed, use this sequence: 1. Use `find-tools` to discover `list_collections`. 2. Use `inspect-tool` with the exact discovered name to read its schema. 3. Use `call-tool` with that name and the required arguments to list collections at no cost. If `list_collections` is directly exposed, call it directly. A successful authenticated listing verifies the connection. An empty list means collection access still needs attention; it is not proof that search is ready. Confirm the tools are usable in this session before saying setup is complete. If the client hides raw discovery, use its exposed Redpine tool interface to perform the same free listing. ### 3. Use search and integrations for the user's task Choose a collection from the listing. Discover `search`, inspect its parameters, and call it through `call-tool`, or use the directly exposed search tool when available. Never guess tool names, collection names or argument schemas. `preview` and `confirm` are top-level MCP tools: preview returns free teaser results and an estimated unlock cost; confirm pays to unlock the selected results. Inspect their schemas before use. `get_balance` checks available credit. Follow the user's intended spending scope; setup verification itself needs no paid search. See https://docs.redpine.ai/docs/preview-unlock.md. For other integrations, discover the relevant tool with `find-tools`, inspect it and then call it, or use the client's directly exposed catalog. A sandbox key supports search, preview and confirm fixtures, but other integration tools return `403 SANDBOX_UNSUPPORTED_ENDPOINT`; they require a live key or an appropriately authorized OAuth connection. MCP agents plan their own search steps; REST assisted search is an option for application integrations. ## Before reporting completion State what you connected: the application, your agent client, or both. Name what you actually verified, whether it used sandbox or live access, and any remaining action such as browser approval, client reload or collection access. Do not claim a connection works based only on installing a package or saving configuration. ## REST endpoints | Method | URL | Purpose | |---|---|---| | `POST` | `https://api.redpine.ai/api/v1/search/assisted` | Assisted search (verified results only) | | `GET` | `https://api.redpine.ai/api/v1/search/collections` | List collections | | `GET` | `https://api.redpine.ai/api/v1/search/collections/{name}/journals` | List the journals your key can reach in a collection | | `POST` | `https://api.redpine.ai/api/v1/search/preview` | Preview search results without charging | | `POST` | `https://api.redpine.ai/api/v1/search/query` | Search documents | | `GET` | `https://api.redpine.ai/api/v1/search/quota` | Current quota usage and limits | | `GET` | `https://api.redpine.ai/api/v1/search/results/{queryId}` | Re-fetch cached results | | `POST` | `https://api.redpine.ai/api/v1/search/unlock` | Pay for previewed results and receive them in full | | `POST` | `https://api.redpine.ai/api/v1/search/{collection}` | Search a single collection by name | ## Rules that will save you a failed call - Always call `/api/v1/search/collections` before searching. Collection names cannot be inferred from the topic. - Pass either `collection` (one) or `collections` (an array, **maximum 5**). Not both. - To page through or revisit results, call `/api/v1/search/results/{queryId}` with the `queryId` from the original response. Do not re-run an identical search; it costs again. - Check `/api/v1/search/quota` before a large batch of queries. - Assisted search (`/api/v1/search/assisted`) charges only for delivered, verified results. A clarification request or an honest "no relevant results" answer costs nothing. - Use assisted search when the question needs interpretation. Use `/api/v1/search/query` when you already know what to search for. ## Errors | Status | Meaning | What to do | |---|---|---| | `401` | Missing, invalid or revoked credentials | Check configured credentials; reconnect the MCP client or ask the user to configure a valid key securely. | | `403` | Access denied or unsupported sandbox endpoint | Read the error code. Re-list accessible collections for access errors; sandbox integration tools require live credentials. | | `402` | Insufficient credits | Report the balance issue; do not retry unchanged. | | `404` | Collection or queryId not found | Check the name against the collections list. | | `410` | Cached result or preview expired | Obtain a fresh preview or search, accounting for any cost. | | `422` | Malformed request body | Read the endpoint schema at https://docs.redpine.ai/openapi.json; correct the request before retrying. | | `429` | Rate limited | Back off and retry after the interval in the response headers. | | `500` | Server error | Preserve the request ID and report the failure; do not blindly repeat a potentially billed request. | | `503` | Service temporarily unavailable | Use bounded retries with backoff. | Branch on the error code, not just the HTTP status, and preserve the request ID for support. Official SDKs already retry `429` and `503`; avoid adding an unbounded retry loop around them. Full detail: https://docs.redpine.ai/docs/errors.md ## Going deeper Every documentation page is available as Markdown by appending `.md` to its URL. Fetch only what you need: - https://docs.redpine.ai/docs/assisted-search.md: Agentic retrieval that plans its own searches and verifies every result. - https://docs.redpine.ai/docs/authentication.md: API keys, scoping, and the Bearer token header. - https://docs.redpine.ai/docs/changelog.md: What changed in the API, the dashboard, the SDKs, the CLI and these docs, newest first. - https://docs.redpine.ai/docs/collections.md: List what you can search, and what each collection supports. - https://docs.redpine.ai/docs/errors.md: Every status code, what causes it, and how to fix it. - https://docs.redpine.ai/docs/filtering.md: Narrow results by metadata, dates, and identifiers. - https://docs.redpine.ai/docs/mcp.md: Connect Claude, Cursor, ChatGPT, or any MCP client directly, no code required. - https://docs.redpine.ai/docs/preview-unlock.md: See what a search would return, and what it would cost, before you pay for it. - https://docs.redpine.ai/docs/rate-limits.md: Request limits, quota headers, and handling throttling. - https://docs.redpine.ai/docs/sandbox.md: Build and test your integration without spending credits. - https://docs.redpine.ai/docs/sdks.md: Official Python, TypeScript and Go clients for the Redpine API. - https://docs.redpine.ai/docs/search-endpoints.md: Four ways to search, and how to pick one. - https://docs.redpine.ai/docs/search.md: The core search endpoint: parameters, response shape, and examples. Bulk options: - https://docs.redpine.ai/llms-full.txt: every page in one file. - https://docs.redpine.ai/openapi.json: OpenAPI 3.1.0, for code generation or a typed client. - https://docs.redpine.ai/llms.txt: this site's index.