MCP server¶
The Tinybird remote MCP server enables AI agents to connect directly to your workspace to use endpoints as tools or execute queries. The Model Context Protocol gives AI assistants access to your analytics APIs, data sources, and endpoints through a standardized interface.
This integration is ideal when you want AI agents to autonomously query your data, call your analytics endpoints, or build data-driven applications without requiring manual API integration.
Our server only supports Streamable HTTP as the transport protocol. If your MCP client doesn't support it, you'll need to use the mcp-remote
package as a bridge.
Quickstart¶
Get a token and use this URL in your MCP client or agent framework:
https://mcp.tinybird.co?token=TINYBIRD_TOKEN
Replace TINYBIRD_TOKEN
with your actual Auth Token. Use resource-scoped static tokens or JWTs for fine-grained access control.
Available tools¶
Depending on the token scopes, the following tools will be exposed:
Endpoint Tools¶
Every published API endpoint in your workspace becomes an individual tool with the endpoint's name. These tools:
- Accept the same parameters as your endpoint
- Return the same response as direct API calls, by default in CSV format, but JSON format is also supported
- Respect endpoint rate limits and authentication
- Support all parameter types (query parameters, filters, etc.)
Example: If you have an endpoint named daily_active_users
, it becomes a tool named daily_active_users
that accepts the same parameters.
Core Tools¶
explore_data
¶
Ask questions about your data and get answers in natural language. The same advanced exploration agent Tinybird uses internally.
Parameters:
question
(string, required): The question to ask about your data
Returns: A natural language answer to the question
text_to_sql
¶
Convert a natural language question into a SQL query.
Parameters:
question
(string, required): The question to convert into a SQL query
Returns: A SQL query
execute_query
¶
Runs SQL queries against the Tinybird SQL API
Parameters:
sql
(string, required): The SQL query to executeformat
(string, optional): The response format, default is CSVWithNames but other formats are supported
Returns: Query results in CSV format by default.
list_datasources
¶
List all data sources in your workspace.
Parameters: None
Returns: Array of data source objects with names, schemas, and metadata
list_service_datasources
¶
List all organization and tinybird service data sources that are available to your workspace.
Parameters: None
Returns: Array of service data source objects with names, schemas, and metadata
list_endpoints
¶
List all published API endpoints in your workspace.
Parameters: None
Returns: Array of endpoint objects with names, parameters, and descriptions
Tool Availability by Token Scope¶
Tool | JWT | admin token |
---|---|---|
Endpoint tools | Only specific endpoint | ✅ |
list_endpoints | ✅ | ✅ |
list_datasources | ✅ | ✅ |
list_service_datasources | ✅ | ✅ |
execute_query | ✅ | ✅ |
explore_data | ✅ | ✅ |
text_to_sql | ✅ | ✅ |
When to use MCP vs Direct API Integration¶
Use MCP when:
- Building AI agents that need autonomous access to your analytics
- Creating conversational interfaces for data exploration
- Developing AI-powered dashboards or reports
- Prototyping data analysis workflows with AI assistance
Use direct API integration when:
- Building production applications with predictable query patterns
- Need maximum performance and minimal latency
- Require fine-grained control over API calls and caching
MCP Monitoring¶
Monitor SQL queries executed by AI agents for unexpected patterns, using Tinybird service data sources.
SELECT * FROM tinybird.pipe_stats_rt WHERE url LIKE '%from=mcp%' AND start_datetime > now() - INTERVAL 1 HOUR
See also¶
- Auth Tokens - Learn about creating and managing authentication tokens
- API Endpoints - Understand how to create and publish endpoints
- Query API - Direct API access for comparison with MCP usage
- Model Context Protocol Documentation - Official MCP specification and guides