How to Use the Elasticsearch Vector MCP in Pydantic AI

Q: How does Pydantic AI ensure correctness when searching Elasticsearch Vector?

When your agent calls the search tool, Pydantic AI intercepts the JSON response from the server. It then validates that response against a predefined Pydantic model. If the data doesn't match the model's schema, it raises an error instead of passing bad data to your agent.

Q: Can I use Pydantic AI to build a resilient workflow for managing indexes in Elasticsearch Vector?

Absolutely. You can define a workflow where the agent uses getindex to check an index's mapping, and because the response is validated, you can trust the result. Based on that trusted data, the agent can then decide whether to createindex or modify its indexdocument calls.

Add type-safe Elasticsearch vector search to your Pydantic AI agent and get validated, predictable results every time.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Elasticsearch Vector MCP to Pydantic AI

Create your Vinkius account to connect Elasticsearch Vector to Pydantic AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Elasticsearch Vector with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Get Type-Safe Search Results

The `search` tool finds documents in Elasticsearch using k-NN. When you use it with Pydantic AI, the response is automatically parsed and validated against a Pydantic model. If Elasticsearch returns an unexpected field or data type, your code will raise a `ValidationError` immediately. This means no more silent failures or corrupted data downstream. Your agent either gets exactly the data structure it expects from a search, or it stops. This is critical for building reliable systems where data integrity is non-negotiable.

Manage Indexes with Pydantic AI's Guarantees

When your agent calls `create_index` or `index_document`, the inputs you provide are validated first. Pydantic AI ensures you're sending well-structured data to this MCP server, catching errors before they even hit your Elasticsearch cluster. The same applies to reading data. The output of `get_index` is checked against a strict schema. This lets your agent confidently inspect index mappings, knowing the data structure is correct and not some hallucinated guess from the LLM.

Build Model-Agnostic Search Agents

Pydantic AI doesn't care if you're using OpenAI, Gemini, or a local model. You can connect this Elasticsearch MCP Server to any of them. The tools `list_indexes`, `index_document`, and `delete_document` will work the same way. This lets you build a core search-and-retrieval logic that's portable. If you decide to switch LLM providers, you don't have to rewrite how your agent interacts with its Elasticsearch knowledge base. The Pydantic AI toolset provides a stable, predictable interface.

Setup guide

Set up Elasticsearch Vector MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "elasticsearch-vector-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to Elasticsearch Vector tools.",
)

result = await agent.run("List recent Elasticsearch Vector transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Elasticsearch Vector. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Elasticsearch Vector now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Elasticsearch Vector MCP in Pydantic AI

When your agent calls the `search` tool, Pydantic AI intercepts the JSON response from the server. It then validates that response against a predefined Pydantic model. If the data doesn't match the model's schema, it raises an error instead of passing bad data to your agent.

Pydantic AI will likely catch it on the client side before the request is even sent. The `index_document` tool's input is also typed. If you try to pass data that doesn't fit the expected model, you'll get a local `ValidationError`.

Absolutely. You can define a workflow where the agent uses `get_index` to check an index's mapping, and because the response is validated, you can trust the result. Based on that trusted data, the agent can then decide whether to `create_index` or modify its `index_document` calls.

Yes. The MCP server connection is independent of the LLM you use. As long as your Pydantic AI agent is configured with the `MCPToolset`, it can call the Elasticsearch tools regardless of which model is driving the agent's logic.

Your data, including the contents of documents you index and the vectors you search with, is streamed through a sandboxed Vinkius environment directly to your Elasticsearch instance. The server is stateless; we don't save or inspect your payloads. Your access is controlled by a single, revocable API token.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript