How to integrate Algolia MCP with Pydantic AI

Connect Pydantic AI to Algolia MCP. Export all records from products index, clear all objects from blog_posts index, and more using natural language, with authentication handled for you.

Algolia logoAlgolia
Api Key

Algolia is a hosted search API that powers lightning-fast, relevant search experiences for web and mobile apps. It helps developers deliver instant, typo-tolerant, and scalable search without complex infrastructure.

127 Tools

Introduction

This guide walks you through connecting Algolia to Pydantic AI using the Composio tool router. By the end, you'll have a working Algolia agent that can search your indices, add and update records, configure synonyms and rules, run A/B tests, and review search analytics through natural language commands.

This guide will help you understand how to give your Pydantic AI agent real control over a Algolia account through Composio's Algolia MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

For exact tool slugs and parameter tables, see the tool catalog in the Composio docs.

Also integrate Algolia with

TL;DR

Here's what you'll learn:
  • How to set up your Composio API key and User ID
  • How to create a Composio Tool Router session for Algolia
  • How to attach an MCP Server to a Pydantic AI agent
  • How to stream responses and maintain chat history
  • How to build a simple REPL-style chat interface to test your Algolia workflows

What is Pydantic AI?

Pydantic AI is a Python framework for building AI agents with strong typing and validation. It leverages Pydantic's data validation capabilities to create robust, type-safe AI applications.

Key features include:

  • Type Safety: Built on Pydantic for automatic data validation
  • MCP Support: Native support for Model Context Protocol servers
  • Streaming: Built-in support for streaming responses
  • Async First: Designed for async/await patterns

What is the Algolia MCP server, and what's possible with it?

The Algolia MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Algolia account. It provides structured and secure access to your search indexes, records, ingestion resources, tests, and analytics events, so your agent can find records, update index content, configure ingestion, manage tests, and record user interactions on your behalf.

  • Index and record management: Have your agent browse indexes, find and retrieve records, add or replace content, delete matching records, copy indexes, or run batch operations across multiple indexes.
  • Search testing and configuration: Let the agent create, inspect, and delete A/B tests, manage query suggestion configurations, and create or update recommendation rules.
  • Ingestion setup: Direct your agent to create and manage data sources, destinations, transformations, and ingestion tasks that move content into Algolia.
  • Rules and synonyms cleanup: Instruct your agent to export search rules, remove selected rules or synonyms, or clear all rules and synonyms from an index.
  • Analytics event tracking: Have your agent record clicked items, clicks following searches, and conversion events for items outside a search context.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
1

Prerequisites

Before starting, make sure you have:
  • Python 3.9 or higher
  • A Composio account with an active API key
  • Basic familiarity with Python and async programming
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key. You'll need credits to use the models, or you can connect to another model provider.
  • Keep the API key safe.
Composio API Key
  • Log in to the Composio dashboard.
  • Navigate to your API settings and generate a new API key.
  • Store this key securely as you'll need it for authentication.
3

Install dependencies

bash
pip install composio pydantic-ai python-dotenv

Install the required libraries.

What's happening:

  • composio connects your agent to external SaaS tools like Algolia
  • pydantic-ai lets you create structured AI agents with tool support
  • python-dotenv loads your environment variables securely from a .env file
4

Set up environment variables

bash
COMPOSIO_API_KEY=your_composio_api_key_here
USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key

Create a .env file in your project root.

What's happening:

  • COMPOSIO_API_KEY authenticates your agent to Composio's API
  • USER_ID associates your session with your account for secure tool access
  • OPENAI_API_KEY to access OpenAI LLMs
5

Import dependencies

python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()
What's happening:
  • We load environment variables and import required modules
  • Composio manages connections to Algolia
  • MCPServerStreamableHTTP connects to the Algolia MCP server endpoint
  • Agent from Pydantic AI lets you define and run the AI assistant
6

Create a Tool Router Session

