> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiql.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect AI agents to AiQL tools over the Model Context Protocol

AiQL exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so AI agents and MCP-compatible clients can call the AiQL tools directly. The server speaks the streamable HTTP transport and is available at the `/mcp` endpoint.

## Endpoint

```
https://api.aiql.io/mcp
```

The MCP server exposes the same tools as the API: the `convert`, `split`, `shape`, and `extract` pipeline tools, plus tools to manage workspaces, ingestions, and queries. See [Tools](/mcp/tools/pipeline) for each tool's parameters.

## Authentication

The MCP server supports two ways to authenticate, both presented as a Bearer token in the `Authorization` header:

* **OAuth** — for interactive clients, with AiQL as the authorization provider.
* **API key** — for programmatic access from scripts and services.

### OAuth

The MCP server is an OAuth 2.1 protected resource, with AiQL acting as the authorization server. Compatible clients discover the authorization server automatically: when a request arrives without a valid token, the server responds with `401 Unauthorized` and a `WWW-Authenticate` header pointing at the [protected resource metadata](https://datatracker.ietf.org/doc/html/rfc9728).

```
https://api.aiql.io/.well-known/oauth-protected-resource/mcp
```

The client reads that metadata, sends you through the AiQL sign-in and consent flow, and uses the issued access token on every request. You do not paste a key into the client — the OAuth flow handles it.

### API key

For programmatic access, pass an AiQL API key as the Bearer token. API keys are prefixed with `aiql_`. Generate one in the [Dashboard](https://app.aiql.io) and keep it in an environment variable rather than committing it to source control.

```
Authorization: Bearer aiql_your_api_key
```

The same key works across the AiQL API and the MCP server.

## Workspace scope

The workspace-scoped tools — ingestions and queries — never take a `workspace_id` parameter. Instead, the workspace is fixed for the session, and how it is determined depends on how you authenticate:

* **OAuth** — you select the workspace during the sign-in flow, and it travels with the access token. Nothing else to pass.
* **API key** — keys are not bound to a workspace, so you pass the workspace in the `AiQL-Workspace` header on every request, the same header the REST API uses.

```
AiQL-Workspace: YOUR_WORKSPACE_ID
```

A workspace-scoped tool call fails if no workspace can be resolved — authenticate with OAuth, or include the `AiQL-Workspace` header with your API key. To work with a different workspace, switch it in the OAuth flow or change the header.

## Connect a client

How you connect depends on the credential you use.

### With OAuth

Point an OAuth-capable MCP client at the endpoint and let it run the sign-in flow. No key goes in the config.

```json theme={null}
{
  "mcpServers": {
    "aiql": {
      "url": "https://api.aiql.io/mcp"
    }
  }
}
```

### With an API key

For clients or automation that authenticate with a key, send it in the `Authorization` header. Because an API key is not bound to a workspace, also send the `AiQL-Workspace` header so the ingestion and query tools know which workspace to operate on.

<CodeGroup>
  ```json MCP client theme={null}
  {
    "mcpServers": {
      "aiql": {
        "url": "https://api.aiql.io/mcp",
        "headers": {
          "Authorization": "Bearer aiql_your_api_key",
          "AiQL-Workspace": "YOUR_WORKSPACE_ID"
        }
      }
    }
  }
  ```

  ```bash curl theme={null}
  curl -X POST https://api.aiql.io/mcp \
    -H "Authorization: Bearer aiql_your_api_key" \
    -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
  ```
</CodeGroup>

<Note>
  The MCP server uses the streamable HTTP transport. Make sure your client supports HTTP-based MCP servers rather than only stdio.
</Note>

## Next steps

<Columns cols={2}>
  <Card title="Tools" icon="wrench" href="/mcp/tools/pipeline">
    See the tools the MCP server exposes and their parameters.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn how Bearer tokens secure your requests.
  </Card>
</Columns>