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.

Use this integration when you want AI agents to autonomously query your data, call your analytics endpoints, or build data-based apps without requiring manual API integration.

The Tinybird MCP server only supports Streamable HTTP as the transport protocol. If your MCP client doesn't support it, use the mcp-remote package as a bridge.

Before you start

Before connecting to the Tinybird MCP server, ensure:

  • You have a Tinybird account and workspace
  • Find your Auth Token with appropriate scopes for your use case. See Authentication and Token requirements.
  • Your MCP client supports either Streamable HTTP or can use the mcp-remote bridge

Authentication and Token requirements

Use an Auth Token with the following scopes, depending on which tools you want to access:

Static tokens

Use the admin token to access all available tools or resource-scoped tokens for granular access to endpoint tools.

Copy your static tokens from the dashboard

JSON Web tokens (JWTs)

Use them for granular access to endpoint tools, multi-tenancy, concurrency control and more.

Learn more about authentication tokens here

MCP clients requiring a bridge

For clients that don't support Streamable HTTP natively:

// Get your TINYBIRD_TOKEN from https://cloud.tinybird.co/tokens
{
  "mcpServers": {
    "tinybird": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.tinybird.co?token=TINYBIRD_TOKEN"
      ]
    }
  }
}

All new Tinybird tokens have embedded the Tinybird API host, for old tokens you can provide your API host as a query param https://mcp.tinybird.co?token=TINYBIRD_TOKEN&host=https://api.tinybird.co. Get the list of Tinybird API hosts here

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.

Using JWT tokens with non-default regions

When using JWT tokens, you must specify the host parameter in the URL with your region's API endpoint, as JWT tokens don't contain region information:

https://mcp.tinybird.co?token=JWT_TOKEN&host=https://api.REGION.PROVIDER.tinybird.co

Examples:

  • EU Central 1 (AWS): https://mcp.tinybird.co?token=JWT_TOKEN&host=https://api.eu-central-1.aws.tinybird.co
  • US East 4 (GCP): https://mcp.tinybird.co?token=JWT_TOKEN&host=https://api.us-east.tinybird.co

See Regions and endpoints for the full list of available regions and their API URLs.

Available tools

The token scopes determine which tools are exposed:

Calling endpoints

The MCP server exposes a fixed set of tools. Published API endpoints aren't exposed as individual tools: use list_endpoints to discover them and call_endpoint to run one.

Core tools

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

This tool is only available when the MCP server connects to a tinybird.co host.

execute_query

Runs SQL queries against the Tinybird SQL API

Parameters:

  • sql (string, required): The SQL query to execute
  • response_format (string, optional): The response format. One of CSVWithNames (default), JSON or Markdown. Ignored when explain is true
  • explain (boolean, optional): Return the query plan instead of executing the query
  • explain_settings (string, optional): Comma-separated EXPLAIN options, such as indexes=1,actions=1

Returns: Query results in CSV format by default.

Results are capped: a query without LIMIT returns at most 1000 rows by default, and a LIMIT greater than 10000 is lowered to 10000.

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

call_endpoint

Call a published API endpoint by name. Use list_endpoints first to find endpoint names and accepted parameters.

Parameters:

  • endpoint_name (string, required): The endpoint name, as returned by list_endpoints
  • params (object, optional): The endpoint parameters, by name. Unknown parameter names are rejected
  • response_format (string, optional): The response format. One of CSVWithNames (default), JSON or Markdown

Returns: The endpoint response. The same result limits as execute_query apply to the q parameter.

explore_data

Deprecated. Use list_datasources, list_service_datasources and execute_query instead.

Tool availability by Token scope

ToolJWTadmin token
call_endpointOnly specific endpoints✅
list_endpoints✅✅
list_datasources✅✅
list_service_datasources✅✅
execute_query✅✅
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

Troubleshooting

Workspace not found error with JWT

If you receive an error like:

Error calling TinybirdAPI: invalid authentication token. Workspace with ID ... not found

This typically means you're using a JWT token without specifying the region. JWT tokens don't include region information, so you must add the host parameter to your MCP URL:

https://mcp.tinybird.co?token=JWT_TOKEN&host=https://api.REGION.PROVIDER.tinybird.co

See Using JWT tokens with non-default regions for examples.

See also

Updated