python
async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Algolia
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["algolia"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an MCP URL")
What's happening:
  • We're creating a Tool Router session that gives your agent access to Algolia tools
  • The create method takes the user ID and specifies which toolkits should be available
  • The returned session.mcp.url is the MCP server URL that your agent will use
7

Initialize the Pydantic AI Agent

python
# Attach the MCP server to a Pydantic AI Agent
algolia_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
agent = Agent(
    "openai:gpt-5",
    toolsets=[algolia_mcp],
    instructions=(
        "You are a Algolia assistant. Use Algolia tools to help users "
        "with their requests. Ask clarifying questions when needed."
    ),
)
What's happening:
  • The MCP client connects to the Algolia endpoint
  • The agent uses GPT-5 to interpret user commands and perform Algolia operations
  • The instructions field defines the agent's role and behavior
8

Build the chat interface

python
# Simple REPL with message history
history = []
print("Chat started! Type 'exit' or 'quit' to end.\n")
print("Try asking the agent to help you with Algolia.\n")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() in {"exit", "quit", "bye"}:
        print("\nGoodbye!")
        break
    if not user_input:
        continue

    print("\nAgent is thinking...\n", flush=True)

    async with agent.run_stream(user_input, message_history=history) as stream_result:
        collected_text = ""
        async for chunk in stream_result.stream_output():
            text_piece = None
            if isinstance(chunk, str):
                text_piece = chunk
            elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                text_piece = chunk.delta
            elif hasattr(chunk, "text"):
                text_piece = chunk.text
            if text_piece:
                collected_text += text_piece
        result = stream_result

    print(f"Agent: {collected_text}\n")
    history = result.all_messages()
What's happening:
  • The agent reads input from the terminal and streams its response
  • Algolia API calls happen automatically under the hood
  • The model keeps conversation history to maintain context across turns
9

Run the application

python
if __name__ == "__main__":
    asyncio.run(main())
What's happening:
  • The asyncio loop launches the agent and keeps it running until you exit

Complete Code

Here's the complete code to get you started with Algolia and Pydantic AI:

python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()

async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Algolia
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["algolia"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an MCP URL")

    # Attach the MCP server to a Pydantic AI Agent
    algolia_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
    agent = Agent(
        "openai:gpt-5",
        toolsets=[algolia_mcp],
        instructions=(
            "You are a Algolia assistant. Use Algolia tools to help users "
            "with their requests. Ask clarifying questions when needed."
        ),
    )

    # Simple REPL with message history
    history = []
    print("Chat started! Type 'exit' or 'quit' to end.\n")
    print("Try asking the agent to help you with Algolia.\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() in {"exit", "quit", "bye"}:
            print("\nGoodbye!")
            break
        if not user_input:
            continue

        print("\nAgent is thinking...\n", flush=True)

        async with agent.run_stream(user_input, message_history=history) as stream_result:
            collected_text = ""
            async for chunk in stream_result.stream_output():
                text_piece = None
                if isinstance(chunk, str):
                    text_piece = chunk
                elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                    text_piece = chunk.delta
                elif hasattr(chunk, "text"):
                    text_piece = chunk.text
                if text_piece:
                    collected_text += text_piece
            result = stream_result

        print(f"Agent: {collected_text}\n")
        history = result.all_messages()

if __name__ == "__main__":
    asyncio.run(main())

Conclusion

You've built a Pydantic AI agent that can interact with Algolia through Composio's Tool Router. With this setup, your agent can perform real Algolia actions through natural language. You can extend this further by:
  • Adding other toolkits like Gmail, HubSpot, or Salesforce
  • Building a web-based chat interface around this agent
  • Using multiple MCP endpoints to enable cross-app workflows (for example, Gmail + Algolia for workflow automation)
This architecture makes your AI agent "agent-native", able to securely use APIs in a unified, composable way without custom integrations.
TOOLS

Supported Tools

Every Algolia action and event your agent gets out of the box.

Add AB Test

Tool to create an A/B test comparing search performance between two index variants.

Add or Replace Record

Tool to add or replace a specific record in an index by objectID.

Add Record to Index

Tool to add a record to an index with auto-generated objectID.

Browse Algolia Index

Browse a batch of records in an Algolia index, optionally filtering them by query or browse parameters.

Clear Objects

Tool to clear records of an index without affecting settings.

Clear Rules

Clear all rules from an Algolia index, optionally forwarding the operation to replica indices.

Clear Synonyms

Clear all synonyms from an Algolia index, optionally forwarding the operation to replica indices.

Clicked Object IDs

Tool to send a click event to Algolia to capture clicked items.

Clicked Object IDs After Search

Tool to send a click event after a search response.

Converted Object IDs

Tool to send a conversion event for items outside of search context.

Copy Index

Initiate an index copy and return an asynchronous task ID.

Create API Key

Tool to create a new API key with specific permissions and restrictions.

Create Authentication

Create an authentication resource in the US region of Algolia's ingestion API for connecting to sources or destinations.

Create Destination

Create a destination for data ingestion using the US Algolia Ingestion API endpoint.

Create Ingestion Task

Create an ingestion task connecting a source to a destination for data synchronization with an Algolia index.

Create or Update Recommend Rules

Tool to create or update a batch of Recommend Rules in an index.

Create Query Suggestions Config

Tool to create a new Query Suggestions configuration for an Algolia index.

Create Source

Tool to create a new data source in Algolia Ingestion API.

Create Transformation

Tool to create a new transformation in Algolia Ingestion API.

Delete AB Test

Tool to delete an A/B test by its unique identifier.

Delete API Key

Delete an Algolia API key to revoke access.

Delete Authentication

Delete an Algolia ingestion authentication resource by ID in the US region.

Delete Query Suggestions Config

Tool to delete a Query Suggestions configuration for the specified index.

Delete Destination

Delete a destination by ID using the US Algolia Ingestion API endpoint.

Delete Index

Tool to delete the specified index and all its records.

Delete Multiple Records

Tool to delete multiple records from an Algolia index.

Delete Recommend Rule

Tool to delete a Recommend rule from a recommendation scenario.

Delete Records by Filter

Tool to delete records matching a filter from an Algolia index.

Delete Rule

Tool to delete the specified rule from an index.

Delete Source

Delete an Algolia Ingestion API source by ID.

Delete Synonym

Tool to delete a synonym from a specified index.

Delete Transformation

Tool to delete a transformation in Algolia Ingestion API.

Delete User Profile

Tool to delete a user profile from personalization.

Delete User Token

Delete events related to a user token from Algolia Insights event metrics and analytics using the US Insights endpoint.

Batch Operations on Multiple Indices

Tool to perform batch operations (add, update, delete) across multiple Algolia indices in a single request.

Export Rules

Export a page of rules from an Algolia index for backup or migration.

Find Object

Tool to find the first object matching a query or filter in an index.

Get A/B Test

Retrieve an A/B test by ID from the DE analytics region, including its status, performance metrics, and configuration details.

Get Add to Cart Rate

Tool to retrieve add-to-cart rate metrics for e-commerce search analytics.

Get API Key

Tool to retrieve the permissions and details of a specific API key.

Get App Task Status

Tool to check the status of an application task.

Get Authentication

Tool to retrieve an authentication resource by its ID.

Get Average Click Position

Tool to retrieve average click position metrics from Algolia Analytics.

Get Click Positions

Tool to retrieve the distribution of clicks by position from Algolia Analytics.

Get Click Through Rate

Tool to retrieve click-through rate (CTR) for searches with at least one click event.

Get Query Suggestions Config

Tool to retrieve a Query Suggestions configuration by index name.

Get Personalization Config

Retrieve the advanced personalization configuration from the EU endpoint, including personalization settings, re-ranking impact and profile type.

Get Conversion Rate

Retrieve conversion rate analytics for an index from the US analytics endpoint, including daily breakdowns.

Get Destination

Retrieve an Algolia ingestion destination by ID using the US endpoint.

Get Dictionary Languages

Tool to list available languages for dictionary entries.

Get Dictionary Settings

Tool to retrieve dictionary settings for all dictionaries.

Get Logs

Tool to retrieve log entries for API requests made to your Algolia application.

Get No Click Rate

Retrieve aggregate and daily no-click rates for tracked searches on an index, with optional date and tag filters.

Get No Results Rate

Retrieve aggregate and daily no-results rates for an index using the US analytics endpoint.

Get No Results Searches

Retrieve frequent searches that produced zero results for an index using the US analytics endpoint.

Get Object Position

Find an object’s zero-based position by objectID in the hits of a supplied search response.

Get multiple objects

Tool to retrieve multiple records from an index.

Get Purchase Rate

Retrieve purchase rate metrics for an index, including daily breakdowns, from the US analytics region.

Get Recommend Rule

Tool to retrieve a Recommend rule that was previously created in the Algolia dashboard.

Get Recommend Task Status

Tool to check the status of a Recommend task.

Get Record from Index

Tool to retrieve a specific record from an index by its objectID.

Get Revenue

Retrieve search-related revenue data from Algolia Analytics using the US regional endpoint.

Get Rule

Tool to retrieve a specific rule by its objectID from an index.

Get Searches Count

Retrieve search counts for an index over a time range, including a daily breakdown, using the US regional Analytics endpoint.

Get Searches No Clicks

Retrieve top searches without clicks from Algolia Analytics using the US regional endpoint, to help identify queries that may need optimization.

Get Index Settings

Retrieve selected settings for a specified Algolia index to inspect its configuration.

Get Source

Tool to retrieve a source from the Algolia Ingestion API.

Get Synonym

Tool to retrieve a specific synonym by its objectID.

Get Task Status

Tool to check the status of an asynchronous task.

Get Top Countries

Retrieve top countries by search volume for a specified index using the US analytics endpoint, to analyze the geographic distribution of searches.

Get Top Filter Attributes

Tool to retrieve top filter attributes from Algolia Analytics.

Get Top Filter For Attribute

Tool to retrieve top filter values for a specific attribute from Algolia Analytics.

Get Top Filters No Results

Tool to retrieve top filters for searches that returned no results from Algolia Analytics.

Get Top Hits

Tool to retrieve the object IDs of the most frequent search results from Algolia Analytics.

Get Top Searches

Retrieve popular search queries from Algolia Analytics, with optional click analytics and revenue metrics.

Get Transformation

Tool to retrieve a transformation by its ID from Algolia's Ingestion API.

Get Usage Statistics

Tool to retrieve Algolia usage statistics over a specified time period.

Get Usage for Index

Retrieve usage statistics for a specific Algolia index over a time period, with hourly or daily aggregation, including metrics such as record counts, query volumes, and processing times.

Get Users

Retrieve user profiles and affinities from Algolia advanced personalization using the EU endpoint.

Get Users Count

Retrieve the number of unique users for an index over a time range, including a daily breakdown, using the US Algolia Analytics endpoint.

Index Exists

Tool to check if an Algolia index exists.

Init Insights API Client

Return Insights client configuration for a selected region, including the application ID, API key, host, and cookie-setting metadata.

List AB Tests

List a page of A/B tests for the application in the DE analytics region, with optional index prefix or suffix filters.

List API Keys

List the application's main API keys with their permissions and restrictions for access-control review.

List Authentications

List a page of Algolia ingestion authentication resources in the US region, with optional type and platform filters.

List Destinations

List a page of Algolia ingestion destinations using the US endpoint, optionally filtering by type, authentication ID or transformation ID.

List Indices

Tool to list all indices and their metadata.

List Ingestion Tasks

List ingestion tasks using the US ingestion endpoint.

List Query Suggestions Configurations

Tool to retrieve all Query Suggestions configurations for an Algolia application.

List Task Runs

List Algolia Ingestion task runs using the US regional endpoint.

List Sources

Tool to list sources from the Algolia Ingestion API.

List Transformations

Tool to list all transformations in Algolia Ingestion API.

Partial Update Objects

Partially update multiple records in an index by objectID without replacing entire records.

Push Records to Task

Push records and a selected indexing action to a configured ingestion task by task ID, including actions to delete records, clear an index, or delete an index.

Replace All Rules

Batch save rules in an index, replacing existing rules by default.

Replace Task

Replace an Algolia Ingestion task with new configuration using the US regional API endpoint.

Restore API Key

Tool to restore a deleted API key within 72 hours of deletion.

Save Rule

Tool to create or replace a rule in an index.

Save Synonym

Tool to add or update a synonym in the specified index.

Save Synonyms

Batch create or replace synonyms in an Algolia index.

Search Authentications

Tool to search for authentication resources by IDs in Algolia.

Search Destinations

Search for multiple Algolia ingestion destinations by their IDs using the US endpoint.

Search Dictionary Entries

Tool to search dictionary entries in Algolia dictionaries.

Search Facet Values

Tool to search for values of a specified facet attribute.

Search Algolia Index

Tool to perform a search on a specified Algolia index.

Search Multiple Indices

Tool to perform searches across multiple indices in a single call.

Search Recommend Rules

Search Recommend rules in a specified index and model.

Search Sources

Search for multiple Algolia Ingestion API sources by their IDs using the US ingestion endpoint.

Search Synonyms

Search synonyms in a specified Algolia index, optionally matching a query or filtering by synonym type.

Search Transformations

Tool to search for transformations by IDs in Algolia Ingestion API.

Set Dictionary Settings

Tool to update dictionary settings for Algolia.

Set Personalization Strategy

Tool to define personalization strategy that controls how user behavior affects search results.

Set Index Settings

Tool to update an Algolia index's settings.

Stop AB Test

Tool to stop an A/B test by its unique identifier.

Try Transformation

Tool to try a transformation before creating it in Algolia.

Try Transformation Before Update

Tool to test a transformation before updating it in Algolia Ingestion API.

Update API Key

Tool to update the permissions and settings of an existing API key.

Update Authentication

Update the name or credentials of an Algolia ingestion authentication resource in the US region.

Update Query Suggestions Config

Tool to update an existing Query Suggestions configuration.

Update Destination

Update an Algolia ingestion destination using the US endpoint, including its configuration, name, type or associated transformations.

Update Dictionary Entries

Batch add or delete entries in an Algolia stopwords, plurals, or compounds dictionary.

Update Record Partially

Tool to add or update attributes in a single record.

Update Source

Tool to update a source in the Algolia Ingestion API.

Update Task

Partially update an Algolia Ingestion API task using the US ingestion endpoint.

Update Transformation

Tool to update an existing transformation in Algolia Ingestion API.

Validate Source

Tool to validate a source payload before creating it in Algolia.

Validate Source Before Update

Tool to validate a source update payload in the Algolia Ingestion API.

FAQ

Frequently asked questions

Start with Algolia.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Algolia tool your agent needs.Free to start.

Start building