Last update: 2026-01-29T22:06:15.000Z
Content:
---
title: "MCP server integration examples · Tinybird Docs"
theme-color: "#171612"
description: "Learn how to integrate the Tinybird MCP server to build AI agents"
inkeep:version: "forward"
---




# AI agent code examples [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#ai-agent-code-examples)

Copy as MD Here are some examples of simple AI agents using Tinybird's MCP Server:

- They are based on the[  web analytics project](https://www.tinybird.co/templates/web-analytics-starter-kit)   but you can adapt it to your own project by using your `TINYBIRD_TOKEN`  .
- Model and libraries set up (such as API keys and other environmental variables) is omitted

Building an agent? Want to know which LLM generates best SQL queries? Explore the results in the [LLM Benchmark](https://llm-benchmark.tinybird.live/).

## Code snippets [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#code-snippets)

### Basic Query Execution with Pydantic AI [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#basic-query-execution-with-pydantic-ai)

import os
from dotenv import load_dotenv
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP
import asyncio

load_dotenv()

tinybird_token = os.getenv('TINYBIRD_TOKEN')
SYSTEM_PROMPT = "YOUR SYSTEM PROMPT"

async def main():
    tinybird = MCPServerStreamableHTTP(
        f"https://mcp.tinybird.co?token={tinybird_token}",
        timeout=120,
    )

    agent = Agent(
        model="anthropic:claude-4-opus-20250514",  # use your favorite model
        mcp_servers=[tinybird],
        system_prompt=SYSTEM_PROMPT
    )

    async with agent.run_mcp_servers():
        result = await agent.run("top 5 pages with the most visits in the last 24 hours")
        print(result.output)


asyncio.run(main())
### Basic Query Execution with Agno [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#basic-query-execution-with-agno)

from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.mcp import MCPTools

import asyncio
import os

tinybird_api_key = os.getenv("TINYBIRD_TOKEN")
SYSTEM_PROMPT = "YOUR SYSTEM PROMPT"

async def main():
    async with MCPTools(
        transport="streamable-http",
        url=f"https://mcp.tinybird.co?token={tinybird_api_key}",
        timeout_seconds=120) as mcp_tools:
        agent = Agent(
            model=Claude(id="claude-4-opus-20250514"),
            tools=[mcp_tools],  # use your favorite model
            instructions=SYSTEM_PROMPT
        )
        await agent.aprint_response("top 5 pages with the most visits in the last 24 hours", stream=True)

if __name__ == "__main__":
    asyncio.run(main())
### Basic Query Execution with Vercel AI SDK [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#basic-query-execution-with-vercel-ai-sdk)

import { anthropic } from "@ai-sdk/anthropic";
import {
  generateText,
  experimental_createMCPClient as createMCPClient,
  type Message,
} from "ai";
import {
  StreamableHTTPClientTransport,
} from "@modelcontextprotocol/sdk/client/streamableHttp";
import * as dotenv from 'dotenv';

dotenv.config();
const SYSTEM_PROMPT = "YOUR SYSTEM PROMPT"

async function main() {
  const messages: Message[] = [{
    id: "1",
    role: "user",
    content: "top 5 pages with more visits in the last 24 hours"
  }];

  const url = new URL(
    `https://mcp.tinybird.co?token=${process.env.TINYBIRD_TOKEN}`
  );

  const mcpClient = await createMCPClient({
    transport: new StreamableHTTPClientTransport(url, {
      sessionId: "session_123",
    }),
  });

  const tbTools = await mcpClient.tools();

  const result = await generateText({
    model: anthropic("claude-3-7-sonnet-20250219"),  // use your favorite model
    messages,
    maxSteps: 5,
    tools: {...tbTools},
    system: SYSTEM_PROMPT
  });

  console.log(result.text);
}

main();
### Advanced Analytics with OpenAI Agents SDK [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#advanced-analytics-with-openai-agents-sdk)

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

SYSTEM_PROMPT = """
You are a data analyst. When analyzing user behavior:
1. First list available endpoints to understand what data is available
2. Use appropriate endpoints or execute_query for analysis
3. Provide insights with specific numbers and trends
4. Suggest actionable recommendations
"""

async def analyze_user_behavior():
    try:
        server = MCPServerStreamableHttp(
            name="tinybird",
            params={
                "url": "https://mcp.tinybird.co?token=TINYBIRD_TOKEN",
            },
        )

        async with server:
            agent = Agent(
                name="user_behavior_analyst", 
                model="YOUR_FAVORITE_MODEL",  # e.g., "openai:gpt-4"
                mcp_servers=[server],
                instructions=SYSTEM_PROMPT
            )
            
            result = await Runner.run(
                agent,
                input="""
                Analyze our user engagement patterns:
                1. What are the current weekly active user trends?
                2. Which features are most popular?
                3. Are there any concerning drops in engagement?
                """
            )
            print("Engagement Analysis:", result.final_output)
            
    except Exception as e:
        print(f"Analysis failed: {e}")

if __name__ == "__main__":
    asyncio.run(analyze_user_behavior())
### Real-time Dashboard Assistant [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#real-time-dashboard-assistant)

import asyncio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

SYSTEM_PROMPT = "YOUR SYSTEM PROMPT"

async def dashboard_assistant():
    server = MCPServerStdio(
        command="npx",
        args=["-y", "mcp-remote", "https://mcp.tinybird.co?token=TINYBIRD_TOKEN"],
    )

    agent = Agent(
        name="dashboard_assistant",
        model=MODEL,  # e.g. "anthropic:claude-3-5-sonnet-20241022",
        mcp_servers=[server],
        system_prompt=SYSTEM_PROMPT
    )

    async with agent.run_mcp_servers():
        while True:
            try:
                user_question = input("\nAsk about your data (or 'quit' to exit): ")
                if user_question.lower() == 'quit':
                    break
                
                result = await agent.run(user_question)
                print(f"Assistant: {result.output}")
                
            except KeyboardInterrupt:
                break
            except Exception as e:
                print(f"Error processing question: {e}")

if __name__ == "__main__":
    asyncio.run(dashboard_assistant())
## Example prompts [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#example-prompts)

Use the prompts from the links below as the `SYSTEM_PROMPT` value in the snippets to build AI agents for your data.

### Tinybird organization metrics [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#tinybird-organization-metrics)

Build AI agents that report summaries on your organization metrics using [service data sources](/forward/monitoring/service-datasources#organization-service-data-sources).

Configure the MCP Server with an Organization Admin Token. You can manage your Tokens in the [Tinybird UI](https://cloud.tinybird.co/tokens).

`https://mcp.tinybird.co?token={organization_admin_token}`

- [  CPU spikes](https://github.com/tinybirdco/ai/blob/main/agents/birdwatcher/missions/cpu_spikes.md)   : Analyzes CPU spikes in your dedicated cluster and finds culprits.
- [  Requests summary](https://github.com/tinybirdco/ai/blob/main/agents/birdwatcher/missions/org_endpoints.md)   : Reports a summary of the requests in your Organization for a given date range.
- [  Ingestion summary](https://github.com/tinybirdco/ai/blob/main/agents/birdwatcher/missions/org_ingestion.md)   : Reports a summary of ingestion in your Organization for a given date range.
- [  Storage summary](https://github.com/tinybirdco/ai/blob/main/agents/birdwatcher/missions/org_storage.md)   : Reports a summary of storage in your Organization for a given date range.

### Tinybird workspace metrics [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#tinybird-workspace-metrics)

Build AI agents that report summaries on metrics for a specific Workspace using [service data sources](/forward/monitoring/service-datasources#service-data-sources).

Configure the MCP server with a Workspace Admin Token. You can manage your Tokens in the [Tinybird UI](https://cloud.tinybird.co/tokens).

`https://mcp.tinybird.co?token={admin_token}`

- [  MCP usage](https://github.com/tinybirdco/ai/blob/main/agents/birdwatcher/missions/mcp_usage.md)   : Reports the most-called Endpoints for a given Workspace by agents using MCP.

### AI agents over your data [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#ai-agents-over-your-data)

Every Endpoint in a Workspace is published as an MCP tool. Use a [resource-scoped token](/docs/forward/administration/tokens) to create AI agents for your data.

Some examples:

- [  PagerDuty incidents](https://github.com/tinybirdco/ai/blob/main/agents/birdwatcher/missions/pagerduty.md)   : Summarizes[  PagerDuty](/forward/get-data-in/guides/ingest-from-pagerduty)   incidents
- [  Plain support summaries](https://github.com/tinybirdco/ai/blob/main/agents/birdwatcher/missions/plain_summary.md)   : Summarizes the most important Plain support issues
- [  Vercel logs](https://github.com/tinybirdco/ai/blob/main/agents/birdwatcher/missions/vercel_logs.md)   : Summarizes errors and metrics from your[  Vercel application logs](/forward/get-data-in/guides/ingest-vercel-logdrains)
- [  Web analytics](https://github.com/tinybirdco/ai/blob/main/agents/birdwatcher/missions/web_analytics.md)   : Summarizes your[  web analytics](https://www.tinybird.co/templates/web-analytics-starter-kit)   metrics.

## Next steps [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp-server-snippets#next-steps)

- Learn[  best practices to build AI agents](/docs/analytics-agents/best-practices)
- Check[  this repository](https://github.com/tinybirdco/ai/tree/main/agents/birdwatcher/missions)   for more examples


