Neon AI Gateway

FIRST: Use the parent neon skill for a Neon overview, getting started with Neon, Neon development best practices, and more.

If the neon skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:

neon skills -s neon -y

Neon AI Gateway

Currently available in aws-us-east-2, aws-us-east-1, aws-eu-central-1, and aws-ap-southeast-1.

The Neon AI Gateway is the LLM inference layer built into your Neon branch: one API and one Neon credential give you access to frontier and open-source models from many providers (Anthropic, OpenAI, Google, Meta, and more), all hosted and powered by Databricks. The catalog shifts over time, so treat /v1/models and the models.dev Neon page as the source of truth rather than a fixed provider list. Your existing OpenAI/Anthropic/Gemini SDK works by changing only the base URL.

Use this skill to help the user send model calls through the gateway, wire it into the AI SDK or Mastra, and switch providers without rewiring code. Deliver a working inference request, a configured agent, or a precise answer from the official Neon docs.

When to Use

Reach for the AI Gateway whenever an app or agent needs to call an LLM and the user would rather not manage model providers themselves:

• One credential instead of many provider accounts. A single Neon credential reaches the entire model catalog across every provider Databricks hosts. No separate OpenAI / Anthropic / Google billing, keys, or signups to provision and rotate.
• Switch models without rewiring. The unified endpoint is OpenAI-compatible and works with every model in the catalog — change one model field to move between Claude, GPT, and Gemini. Standard SDKs (OpenAI, Anthropic, google-genai) work with just a base-URL change.
• AI follows your branches. Each branch has its own gateway endpoint, scoped with the same lineage as your database. AI requests from a preview/feature branch are isolated to that branch — the same isolation your data already gets — which makes preview, CI, and agent environments self-contained.
• No extra infrastructure, and it's already next to your data. The gateway lives inside your Neon project (and is injected into Neon Functions automatically), runs on the same Databricks infrastructure that serves trillions of tokens a month, and supports streaming (SSE) out of the box.

If the user already has a deep, single-provider integration and no interest in Neon branching or multi-model routing, a direct provider SDK is fine — but the moment they want one credential, model portability, or branch-scoped AI, this is the reason to use it.

What It Does

• One API for all models — Frontier and open-source models behind a single endpoint, addressed by their catalog ID (e.g. claude-sonnet-4-6, gpt-5-mini, gemini-3-flash).
• Standard SDKs, one URL change — OpenAI SDK and AI SDK (OpenAI-compatible MLflow/Responses routes), Anthropic SDK (native Messages), google-genai (native Gemini).
• Branch-scoped — Each branch gets its own gateway host; the Neon credential authorizes requests for that branch and its descendants.
• Streaming — Server-sent events work on all endpoints with no extra configuration.

Availability

Check these preconditions before setting anything up:

The AI Gateway is currently available in aws-us-east-2, aws-us-east-1, aws-eu-central-1, and aws-ap-southeast-1. Foundation model access requires a paid Neon plan. Confirm the user's project is in one of these regions.

Enabling the gateway: plan and model-catalog gating

The AI Gateway is credential-gated rather than a provisioning step, but two plan limits gate it — one blocks provisioning, the other only trims the catalog — and the CLI surfaces each:

• Free plan → provisioning is blocked. neon config apply / deploy and neon checkout refuse to enable the gateway on a Free plan (the gateway can't serve requests there), with a friendly "upgrade to a paid plan, or remove aiGateway" error. A dry-run neon config plan and neon env pull don't provision, so they only warn. So: to use the gateway the project's account must be on a paid Neon plan.
• Paid plan with a reduced model catalog. On a paid plan the gateway provisions and serves, but an account can start with a trimmed catalog — some flagship models (e.g. Anthropic Opus, OpenAI Codex / *-pro) are missing from GET /v1/models. This is expected; neon env pull (and the env pull bundled into apply / deploy / checkout) warns and links the user to their branch's AI Gateway page in the Neon Console (https://console.neon.tech/app/projects/<project-id>/branches/<branch-id>/ai-gateway) to request access to more models. Verify what's actually available for the branch by reading /v1/models (see the models section below) rather than assuming the full catalog.

When helping a user debug "the gateway isn't working" or "a model is missing", use /v1/models plus the account's plan to distinguish these two cases — a Free plan blocks provisioning entirely, while a reduced catalog on a paid plan just needs a model-access request.

Setup

The gateway is part of neon.ts (see the neon skill for the branch-first workflow and neon.ts basics). Enable it with aiGateway:

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  aiGateway: true,
});

neon deploy   # provisions the gateway on the linked branch

Neon Infrastructure as Code (neon.ts)

The aiGateway toggle above is part of neon.ts, Neon's infrastructure-as-code file — one TypeScript file declares the gateway alongside every other branch service, in version control (see the neon skill for the full reference). Reconcile it against a branch the Terraform way:

neon config status   # print the branch's live config (is the gateway on?)
neon config plan     # dry-run diff of what apply would change
neon config apply    # enable the gateway on the branch  (neon deploy is an alias)

The gateway is branch-scoped: each branch gets its own gateway host. When a neon.ts is present, neon checkout applies the policy as it creates a branch, so a fresh preview/CI branch comes up with the gateway already enabled. Checking out an existing branch doesn't reconcile it — run neon deploy to apply changes. Provisioning (config apply / deploy), link, and checkout also pull the branch's gateway credentials into your local .env.local, so local runs hit the same branch gateway as the deployed function (no manual env pull needed).

Environment Variables

When aiGateway is enabled, Neon injects the gateway credentials as Neon-branded env vars. Inside a deployed Neon Function these are injected automatically; locally, neon env pull writes them to .env/.env.local (or use neon-env run -- <cmd> to inject at runtime without a file):

Neon injects only these two vars — it does not set OPENAI_API_KEY / OPENAI_BASE_URL. The @neon/ai-sdk-provider and Mastra's neon/<model> read NEON_AI_GATEWAY_* directly (zero config); for the plain OpenAI SDK / @ai-sdk/openai, build the client's apiKey + baseURL from them (shown below), or set your own OPENAI_* by hand (env pull leaves user-set vars untouched).

NEON_AI_GATEWAY_BASE_URL is the bare host — you append the dialect path yourself (which is exactly what the @neon/ai-sdk-provider does for you). The routes under the host are:

• /v1 — unified, OpenAI Chat Completions-compatible; recommended default, works with every provider (/v1/chat/completions).
• /openai/v1 — OpenAI Responses API (required for gpt-5-…-codex variants and gpt-5-5-pro); the @ai-sdk/openai provider uses the Responses API by default (/openai/v1/responses).
• /anthropic — native Anthropic Messages (extended thinking, prompt caching). Give the Anthropic SDK this as its base URL and it appends /v1/messages itself, so the full request path is /anthropic/v1/messages.
• /gemini — native Gemini generateContent. Give google-genai this as its base URL and it appends /v1beta/models/<model>:generateContent itself, so the full request path is /gemini/v1beta/models/<model>:generateContent.

So ${NEON_AI_GATEWAY_BASE_URL}/v1 is the chat-completions endpoint and ${NEON_AI_GATEWAY_BASE_URL}/openai/v1 the OpenAI Responses endpoint (both appended by you); for the native Anthropic and Gemini dialects you hand the SDK the shorter /anthropic or /gemini base and it appends the rest. See Use with Plain SDKs below.

For typed, validated access to the injected credentials, pass the same neon.ts config object to parseEnv from @neon/env — it returns an env.aiGateway namespace (apiKey, baseUrl) derived from your config.