Last update: 2026-01-29T22:06:15.000Z
Content:
---
title: "MCP server · Tinybird Docs"
theme-color: "#171612"
description: "The Tinybird remote MCP server enables AI agents to connect directly to your Tinybird workspace to execute queries or use your endpoints as tools."
inkeep:version: "forward"
---




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

Copy as MD 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](https://modelcontextprotocol.io/) 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.

## Before you start [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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. Details below.
- Your MCP client supports either Streamable HTTP or can use the `mcp-remote`   bridge

### Authentication and Token Requirements [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#authentication-and-token-requirements)

You'll need 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](https://cloud.tinybird.co/tokens)

**JSON Web tokens (JWTs)**

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

Learn more about authentication tokens [here](/docs/administration/tokens)

### MCP clients requiring a bridge [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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](/api-reference#current-tinybird-regions)

## Quickstart [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#quickstart)

Get a [token](https://cloud.tinybird.co/tokens) 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 [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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](/docs/api-reference#regions-and-endpoints) for the full list of available regions and their API URLs.

## Available tools [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#available-tools)

Depending on the token scopes, the following tools will be exposed:

### Endpoint Tools [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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 [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#core-tools)

####  `explore_data` [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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` [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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` [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#execute_query)

Runs SQL queries against the Tinybird SQL API

**Parameters:**

- `sql`   (string, required): The SQL query to execute
- `format`   (string, optional): The response format, default is CSVWithNames but[  other formats](/docs/api-reference/query-api#id2)   are supported

**Returns:** Query results in CSV format by default.

####  `list_datasources` [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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` [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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` [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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 [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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 [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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 [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#mcp-monitoring)

Monitor SQL queries executed by AI agents for unexpected patterns, using [Tinybird service data sources](/docs/monitoring/service-datasources).

SELECT *
FROM tinybird.pipe_stats_rt
WHERE url LIKE '%from=mcp%'
AND start_datetime > now() - INTERVAL 1 HOUR
## Troubleshooting [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#troubleshooting)

### Workspace not found error with JWT [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#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](https://www.tinybird.co/docs/forward/analytics-agents/mcp#using-jwt-tokens-with-non-default-regions) for examples.

## See also [¶](https://www.tinybird.co/docs/forward/analytics-agents/mcp#see-also)

- [  Auth Tokens](/docs/administration/tokens)   - Learn about creating and managing authentication tokens
- [  API Endpoints](/docs/forward/work-with-data/publish-data/endpoints)   - Understand how to create and publish endpoints
- [  Query API](/docs/api-reference/query-api)   - Direct API access for comparison with MCP usage
- [  Model Context Protocol Documentation](https://modelcontextprotocol.io/)   - Official MCP specification and guides


