Algolia DocSearch

The Algolia DocSearch MCP Plugins allow AI coding clients to connect to the public DocSearch documentation corpus via the Model Context Protocol (MCP). These plugins enable AI agents to search and retrieve documentation content using natural language queries.

Key constraints:

• They connect to the public endpoint: https://mcp.algolia.com/1/docsearch/mcp.
• They do not expose crawler operations, DocSearch administration, private documentation, or Algolia index credentials.
• No user authentication is required for the public endpoint.

Hybrid mode connects the DocSearch keyword search modal with the Ask AI Sidepanel experience. It allows users to start an AI interaction within the search modal (scanning keyword results) and then seamlessly transition that conversation into a Sidepanel for a continuous, side-by-side experience.

During the handoff, the prompt and its identifiers are carried over so the conversation context is preserved. The handoff uses an InitialAskAiMessage object containing:

• query: The text of the prompt.
• messageId: An optional ID used to restore a locally stored conversation.
• suggestedQuestionId: An optional ID used to identify which suggested question was selected in Agent Studio.

To ensure a good user experience, Hybrid mode behaves differently on mobile devices (viewports matching (max-width: 768px)):

• React: The DocSearch provider automatically detects mobile viewports. On mobile, Ask AI actions stay within the modal instead of moving to the Sidepanel. This prevents the conversation from being forced into a desktop-oriented layout. The decision is updated on window resize.
• JavaScript: The JavaScript packages do not share a provider, so they do not apply this mobile logic automatically. If you want consistent behavior, you must manually implement a matchMedia check within your interceptAskAiEvent callback, as shown in the JavaScript integration guide.
• Sidepanel Focus: On mobile, the Sidepanel avoids automatically focusing the prompt to prevent the virtual keyboard from disrupting the layout.

You should use one Algolia application per project. If you have an additional project, you must apply to the DocSearch program separately for it.

Using separate applications ensures that the following are correctly scoped:

• API key scope
• Crawler name and Algolia application name
• Generated indices
• Allowed domains for the Crawler

DocSearch v5 automatically includes feedback controls for completed Agent Studio answers.

• Positive Feedback (Thumbs up): Submits immediately with a value of { thumbs: 1 }.
• Negative Feedback (Thumbs down): Opens a form where users can select zero or more reason tags and an optional note. The payload structure is:

  {
    thumbs: 0;
    tags?: AskAiFeedbackReason[];
    notes?: string;
  }

Constraints and Behavior:

• Reason tags and notes are only collected for negative feedback.
• Notes are trimmed, omitted if empty, and limited to 1,000 characters.
• Submitting without a reason or note is valid.
• Closing or canceling the form does not submit feedback.
• To enable feedback, use an API key with the search ACL. You do not need to explicitly add an askAi option to enable the controls themselves.

DocSearch uses heading hierarchy to build hierarchy.lvl0 through hierarchy.lvl6. This structure is used to improve result relevance and, in v5, to render result breadcrumbs.

Best Practices:

• Use an ordered heading hierarchy (e.g., <h1> through <h6>).
• Avoid skipping levels to ensure each result retains its page context.
• For large pages, aim for at least three levels of depth (e.g., lvl0 to lvl3).
• If you don't use standard <hX> elements, you can use classes like <span class="title-X"> to represent hierarchy.

Security and Sharing

The apiKey provided by the DocSearch team is a search-only API key. It is safe to include this key in your public repository and version control.

Warning: If you decide to run the scraper yourself, ensure you create a search-only key and never share your Admin API key.

Key Differences

Every Algolia application has a default "Search API Key" in the dashboard that can list indices and retrieve settings. However, for DocSearch applications, the acceptance email contains a specific search-only API key scoped strictly to your DocSearch index. If you lose this key, you must contact Algolia support.

Key Rotation

To rotate your API keys, you must contact Algolia support.