---
last_updated: "2026-09-30T12:55:40.000Z"
title: MCP
meta:
  description: Connect AI agents to Tinybird with the remote MCP server.
---

# MCP

The Tinybird remote MCP server lets AI agents query your Workspace and call published API Endpoints. MCP stands for [Model Context Protocol](https://modelcontextprotocol.io), 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.

{% callout type="info" %}
The Tinybird MCP server supports Streamable HTTP. If your MCP client doesn't support Streamable HTTP, use `mcp-remote` as a bridge.
{% /callout %}

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

```shell
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.

### Set up MCP in common clients

Replace `TINYBIRD_TOKEN` with a Tinybird Token in each example.

{% tabs initial="Claude Code" %}

{% tab label="Claude Code" %}

```shell {% title="Add the Tinybird MCP server" %}
claude mcp add tinybird --scope user --transport http "https://mcp.tinybird.co?token=TINYBIRD_TOKEN"
```

{% /tab %}

{% tab label="Cursor" %}

Add the server to your global `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project to scope it to that project:

```json {% title="~/.cursor/mcp.json" %}
{
  "mcpServers": {
    "tinybird": {
      "url": "https://mcp.tinybird.co?token=TINYBIRD_TOKEN"
    }
  }
}
```

{% /tab %}

{% tab label="Codex CLI" %}

```shell {% title="Add the Tinybird MCP server" %}
codex mcp add tinybird --url "https://mcp.tinybird.co?token=TINYBIRD_TOKEN"
```

{% /tab %}

{% tab label="Amp" %}

```shell {% title="Add the Tinybird MCP server" %}
amp mcp add tinybird "https://mcp.tinybird.co?token=TINYBIRD_TOKEN"
```

{% /tab %}

{% /tabs %}

### Clients that need a bridge

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

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

{% callout type="info" %}
New Tinybird Tokens include the Tinybird API host. For older Tokens, pass the API host as a query parameter: `https://mcp.tinybird.co?token=TINYBIRD_TOKEN&host=https://api.tinybird.co`. See [Regions and endpoints](/api-reference#regions-and-endpoints).
{% /callout %}

### JWTs and non-default regions

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

```shell
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.

## 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](/forward/core-concepts/tokens) and [JWTs](/forward/core-concepts/jwt).

{% table %}
  * Tool
  * JWT
  * Admin Token
  ---
  * `call_endpoint`
  * Specific Endpoints only
  * ✓
  ---
  * `list_endpoints`
  * ✓
  * ✓
  ---
  * `list_datasources`
  * ✓
  * ✓
  ---
  * `list_service_datasources`
  * ✓
  * ✓
  ---
  * `execute_query`
  * ✓
  * ✓
  ---
  * `text_to_sql`
  * ✓
  * ✓
{% /table %}

## Available tools

The MCP server exposes the following tools.

`call_endpoint`

: Call a published Endpoint by name. Takes `endpoint_name` (as returned by `list_endpoints`), an optional `params` object with the Endpoint's own parameters, and an optional `response_format`. The default is `CSVWithNames`; `JSON` and `Markdown` are also supported. Respects Endpoint rate limits and Token scopes. Use `list_endpoints` first to discover available Endpoint names and the parameters each one accepts. If the target Endpoint already defines its own `response_format` parameter, pass it inside `params` instead. The Endpoint's own parameter takes priority over `call_endpoint`'s `response_format` argument. Parameters that the Endpoint doesn't define are rejected with an error that lists the accepted ones.

`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 `response_format` parameter accepts `CSVWithNames`, `JSON`, or `Markdown`. The default is `CSVWithNames`. Set `explain` to `true` to return the query plan instead of running the query, and pass EXPLAIN options such as `indexes=1,actions=1` in the optional `explain_settings` parameter.

`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 Endpoints with names, parameters, and descriptions. Use this to find the `endpoint_name` and parameters to pass to `call_endpoint`.

## 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 to call Endpoints without writing tool wrappers.

Use direct APIs when:

- You are building a production app 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.

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

See [Service Data Sources](/forward/monitoring/service-datasources).

## Troubleshooting

### Workspace not found with a JWT

If you receive an error like this:

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

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

See [JWTs and non-default regions](#jwts-and-non-default-regions).

## See also

- [Tokens](/forward/core-concepts/tokens)
- [Endpoints](/forward/core-concepts/api-endpoints)
- [Query API](/api-reference/query-api)
- [Model Context Protocol documentation](https://modelcontextprotocol.io)