MCP server - AiQL Docs

AiQL exposes a Model Context Protocol (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 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://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 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.

{
  "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.

{
  "mcpServers": {
    "aiql": {
      "url": "https://api.aiql.io/mcp",
      "headers": {
        "Authorization": "Bearer aiql_your_api_key",
        "AiQL-Workspace": "YOUR_WORKSPACE_ID"
      }
    }
  }
}

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":{}}'

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

​Endpoint

​Authentication

​OAuth

​API key

​Workspace scope

​Connect a client

​With OAuth

​With an API key

​Next steps

Tools

Authentication

Endpoint

Authentication

OAuth

API key

Workspace scope

Connect a client

With OAuth

With an API key

Next steps