MCP¶

The Tinybird remote MCP server lets AI agents query your Workspace and use published API Endpoints as tools. MCP stands for Model Context Protocol, a standard interface for exposing tools and context to agents.

Use MCP when you want an agent to explore data, call analytics Endpoints, or answer questions over Tinybird data without writing a custom API integration.

Before you start¶

You need:

• A Tinybird account and Workspace.
• A Token with the scopes required by the tools you want to expose.
• An MCP client that supports Streamable HTTP, or a client that can run mcp-remote.

Connect to the MCP server¶

Use this URL in your MCP client:

https://mcp.tinybird.co?token=TINYBIRD_TOKEN

Replace TINYBIRD_TOKEN with a Tinybird Token.

Use a resource-scoped static Token or a JWT when you want to restrict which Endpoints or Data Sources the agent can access. Use an admin Token only for trusted internal tools.

Clients that need a bridge¶

For MCP clients that do not support Streamable HTTP directly, configure mcp-remote:

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

JWTs and non-default regions¶

JWTs do not contain region information. When you use a JWT outside the default region, include the host parameter:

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.

Authentication and Token scopes¶

The tools exposed by the MCP server depend on the Token scopes.

Use static Tokens for backend and internal tools. An admin Token exposes all available tools. Resource-scoped Tokens expose only the resources allowed by the Token.

Use JWTs for user-facing or multi-tenant agents. JWTs can restrict access to specific Endpoints, add fixed parameters, filter Data Sources, and set rate limits. See Tokens and JWTs.

Available tools¶

The MCP server exposes Endpoint tools and core tools.

Endpoint tools¶

Every published API Endpoint in your Workspace can become a tool with the Endpoint name.

Endpoint tools:

• Accept the same parameters as the Endpoint.
• Return the same response as direct API calls.
• Return CSV by default. JSON is also supported.
• Respect Endpoint rate limits and Token scopes.

For example, an Endpoint named daily_active_users becomes a tool named daily_active_users.

Core tools¶

explore_data

: Ask questions about your data and get a natural language answer.

text_to_sql

: Convert a natural language question into a SQL query.

execute_query

: Run SQL against the Tinybird Query API. The sql parameter is required. The optional format parameter controls the response format. The default is CSVWithNames.

list_datasources

: List Data Sources in your Workspace.

list_service_datasources

: List Organization and Tinybird service Data Sources available to your Workspace.

list_endpoints

: List published API Endpoints with names, parameters, and descriptions.

Use MCP or direct APIs¶

Use MCP when:

• You are building an AI agent that needs access to analytics data.
• You want a conversational interface over Data Sources or Endpoints.
• You are prototyping data analysis workflows with an LLM.
• You want Endpoints to become tools without writing tool wrappers.

Use direct APIs when:

• You are building a production application with fixed query patterns.
• You need the lowest possible latency.
• You need custom caching, retries, observability, or request handling.

Monitor MCP usage¶

MCP requests include from=mcp. Use Tinybird service Data Sources to monitor queries executed by agents.

SELECT *
FROM tinybird.pipe_stats_rt
WHERE url LIKE '%from=mcp%'
AND start_datetime > now() - INTERVAL 1 HOUR

See Service Data Sources.

Troubleshooting¶

Workspace not found with a JWT¶

If you receive an error like this:

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

You might be using a JWT without a host parameter. JWTs do not include region information. Add the regional API host to the MCP URL:

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

See JWTs and non-default regions.

See also¶

• Tokens
• API Endpoints
• Query API
• Model Context Protocol documentation