How to Use the Matomo MCP in OpenAI Agents SDK

Q: How do I connect the Matomo MCP Server to my OpenAI Agents SDK pipeline?

You initialize the server using the MCPServerStreamableHttp class with your Vinkius endpoint URL. Pass this instance directly into the agent's mcpservers list during constructor initialization. The SDK automatically discovers all ten analytics tools at runtime.

Q: Can my OpenAI Agents SDK system run parallel queries across multiple sites?

Yes, the SDK handles concurrent async calls to listsites and getvisitssummary without blocking your primary agent thread. You can spin up specialized sub-agents to analyze different web properties simultaneously.

Q: How does the OpenAI Agents SDK handle tool caching for Matomo endpoints?

Set cacheToolsList=True in your SDK server parameters to cache the tool definitions. This prevents the SDK from making redundant schema requests to your Vinkius endpoint, reducing latency on frequent calls to gettoppages.

Feed raw web traffic data directly to your OpenAI Agents SDK workflows with local privacy controls and zero manual API configuration.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Matomo MCP to OpenAI Agents SDK

Create your Vinkius account to connect Matomo to OpenAI Agents SDK 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 Matomo with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Track live visits inside OpenAI Agents SDK.

The `get_live_last_visits` tool feeds real-time visitor activity data directly into your OpenAI Agents SDK runtime. Your agent reads raw session logs, counts active sessions, and triggers automated workflows based on immediate user actions without waiting for daily batch processing. Because the OpenAI Agents SDK manages long-running loops, it uses this fresh stream to adjust system prompts dynamically. This setup ensures your agent makes decisions using real-world traffic patterns rather than stale database dumps.

Validate conversion goals before agent execution.

The `get_goals` tool exposes defined business conversions directly to your agent's decision-making loop. When your OpenAI Agents SDK system triggers a follow-up action, it checks actual conversion history first to prevent redundant customer outreach. Built-in SDK guardrails validate these tool outputs before executing next steps. This check prevents your agent from hallucinating fake conversion milestones or acting on corrupted goal IDs.

Build profiles with this MCP Server.

The `get_visitor_profile` tool fetches complete behavioral histories for individual users to fuel personalized agent interactions. Your OpenAI Agents SDK system parses these detailed profiles to understand specific user intent before generating email replies or chat responses. You can trace these deep database queries directly inside the OpenAI developer dashboard. The combination of this MCP Server and OpenAI tracing gives you complete visibility into how your agent processes raw analytics histories.

Setup guide

Set up Matomo MCP in OpenAI Agents SDK

Prerequisites

Python 3.10+ installed
openai-agents package (pip install openai-agents)
Active Vinkius subscription with a valid endpoint token

1

Install the SDK

Run pip install openai-agents to install the OpenAI Agents SDK. The MCP integration is built-in — no extra dependencies needed.
2

Connect via SSE transport

Use MCPServerSse with your Vinkius endpoint URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. The SDK auto-discovers all Matomo tools at runtime.
3

Create your Agent

Pass the MCP to Agent(mcp_servers=[server]). The agent receives Matomo tools as native definitions — JSON schemas resolve automatically.
4

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate Matomo tools and returns structured results. Copy the full example on the right to get started.

agent.py

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    ) as server:
        agent = Agent(
            name="Matomo Agent",
            instructions="You have access to Matomo tools.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "List recent transactions")
        print(result.final_output)

asyncio.run(main())

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 Matomo. 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 Matomo 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 Matomo MCP in OpenAI Agents SDK

You initialize the server using the `MCPServerStreamableHttp` class with your Vinkius endpoint URL. Pass this instance directly into the agent's `mcp_servers` list during constructor initialization. The SDK automatically discovers all ten analytics tools at runtime.

Yes, the SDK handles concurrent async calls to `list_sites` and `get_visits_summary` without blocking your primary agent thread. You can spin up specialized sub-agents to analyze different web properties simultaneously.

Set `cacheToolsList=True` in your SDK server parameters to cache the tool definitions. This prevents the SDK from making redundant schema requests to your Vinkius endpoint, reducing latency on frequent calls to `get_top_pages`.

No, the agent auto-discovers the schemas directly from the server. When you call tools like `get_top_referrers`, the schema is parsed and validated by the SDK without manual Python code.

Your raw visitor IP and session logs remain inside your self-hosted database. The Vinkius MCP Server acts as an ephemeral proxy, passing the JSON payload directly to your local OpenAI Agents SDK runtime without writing data to external disks.

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