---
title: MCP server
tags: analytics-agents
meta:
    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.
---

# 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](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.

{% callout type="info" %}
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.
{% /callout %}

## 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

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.

{% callout type="info" %}
Learn more about authentication tokens [here](/administration/tokens)
{% /callout %}

### MCP clients requiring a bridge

For clients that don't support Streamable HTTP natively:

```json
// 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"
      ]
    }
  }
}
```

{% callout type="info" %}
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](https://www.tinybird.co/docs/api-reference#current-tinybird-regions)
{% /callout %}


## Quickstart

Get a [token](https://cloud.tinybird.co/tokens) and use this URL in your MCP client or agent framework:

```sh
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:

```sh
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](/api-reference#regions-and-endpoints) for the full list of available regions and their API URLs.

## 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 execute
- `format` (string, optional): The response format, default is CSVWithNames but [other formats](/api-reference/query-api#id2) 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](/monitoring/service-datasources).

```sql
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:

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

See [Using JWT tokens with non-default regions](#using-jwt-tokens-with-non-default-regions) for examples.

## See also

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