Prema Ananda

Posted on Jul 15

Learning MCP the Hard Way: Building a Python Client for Algolia's MCP Server

#devchallenge #algoliachallenge #ai #mcp

Algolia MCP Server Challenge: Ultimate user Experience

This is a submission for the Algolia MCP Server Challenge

What I Built

I built a conversational AI assistant that lets you interact with Algolia's API using natural language. Instead of writing code or remembering API endpoints, you can simply ask questions like "show me my applications" or "search for 'Interstellar' in the movies index."

The project consists of:

Python MCP Client - A custom implementation to connect with Algolia's MCP server
Gemini-powered Backend - Uses Google's Gemini API to understand user intent and generate API calls
Simple Chat Interface - A clean web UI for testing and demonstration
FastAPI Server - Orchestrates communication between all components

Gemini is the central brain of the system - it dynamically discovers available tools from the MCP server and decides which ones to use based on user requests. The MCP server is just a tool that provides secure, standardized access to Algolia's API.

Demo

📂 Source Code: GitHub Repository Link
🎥 Demo Video:

The demo shows:

Natural language queries being processed by Gemini
Dynamic tool discovery from the MCP server
Real-time responses from Algolia's API

How I Utilized the Algolia MCP Server

The Algolia MCP server serves as a secure, standardized gateway to Algolia's API in my project. Here's how I integrated it:

1. Connection Initialization: The Critical Bridge

The heart of the MCP integration lies in the connection setup. Here's the code that establishes the bridge between Gemini and Algolia:

async def __aenter__(self):
    """Asynchronous entry into the context manager."""
    # Load environment variables (API keys, paths)
    load_dotenv()

    # Configure MCP server startup parameters
    server_params = StdioServerParameters(
        command="node",
        args=[
            "--experimental-strip-types", 
            "--no-warnings=ExperimentalWarning", 
            "src/app.ts"
        ],
        cwd=os.getenv("MCP_NODE_PATH", "d:/mcp-node")
    )

    try:
        # Start MCP server process
        self._mcp_process = stdio_client(server_params)
        read, write = await self._mcp_process.__aenter__()

        # Establish client session for JSON-RPC communication
        self._client_session = ClientSession(read, write)
        self.session = await self._client_session.__aenter__()

        # 🚀 KEY MOMENT: Discover all available tools from Algolia MCP server
        # This is what Gemini will use to decide which actions to take
        self.tools = (await self.session.list_tools()).tools

        print("[INFO] Algolia MCP Client started successfully and is ready.")
        return self

    except FileNotFoundError:
        print(f"[FATAL] Command '{server_params.command}' not found. "
              "Make sure Node.js and MCP CLI are installed.")
        sys.exit(1)

    except Exception as e:
        print(f"[FATAL] Failed to start MCP server: {e}")
        await self.__aexit__(None, None, None)  # Ensure cleanup
        sys.exit(1)

This asynchronous context manager performs these critical steps:

Configuration Loading - Loads environment variables from .env file
Server Parameters Setup - Defines how to launch the Algolia MCP server using Node.js
Connection Establishment - Creates bidirectional communication through stdin/stdout
Dynamic Tool Discovery - This is the key line! self.tools = (await self.session.list_tools()).tools retrieves all available tools from Algolia MCP server
Error Handling - Comprehensive handling for missing Node.js, incorrect paths, or connection issues

2. The MCP Advantage

Using the MCP server instead of direct API calls gave me:

Abstraction: Clean tool interface instead of complex HTTP endpoints
Extensibility: New tools automatically become available to Gemini
Standardization: JSON-RPC protocol for consistent communication

The MCP server acts as a secure middleware layer that transforms Algolia's complex API into simple, discoverable tools that Gemini can understand and use.

The Real Story: Why This Project Exists
This isn't just another demo project. This is a learning tool born out of necessity.
I'm currently working on a much larger project for this same Algolia MCP Server Challenge (which I can't reveal yet 😉), and I needed to understand how MCP actually works under the hood. The problem? MCP is so new that even the LLMs I use for coding assistance don't know much about it yet!
Sure, Algolia's team has an excellent tutorial video showing how to connect their MCP server to Claude Desktop. But what if you want to integrate MCP into your own Python application? What if you need to understand the protocol itself, not just use it through a GUI?
That's where this project comes in. It's a pure Python implementation that does roughly the same thing as the Claude Desktop integration, but gives you full control and understanding of what's happening behind the scenes.

Key Takeaways

Debug subprocess communication between Python and Node.js
Figure out proper process management for the MCP server

Technical Challenges

Challenge 1: Understanding MCP Protocol
MCP uses JSON-RPC 2.0 over stdio, which was completely new to me. I had to learn how to:

Spawn MCP server as subprocess
Communicate through stdin/stdout
Handle async message passing

Challenge 2: Gemini Integration
The real challenge was teaching Gemini to be methodical. I developed a strict prompt that forces Gemini to:

Check for required parameters before calling tools
Ask for missing information instead of guessing

Challenge 3: Process Management
Managing the MCP server lifecycle properly took several iterations:

Proper startup and shutdown procedures
Error handling for subprocess communication

What I Learned

MCP is a paradigm shift - Instead of hardcoding API integrations, we can build systems that dynamically discover and use tools
Gemini is incredibly capable - With proper prompting, it can reliably orchestrate complex API workflows
Documentation matters - New technologies need clear examples and implementation guides
Learning by building - Sometimes the only way to understand something is to implement it yourself

Why This Approach Works

This project demonstrates that Gemini can be the central intelligence for complex API interactions, with MCP providing the secure, standardized tool layer. The combination creates a system that is:

Flexible - Works with any MCP server
Extensible - New tools automatically available to Gemini
User-friendly - Natural language interface for complex APIs

Future Possibilities

This foundation opens up exciting possibilities:

Multi-provider integration - Connect multiple MCP servers
Workflow automation - Chain multiple API calls together

The future of AI-API interaction is conversational, and projects like this show how Gemini + MCP can make it a reality.

Acknowledgments

Special thanks to:

Algolia team for providing excellent MCP server implementation and tutorials
Gemini CLI for writing the core MCP client code and backend logic
Claude 4 Sonnet for creating the frontend interface and helping format this article

Built with curiosity and determination for the Algolia MCP Server Challenge

Top comments (5)

Nikoloz Turazashvili (@axrisi) • Jul 17

If you use models that support structured output you can make your app to be more robust and not break due to LLM limitations. Sometimes LLMs won't send you pure Json as you requested it in your prompt. I guess you faced inconsistence during development.

here is guide from openai
platform.openai.com/docs/guides/st...