# Sequel Documentation > The complete Sequel documentation, concatenated as Markdown for LLMs. Sequel is the data layer for your agents: it manages auth, credentials, and execution so AI tools can securely query your cloud databases, warehouses, and SaaS tools over MCP. Source pages: https://sequel.sh/docs --- # Getting Started Connect the Sequel MCP server to your AI tool in a few minutes — the MCP URL, where to get an API key, the two auth types, and how OAuth works. This guide gets the Sequel MCP server running inside your AI tool. By the end you'll have a connected data source and an agent answering questions against it. Sign up at [sequel.sh](https://sequel.sh) and create or join an organization. Then add a data source — a cloud Postgres or MySQL database, a warehouse like BigQuery, or a SaaS source like Stripe or Google Analytics. See [Connecting your first data source](/docs/connecting-your-first-data-source) for the full walkthrough. Everything you connect becomes available to the MCP server. The CLI is the fastest way to wire Sequel into a coding agent — it creates the API key and writes the config for you. One line installs it: curl -fsSL https://sequel.sh/install | sh Then sign in: sequel login Run `install` and pick your agent — Claude Code, Cursor, VS Code, Windsurf, Zed, Codex, or Claude Desktop — or pass its slug directly: ```bash sequel install # interactive sequel install cursor # or target one directly ``` The CLI runs over the same hosted MCP endpoint every tool uses — `https://api.sequel.sh/mcp` — so you never touch the URL or key by hand. Prefer to configure a tool manually (or using ChatGPT, Claude.ai, or Gemini)? See [Install Sequel MCP](/docs/install) for copy-paste setup. Restart the agent, then try “What tables do we have, and how many rows are in each?” Go deeper with [Chatting with your data](/docs/chatting-with-your-data). ## Authentication: two ways to connect Sequel supports **two authentication methods** for the MCP server. Pick whichever your tool supports best. | Method | Best for | How it works | | --- | --- | --- | | **API key (Bearer token)** | CLIs and editors — Claude Code, Cursor, VS Code, Windsurf, Zed, Codex, Gemini | You paste a static key into an `Authorization: Bearer …` header in the tool's config. | | **OAuth 2.0** | Connector-style clients — ChatGPT, Claude.ai | The tool registers itself and sends you through a sign-in + consent screen. No key to copy. | ### API key Create a key in the Sequel dashboard under **Settings → API Keys**. Keys look like `sql_…` and are shown **once** at creation — copy it then. Add it as a Bearer token: Authorization: Bearer sql_your_api_key When you install from the dashboard, Sequel auto-provisions a key named sequel_mcp and drops it straight into the snippet for you. ### OAuth For clients that support it, OAuth avoids copying keys around. The flow is standard OAuth 2.0 with PKCE: the client registers itself automatically, you sign in on a Sequel consent screen, and Sequel issues a short-lived access token (refreshed automatically) scoped to your organization. Revoke access any time from the dashboard. Either method only ever exposes the data sources your organization has connected — see [API keys & authentication](/docs/api-keys-and-auth) for the full details. ## Next step Head to **[Install Sequel MCP](/docs/install)** for copy-paste setup instructions for every supported AI tool. --- # Install Sequel MCP Step-by-step instructions for installing the Sequel MCP server in Claude Code, Cursor, VS Code, ChatGPT, Codex, Windsurf, Zed, and Gemini. Sequel exposes a single hosted MCP endpoint. Point any MCP-capable AI tool at it and authenticate with your API key: https://api.sequel.sh/mcp There are two ways to install it into your agent: the **Sequel CLI** (one command — it creates the API key and writes the config for you) or **manual setup** (copy-paste the config into each tool yourself). ## Fastest: the Sequel CLI The CLI installs Sequel into a coding agent in a single step. It signs you in, provisions a scoped API key for that agent, and writes the right config to the right place — no keys to copy by hand. One line installs the latest CLI (`@sequelsh/cli`) with whatever package manager you have: curl -fsSL https://sequel.sh/install | sh Prefer npm directly? `npm install -g @sequelsh/cli@latest` works too (or `pnpm add -g`, `bun add -g`, `yarn global add`). sequel login This opens your browser to authenticate and pick an organization. Run `install` and pick an agent from the list, or pass its slug directly: sequel install The CLI creates an API key named after the agent, then writes its MCP config. For agents that support it, you'll also be asked for a **scope** — `global` (available everywhere on this machine) or `local` (this project only). | Agent | Slug | Scopes | | --- | --- | --- | | Claude Code | `claude-code` | global, local | | Claude Desktop | `claude` | global | | Cursor | `cursor` | global, local | | VS Code | `vscode` | global, local | | Windsurf | `windsurf` | global | | Zed | `zed` | global, local | | Codex | `codex` | global | Restart the agent and ask it to **"list my Sequel connections."** If it answers, you're connected. Already have the CLI? `sequel install claude-code` (or any slug above) re-runs setup for that agent at any time. ## Manual setup Prefer to wire it up yourself — or using ChatGPT, Claude.ai, or Gemini? Generate a key under **Settings → API Keys** in your Sequel dashboard and drop it into the `Authorization` header shown in each snippet below. Some tools — like ChatGPT and Claude.ai — can also sign in with **OAuth** instead of a static key; see [API keys & authentication](/docs/api-keys-and-auth) for the difference. Expand a tool for its exact setup. Replace `sql_your_api_key` with a real key from your dashboard. Any client that supports the [Model Context Protocol](https://modelcontextprotocol.io) over streamable HTTP can connect using the URL and `Authorization` header above. --- # Connecting your first data source Add a cloud database, warehouse, or SaaS source to Sequel — credentials, testing the connection, and what happens once it's live. A **data source** is any database, warehouse, or SaaS API you connect to Sequel. Once connected, it's available to the in-app chat and to every AI tool you've authorized through the [MCP server](/docs/install). This guide walks through adding your first one. Sequel connects to cloud-hosted data sources — managed Postgres/MySQL (RDS, Supabase, Neon, PlanetScale), warehouses like BigQuery and ClickHouse, and SaaS APIs like Stripe and Google Analytics. Make sure your source is reachable from the internet (or via the access method its guide describes). ## Add a connection In the Sequel dashboard, go to **Connections** and click **New connection**. Choose the source you want to connect — for example PostgreSQL, BigQuery, or Google Analytics. Each type asks for the credentials it needs. Depending on the source, this is a connection string, a host/port/user/password, a service-account key, or an OAuth sign-in. The per-integration guides under [Integrations](/docs/integrations) cover exactly what each source needs. Sequel verifies the credentials before saving. A green check means the connection is live and ready to query. If the test fails, double-check network access and credentials. ## What happens after you connect - **Schema discovery.** Sequel reads your tables, columns, and relationships so agents can navigate the source without you spelling everything out. - **Available over MCP.** The source immediately becomes queryable from any AI tool connected to your organization's MCP server. - **Scoped access.** Connections belong to your organization. API keys and OAuth sessions only ever see the sources your org has connected. ## Connecting more sources Repeat the flow for every source you want Sequel to reach. Because Sequel can join across connections, adding a second and third source is where it gets powerful — see [Chatting with your data](/docs/chatting-with-your-data) for cross-source examples. ## Next steps - [Chatting with your data](/docs/chatting-with-your-data) - [Browse all integrations](/docs/integrations) - [API keys & authentication](/docs/api-keys-and-auth) --- # Chatting with your data How to ask good questions, join across sources, and use the Python workbench — whether you're in the Sequel app or an MCP client like Claude or Cursor. Once a source is connected, you can ask questions in plain English — from the Sequel app or from any AI tool wired up to the [MCP server](/docs/install). This page covers what the agent can do and how to get the most out of it. ## What the agent can do Behind the scenes, Sequel exposes a small set of tools that the AI agent calls to answer your question: | Capability | What it's for | | --- | --- | | **Discover connections** | List the data sources available to you. | | **Search schemas** | Find the right tables and columns and plan a query. | | **Run queries** | Execute read queries and return sample results. | | **Python workbench** | Run Python (pandas, matplotlib, and more) in an isolated sandbox for analysis and charts. | | **Download files** | Export results — CSVs, charts — produced in the workbench. | You don't call these directly. You ask a question; the agent chains the tools to answer it. ## Ask better questions - **Be specific about the metric and window.** "Weekly active users for the last 90 days" beats "how are we doing." - **Name the source when it's ambiguous.** "In our Postgres `orders` table…" removes guesswork. - **Ask for the format you want.** "Return a table" or "plot it as a line chart." Start broad to orient the agent ("what tables relate to subscriptions?"), then drill in. The agent keeps context across the conversation. ## Join across sources This is where Sequel shines. Because every connection is available in one place, a single question can span systems: > "Compare 90-day retention for users acquired through paid vs organic channels, using signups from Postgres and acquisition source from Google Analytics." The agent searches both schemas, runs the queries it needs, and combines the results — no manual exports or copy-paste between tools. ## Run real analysis with the workbench When SQL isn't enough, the agent can run Python in a sandbox: > "Pull last quarter's order values and plot a histogram with the median marked." The workbench has common data libraries available and runs in isolation. Generated files (charts, CSVs) can be downloaded directly from the conversation. ## Same data, every tool The connections you set up power every surface equally — the Sequel app, Claude, Cursor, ChatGPT, and any other MCP client. Set a source up once and ask about it from wherever you work. ## Next steps - [Install Sequel MCP in your tool](/docs/install) - [API keys & authentication](/docs/api-keys-and-auth) - [Browse all integrations](/docs/integrations) --- # Building with Sequel Use the Sequel MCP server inside your own agents — examples for the Vercel AI SDK, the Claude Agent SDK, and the OpenAI Agents SDK. Sequel isn't only for off-the-shelf tools like Claude or Cursor — you can point your own agents at the same hosted MCP server and give them secure, schema-aware access to your data. Every framework that speaks [Model Context Protocol](https://modelcontextprotocol.io) connects the same way: the streamable HTTP endpoint `https://api.sequel.sh/mcp`, authenticated with a Bearer API key. Create a key under **Settings → API Keys** in the dashboard and pass it as `Authorization: Bearer sql_…`. See [API keys & authentication](/docs/api-keys-and-auth) for details. ## Vercel AI SDK Create an MCP client over the streamable HTTP transport, then hand its tools to `generateText`. ```ts import { experimental_createMCPClient, generateText, stepCountIs } from "ai"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; import { anthropic } from "@ai-sdk/anthropic"; const mcp = await experimental_createMCPClient({ transport: new StreamableHTTPClientTransport(new URL("https://api.sequel.sh/mcp"), { requestInit: { headers: { Authorization: "Bearer " + process.env.SEQUEL_API_KEY }, }, }), }); const { text } = await generateText({ model: anthropic("claude-opus-4-8"), tools: await mcp.tools(), stopWhen: stepCountIs(10), prompt: "How many users signed up last week?", }); console.log(text); ``` ## Claude Agent SDK Register Sequel as an `http` MCP server in the `query` options — the agent discovers and calls the tools on its own. ```ts import { query } from "@anthropic-ai/claude-agent-sdk"; const response = query({ prompt: "How many users signed up last week?", options: { mcpServers: { sequel: { type: "http", url: "https://api.sequel.sh/mcp", headers: { Authorization: "Bearer " + process.env.SEQUEL_API_KEY }, }, }, }, }); for await (const message of response) { if (message.type === "result") console.log(message.result); } ``` ## OpenAI Agents SDK Wrap the endpoint in an `MCPServerStreamableHttp` and attach it to your agent's `mcpServers`. ```ts import { Agent, run, MCPServerStreamableHttp } from "@openai/agents"; const sequel = new MCPServerStreamableHttp({ name: "Sequel", url: "https://api.sequel.sh/mcp", requestInit: { headers: { Authorization: "Bearer " + process.env.SEQUEL_API_KEY }, }, }); const agent = new Agent({ name: "Data analyst", instructions: "Answer questions using the connected data sources.", mcpServers: [sequel], }); await sequel.connect(); const result = await run(agent, "How many users signed up last week?"); console.log(result.finalOutput); await sequel.close(); ``` ## Next steps - [Install Sequel MCP in your tool](/docs/install) - [API keys & authentication](/docs/api-keys-and-auth) - [Browse all integrations](/docs/integrations) --- # API keys & authentication The two ways to authenticate with the Sequel MCP server — static API keys and OAuth 2.0 — plus how to create, scope, and revoke access. The Sequel MCP server supports **two authentication methods**. Both authorize a client to query the data sources your organization has connected — nothing more. This page explains when to use each and how to manage access. ## At a glance | | API key | OAuth 2.0 | | --- | --- | --- | | **Best for** | CLIs & editors (Claude Code, Cursor, VS Code, Windsurf, Zed, Codex, Gemini) | Connector-style clients (ChatGPT, Claude.ai) | | **Setup** | Paste a key into the tool's config | Sign in on a consent screen | | **Credential** | Static `sql_…` Bearer token | Short-lived access token, auto-refreshed | | **Revoke** | Delete the key | Revoke the authorization | ## API keys API keys are static Bearer tokens you generate once and paste into a tool's MCP config. Go to **Settings → API Keys** in the Sequel dashboard and create a new key. Give it a descriptive name (e.g. the tool or person it's for). The full key is shown **once**, at creation. Copy it then — afterward only a short prefix is visible for identification. Add it to your tool's MCP config: Authorization: Bearer sql_your_api_key When you install Sequel from the dashboard's install dialog, it auto-provisions a key named sequel_mcp and inserts it into the config snippet for you — so you usually don't have to create one by hand. A key grants access to your organization's connected data. Don't commit keys to shared repos — give each person or tool its own key, and revoke any key that may have leaked. ## OAuth 2.0 For clients that support it, OAuth avoids sharing static keys. Sequel implements standard **OAuth 2.0 with PKCE**: The MCP client registers with Sequel automatically (dynamic client registration) — there's nothing to paste. You're redirected to a Sequel consent screen, sign in, and pick the organization to authorize. Sequel returns a short-lived access token (refreshed automatically in the background) scoped to your organization. The client uses it on every request. To use OAuth, just choose Sequel as an MCP connector in a client that supports it (for example ChatGPT's Connectors or Claude.ai integrations) and follow the sign-in prompt. ## Scope & revocation - **Organization-scoped.** Every key and OAuth session can only reach the data sources your organization has connected. - **Revoke anytime.** Delete an API key, or revoke an OAuth authorization, from the dashboard. Access stops immediately. - **Rotate freely.** Issue separate keys per tool or environment so you can revoke one without disrupting the others. ## Next steps - [Install Sequel MCP in your tool](/docs/install) - [Getting Started](/docs/getting-started) --- # Integrations Connect Sequel to your databases, warehouses, product analytics, and SaaS tools. Browse every supported integration and its setup guide. Sequel connects to cloud databases, warehouses, product analytics, and SaaS APIs — and can join across them in a single question. Pick a source below for its step-by-step setup guide. Guides are rolling out continuously. Sources without a dedicated guide yet still work today via the [connections flow](/docs/connecting-your-first-data-source). --- # PostgreSQL Connect a cloud-hosted PostgreSQL database to Sequel and query it in natural language from the app or any MCP client. Connect a cloud-hosted PostgreSQL database to Sequel and query it in plain English — from the Sequel app or any AI tool wired up to the [MCP server](/docs/install). This works with managed Postgres anywhere: Amazon RDS/Aurora, Supabase, Neon, Render, Railway, Heroku, Digital Ocean, and similar. ## What you'll need - A **cloud-hosted PostgreSQL** database reachable over the internet. - A database **connection string** (or host, port, database, user, and password). - A user with **read access** to the schemas you want to query. Create a dedicated read-only role for Sequel. It's the simplest way to guarantee queries can't modify your data, and it scopes access to just the tables you intend to expose. ## Connect it In the Sequel dashboard, go to **Connections → New connection** and choose **PostgreSQL**. Paste your connection string. It usually looks like this: postgresql://USER:PASSWORD@HOST:5432/DATABASE?sslmode=require Most managed providers require SSL — keep `sslmode=require` unless your provider says otherwise. If your database restricts inbound traffic, allow connections from Sequel so the test can reach it. Check your provider's networking/allowlist settings. Sequel verifies the credentials and reads your schema. A green check means it's live. ## Try it Once connected, ask things like: - "How many rows are in each table?" - "Show me the 10 most recently created users." - "What foreign keys reference the `orders` table?" - "Plot daily signups for the last 30 days." ## Troubleshooting | Symptom | Likely fix | | --- | --- | | Connection test times out | Database isn't reachable from the internet, or an allowlist is blocking Sequel. | | SSL/TLS error | Add or adjust `sslmode` (commonly `require`) to match your provider. | | "Permission denied" on a table | The user lacks `SELECT` on that table or schema — grant read access. | ## Related - [Connecting your first data source](/docs/connecting-your-first-data-source) - [Chatting with your data](/docs/chatting-with-your-data) - [Browse all integrations](/docs/integrations) --- # Google Analytics Connect Google Analytics 4 to Sequel with OAuth and ask about sessions, conversions, and traffic in natural language. Connect **Google Analytics 4 (GA4)** to Sequel and ask about your traffic, sessions, conversions, and acquisition channels in plain English — then join it with your product or revenue data for questions a single tool can't answer alone. ## What you'll need - A **Google account** with access to the GA4 property you want to query. - At least **Viewer** access on that property. Google Analytics connects over **OAuth**, so there's no key to copy — you authorize Sequel with your Google account and pick the property. ## Connect it In the Sequel dashboard, go to **Connections → New connection** and choose **Google Analytics**. You'll be redirected to Google's consent screen. Sign in and grant Sequel read access to your Analytics data. Choose the GA4 property you want Sequel to query. You can connect additional properties later by repeating this flow. Sequel verifies access and the connection goes live. Sequel queries GA4 properties. Universal Analytics properties stopped processing data in 2023 and aren't supported. ## Try it - "How many sessions did we get last week, by channel?" - "What were our top 10 landing pages by users this month?" - "Compare conversion rate for mobile vs desktop over the last 30 days." - "Which acquisition source drove the most new users this quarter?" ## Join it with other sources Google Analytics gets more powerful alongside your other data. With a database also connected, ask: > "For users acquired through paid search in GA, what's their 90-day retention in our Postgres `events` table?" ## Troubleshooting | Symptom | Likely fix | | --- | --- | | No properties listed | The Google account you authorized doesn't have access to the property — use one with at least Viewer access. | | Authorization fails | Re-run the OAuth flow and make sure you grant the requested Analytics read scope. | | Data looks empty | Confirm the property actually has data in the date range you're asking about. | ## Related - [Google Search Console](/docs/google-search-console) - [Chatting with your data](/docs/chatting-with-your-data) - [Browse all integrations](/docs/integrations) --- # Google Search Console Connect Google Search Console to Sequel with OAuth and ask about clicks, impressions, queries, and pages in natural language. Connect **Google Search Console (GSC)** to Sequel and ask about your organic search performance — clicks, impressions, average position, top queries, and top pages — in plain English. Pair it with Google Analytics and your product data for a full picture of how search traffic converts. ## What you'll need - A **Google account** with access to the Search Console property you want to query. - At least **Restricted** or **Full** user access on that property. Search Console connects over **OAuth** — authorize Sequel with your Google account and select the property. ## Connect it In the Sequel dashboard, go to **Connections → New connection** and choose **Google Search Console**. Grant Sequel read access on Google's consent screen. Choose the verified Search Console property (a domain or URL-prefix property) you want to query. Sequel verifies access and the connection goes live. Search Console data typically lags by a couple of days, and very recent dates may be incomplete. Ask about ranges that end a few days back for stable numbers. ## Try it - "What were our top 20 search queries by clicks last month?" - "Which pages gained the most impressions week over week?" - "What's our average position for branded vs non-branded queries?" - "Show clicks and CTR by country for the last 28 days." ## Join it with other sources > "Take our top 20 GSC landing pages by clicks and show how many of those sessions converted, using our Postgres `orders` table." ## Troubleshooting | Symptom | Likely fix | | --- | --- | | No properties listed | The authorized account lacks access — use one added as a user on the property in Search Console. | | Recent dates empty | GSC data lags; query a range ending 2–3 days ago. | | Authorization fails | Re-run the OAuth flow and grant the requested Search Console read scope. | ## Related - [Google Analytics](/docs/google-analytics) - [Chatting with your data](/docs/chatting-with-your-data) - [Browse all integrations](/docs/integrations) --- # Introduction What Sequel is — the data layer for your agents. It manages auth, credentials, and execution to securely connect your cloud databases, warehouses, and SaaS tools to the AI agents you already use, over MCP. Sequel is the **data layer for your agents**. You connect your cloud databases, warehouses, and SaaS tools to Sequel once, and then the AI tools you already use — Claude, Cursor, ChatGPT, or any other MCP-capable agent — can ask questions of your data in plain English and get back real answers. Your agents talk to Sequel, and Sequel safely talks to your data. No more handing out database passwords or API keys to every tool. ![Sequel sits between your data stack and your AI agents](/docs/data-layer.png) ## Why use Sequel - **One secure boundary.** Your credentials live in Sequel, encrypted. Agents ask Sequel to run work — they never see the secret behind a connection. Authorize a tool once, revoke it any time. - **Connect once, use everywhere.** The same connections power every MCP client and the CLI. Add a new agent with a permission grant, not another round of credential setup. - **Answers across sources.** Most real questions span more than one system. Sequel can join your Postgres revenue, Google Analytics sessions, and Stripe payments in a single thread. - **Real analysis, not just queries.** A built-in Python sandbox (pandas, matplotlib, and more) lets agents compute, chart, and export results — backed by your actual data. ## What Sequel manages for you Sitting between your agents and your data, Sequel owns the three things that make agent access hard to get right: | Concern | How Sequel handles it | | --- | --- | | **Auth** | Every agent and MCP client connects through Sequel's OAuth flow and scoped API keys. You authorize a tool once, and you can revoke that access at any time without touching the data source itself. | | **Credentials** | Database passwords, connection strings, and SaaS API keys are stored and encrypted on Sequel's side. Agents never see them — they ask Sequel to run work on a connection, not for the secret behind it. | | **Execution** | Queries and Python analyses run in Sequel's controlled, sandboxed environment, then return clean results. Your agents get answers and charts back; your data sources only ever talk to Sequel. | This is what "data layer" means in practice: one secure boundary in front of all your sources, so onboarding a new agent is a permission grant rather than a secret-sharing exercise. ## What you can do with it - **Ask questions across sources.** Join Postgres revenue with Google Analytics sessions and Stripe payments in a single thread. - **Explore schemas in natural language.** "What tables relate to subscriptions, and how?" - **Run real analysis.** Sequel includes a Python sandbox (pandas, matplotlib, and more) so agents can compute, chart, and export results. - **Connect once, use everywhere.** The same connections power every MCP client and the CLI — no per-tool credential setup. ## Who it's for - **Data and analytics teams** who want self-serve answers without writing every query by hand. - **Engineers** who want schema-aware, data-grounded answers inside their editor or CLI. - **Operators and PMs** who live in ChatGPT or Claude and want those tools to answer with real numbers instead of guesses. Managed Postgres and MySQL (RDS, Supabase, Neon, PlanetScale, and similar), warehouses like BigQuery and ClickHouse, and SaaS APIs like Stripe and Google Analytics. ## Next steps - **[Getting Started](/docs/getting-started)** — connect the MCP server and run your first query. - **[Install Sequel MCP](/docs/install)** — copy-paste setup for every supported AI tool. - **[Integrations](/docs/integrations)** — browse every supported data source and its setup guide.