Build an AI Agent That Queries Your SQL Database over MCP

Short answer: give your agent an MCP client pointed at https://builder.ai2sql.io/api/mcp and an AI2SQL API key. It gets three tools, list_connections, describe_schema and run_query, and can answer questions from your PostgreSQL, MySQL or SQL Server data without ever holding the database password or the ability to write.

AI2SQL is a hosted MCP server for SQL databases. You connect the database once in AI2SQL; every agent then talks to the same read-only, logged endpoint.

The endpoint


URL	`https://builder.ai2sql.io/api/mcp`
Transport	MCP Streamable HTTP (JSON-RPC over POST)
Auth	`x-ai2sql-key: sql_…` header, or `Authorization: Bearer sql_…`
Default database (optional)	`x-ai2sql-connection: <connection id>`

Create the key under API keys in the AI2SQL dashboard. Keys are part of Pro and Team. Use one key per agent so Agent activity shows which agent ran what.

The tools

Tool	Input	Returns
`list_connections`	none	Your connected databases and their ids
`describe_schema`	`connection_id`	Tables, columns and types
`run_query`	`sql`, `connection_id`	Up to 1,000 rows from one read-only `SELECT` / `WITH`

A good agent loop is: list connections, describe the schema it needs, write one SELECT, run it, answer.

OpenAI Agents SDK (Python)

import asyncio, os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="ai2sql",
        params={
            "url": "https://builder.ai2sql.io/api/mcp",
            "headers": {"x-ai2sql-key": os.environ["AI2SQL_KEY"]},
        },
    ) as ai2sql:
        agent = Agent(
            name="Analyst",
            instructions="Answer with numbers from the database. Read the schema before writing SQL.",
            mcp_servers=[ai2sql],
        )
        result = await Runner.run(agent, "Who were our top 5 customers by revenue last month?")
        print(result.final_output)

asyncio.run(main())

Claude API MCP connector (Python)

The Claude API connects to the MCP server for you; there is no client to run.

import os
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://builder.ai2sql.io/api/mcp",
        "name": "ai2sql",
        "authorization_token": os.environ["AI2SQL_KEY"],
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "ai2sql"}],
    messages=[{"role": "user", "content": "Who were our top 5 customers by revenue last month?"}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

authorization_token is sent as a Bearer token, which AI2SQL accepts for sql_ keys.

MCP TypeScript SDK

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://builder.ai2sql.io/api/mcp"), {
    requestInit: { headers: { "x-ai2sql-key": process.env.AI2SQL_KEY! } },
  }),
);

const { tools } = await client.listTools();
const dbs = await client.callTool({ name: "list_connections", arguments: {} });

Hand tools to your model in whatever format it expects, and forward its tool calls to client.callTool.

curl

curl -s https://builder.ai2sql.io/api/mcp \
  -H "x-ai2sql-key: $AI2SQL_KEY" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

What the agent cannot do

Write. INSERT, UPDATE, DELETE and DDL are blocked by the SQL guard before they reach your database. Background in read-only database MCP that is not actually read-only.
Pull the whole table. Each call returns at most 1,000 rows.
Hide. Every call, including blocked ones, is logged in Agent activity with the key name, SQL, database, result and latency.
See the password. It only holds the AI2SQL key, which you can revoke at any time.

Frequently asked questions

How do I give my own AI agent access to a SQL database?

Point the agent's MCP client at https://builder.ai2sql.io/api/mcp with an AI2SQL API key in the x-ai2sql-key header or as a Bearer token. The agent gets three tools: list_connections, describe_schema and run_query, which runs one read-only SELECT.

Does the Claude API MCP connector work with AI2SQL?

Yes. Pass the server in mcp_servers with your AI2SQL key as authorization_token, add an mcp_toolset entry with the same name, and send the mcp-client-2025-11-20 beta header.

Does the OpenAI Agents SDK work with AI2SQL?

Yes. Use MCPServerStreamableHttp with the AI2SQL URL and the x-ai2sql-key header, then pass the server in the agent's mcp_servers list.

Can the agent write to the database?

No. run_query accepts one SELECT or WITH statement; writes and DDL are blocked before they reach the database, and each call returns at most 1,000 rows.

What do I need to start?

An AI2SQL account on the Pro or Team plan (7-day trial), a connected PostgreSQL, MySQL or SQL Server database, and an API key from the dashboard.