How to Use the Searchspring MCP in Pydantic AI

Q: How do I configure the Searchspring MCP Server in Pydantic AI?

You initialize the Pydantic AI MCPToolset with your Vinkius HTTP endpoint URL and pass it to your Agent's toolsets parameter. The framework automatically registers Searchspring tools like searchfiltered and handles the underlying JSON schema validation.

Q: Does this setup support asynchronous Searchspring queries?

Yes, the unified MCPToolset integration in Pydantic AI natively supports asynchronous execution. Your agent can run multiple Searchspring catalog queries using searchbrand or searchcategory concurrently without blocking the main event loop.

Force Searchspring catalog data through Pydantic AI validation to guarantee type-safe MCP search results without silent errors.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect Searchspring MCP to Pydantic AI

Create your Vinkius account to connect Searchspring to Pydantic AI — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup Searchspring with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity Vinkius runs on Gemini

Gemini

Grok

Type-Safe Catalog Validation via MCP Server

Silent data corruption ruins e-commerce checkouts. When your Pydantic AI agent calls `search_products` or `search_sku`, the framework validates the incoming Searchspring JSON payload against your strict Python models at runtime. If the Searchspring catalog API suddenly returns an unexpected null value or a string instead of a float for pricing, Pydantic AI catches it instantly. Your application fails loudly and safely before bad Searchspring data can break your frontend.

Strict Pricing and Sorting Enforcement

Let's look at the data. If your Pydantic AI agent uses `search_price_range` or `search_sorted`, you need to be certain the returned Searchspring prices match your internal database types. Pydantic AI guarantees that every Searchspring price field matches your float or Decimal specifications. This strict type checking extends to Searchspring pagination. When the Pydantic AI agent requests the next set of items using `search_pagination`, the page offsets and limits are validated before the model can process them.

Validated Query Suggestions

Autocomplete data is notoriously messy. By routing Searchspring `suggest_queries` through this type-safe Pydantic AI setup, you ensure that every suggested search term conforms to your application's string validation rules. The Pydantic AI agent can safely pass these verified suggestions to other Searchspring tools like `search_filtered` or `search_brand`. This eliminates the risk of injecting malformed search parameters into your downstream Searchspring catalog queries.

Setup guide

Set up Searchspring 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": {
        "searchspring-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

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

result = await agent.run("List recent Searchspring 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 Searchspring. 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 Searchspring 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 Searchspring MCP in Pydantic AI

Pydantic AI guarantees that every JSON payload returned by Searchspring tools like `search_products` conforms to your exact Python type schemas. This prevents your Pydantic AI agent from hallucinating properties or crashing due to unexpected Searchspring API changes.

You initialize the Pydantic AI `MCPToolset` with your Vinkius HTTP endpoint URL and pass it to your Agent's toolsets parameter. The framework automatically registers Searchspring tools like `search_filtered` and handles the underlying JSON schema validation.

The Pydantic AI runtime will immediately raise a validation error. This prevents your agent from displaying incorrect Searchspring pricing to customers or proceeding with a broken checkout state.

Yes, the unified `MCPToolset` integration in Pydantic AI natively supports asynchronous execution. Your agent can run multiple Searchspring catalog queries using `search_brand` or `search_category` concurrently without blocking the main event loop.

The MCP server only handles product SKUs, prices, categories, and search queries within the Pydantic AI runtime. No sensitive customer data or transaction logs are accessed. The server runs inside an ephemeral sandbox, and all traffic is encrypted, meaning your catalog schema remains private.

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