Today we're launching @neon/tools, a package that turns the @neon/sdk ergonomic client into typed agent tools with adapters for MCP, Mastra, and Eve. We're also using it to expand the hosted Neon MCP Server, which now exposes 82 new tools, bringing the total to 101 tools: 82 Management API tools alongside 19 hand-written tools for SQL, migrations, diagnostics, docs, and search.

If you build agent platforms or your own agents, you can now select the Neon operations you need and hand them to a model as tools, without writing the schemas, retries, and workflows by hand:

npm install @neon/tools

Rethinking generated agent tools, one year later

About a year ago, we wrote that turning an OpenAPI spec directly into an MCP server was a shaky default. What has changed?

Back then, we identified two problems:

  1. First, tool definitions took up context, a problem commonly known as context bloat. A large API could put hundreds of schemas into the prompt before the model read the user's request. Similar names and descriptions also made it harder for the model to select the right tool.
  2. Second, a raw REST operation is not automatically a good agent tool. REST APIs describe resources and requests. Agents are trying to finish tasks. A 1:1 mapping gives you coverage, but not the waiting, workflows, or names that make a tool usable.

MCP hosts and model providers have since moved toward progressive tool discovery. The host searches a catalog first, then loads the full tool schema only when the model needs it, significantly reducing the context bloat caused by MCP. The MCP client best practices describe the flow as search, inspect, execute. That makes larger tool catalogs practical, and it solves the first problem.

The second problem remains. Progressive discovery (and, on some clients, programmatic tool calling) lets an agent work through a large catalog. That still isn't the most token-efficient way to use an API like Neon's.

Neon is infrastructure. Creating a branch over REST is three calls: create the branch, attach compute, then fetch a connection string. If an agent has to rediscover that chain every time, it wastes tokens and repeats the same mistakes. That's why SDKs exist: they expose the raw endpoints, and they also bundle common workflows into one operation. We can do the same for agent tools. In @neon/sdk, those three calls are branches.createAndConnect.

A generated schema can describe a request body, but it does not decide:

  • whether a create call should wait until the resource is ready
  • whether the result should include a connection string
  • which low-level operations should stay hidden
  • when several API calls should become one workflow
  • which tool names and descriptions help a model choose correctly

These are product decisions that happen at a level above the raw API spec.

Traditional deterministic code generation gets you raw methods, but that only gets you so far. Not the best developer experience, and not the best agent experience either. So we layered on top of the spec instead.

The Neon OpenAPI spec code-generates typed fetch functions and Zod request schemas. @neon/sdk exposes the raw API methods, but also adds createNeonClient(): a higher-level, ergonomic client built on top of the raw layer for a better developer experience. @neon/tools builds on that same ergonomic layer and the Zod request schemas to publish agent tools.

Two packages @neon/sdk and @neon/tools now build on top of each other:

@neon/sdk: OpenAPI spec → code generation → @neon/sdk raw methods → coding-agent-authored layer → createNeonClient() ergonomic client @neon/tools: OpenAPI spec → code generation → @neon/tools Zod request schemas + @neon/sdk ergonomic layer → agent tools

@neon/tools is the agent-facing end of that pipeline.

Building @neon/tools

We built @neon/tools in part to expand the hosted Neon MCP Server. However, we quickly realized that code-generation alone isn't enough for MCP. Hence, we decided to leverage coding agents as part of our pipeline. Deterministic code generation and agent-driven code generation compose into a pipeline that allows us to ship higher-level MCP tools and CLI workflows.

Building great MCP and CLIs for agents

CLIs and MCPs can be fully generated off OpenAPI specs, but in the age of agent-driven development it's almost free (aside from token costs, of course) to build tailored ergonomic layers on top to provide better developer and agent experiences.

For each developer surface, you need to make tailored calls around error handling, abstraction level, return values, etc. Those need to be tailored towards both agents and developers.

Once you have a raw code-generation pipeline, you can fill the gaps with agents to quickly ship ergonomic layers on top of your raw OpenAPI spec whenever the spec changes. @neon/tools is our answer to automating MCP tool generation with code generation and coding agents.

Turning SDK methods into agent tools

@neon/tools takes the generated Zod request schemas from the same OpenAPI spec, binds them to the ergonomic client, and publishes the result as agent tools. You select tools by SDK path:

import { createNeonTools } from "@neon/tools";
const apiKey = process.env.NEON_API_KEY;
if (!apiKey) throw new Error("NEON_API_KEY is required");
const tools = createNeonTools({
  apiKey,
  tools: [
    "projects.list",
    "projects.createAndConnect",
    "branches.createAndConnect",
    "branches.resetFromParent",
    "branches.compareSchema",
  ],
});
const listed = await tools["projects.list"].execute({ limit: 10 });
const created = await tools["projects.createAndConnect"].execute({
  name: "agent-project",
  region_id: "aws-us-east-1",
});

@neon/tools lets you select the functions from the @neon/sdk ergonomic layer and turns them into MCP tools.

  • projects.list becomes list_projects
  • projects.createAndConnect becomes create_and_connect_projects
  • postgres.roles.resetPassword becomes reset_password_postgres_roles

@neon/tools now powers Neon MCP

With @neon/tools, we grew the Neon MCP Server to over 101 tools. The expanded surface includes:

  • project updates, recovery, members, permissions, regions, and operations
  • branch, Postgres role, and database management
  • compute endpoint lifecycle operations
  • snapshot creation, schedules, and restore
  • Managed Better Auth providers, trusted domains, and users
  • Data API configuration
  • Functions deployment and management
  • Object Storage buckets, objects, and presigned URLs

The server still keeps 19 hand-written host tools. These cover jobs that do not map cleanly to one Management API method: running SQL, inspecting a database, preparing and completing safe migrations, tuning queries, searching resources, fetching docs, listing organizations, and getting a connection string.

This is still the hybrid model we argued for in 2025:

  • Use generated schemas and shared runtime behavior for broad Management API coverage.
  • Keep opinionated tools for tasks where the agent needs a workflow, not an HTTP operation.

The server covers 12 categories: projects, branches, endpoints, snapshots, schema, querying, Managed Better Auth, Data API, observability, docs, Functions, and Object Storage. An unfiltered connection exposes every category. Clients that need a narrower surface can select categories in the URL:

https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema

You can also scope the connection to one project or make it read-only:

https://mcp.neon.tech/mcp?projectId=<project-id>&readonly=true

Safety stays with the host

Every non-read operation in @neon/tools is conservatively marked as requiring approval. Reads that return connection credentials also require approval. The MCP adapter publishes standard annotations plus neon/requiresApproval metadata; Mastra and Eve receive their native approval fields.

Those annotations are advice to the host. The protocol does not enforce approval by itself.

The hosted Neon MCP Server builds on top of the @neon/tools:

  • OAuth or API-key authentication
  • read-only mode
  • project-scoped grants
  • category filtering
  • project and branch ID injection
  • result sanitization
  • fixed model-facing names and descriptions

With native adapters for MCP, Mastra, and Eve

Once we figured out MCP tools, we didn't stop there. @neon/tools publishes the same descriptors through three adapters:

MCP

@neon/tools/mcp registers a selected tool catalog with an MCP 2.x server. An MCP 1.x entry point is available at @neon/tools/mcp-v1.

import { McpServer } from "@modelcontextprotocol/server";
import { createNeonTools } from "@neon/tools";
import { registerNeonTools } from "@neon/tools/mcp";
const server = new McpServer({ name: "neon", version: "1.0.0" });
const tools = createNeonTools({
  apiKey: process.env.NEON_API_KEY!,
  tools: ["projects.list", "projects.createAndConnect"],
});
registerNeonTools(server, tools);

The hosted Neon MCP Server uses createNeonTools() directly and adds its own registration and access-control layer. registerNeonTools() is for teams building their own MCP server.

Mastra

Mastra is a TypeScript framework for building agents, tools, workflows, memory, and observability. The adapter maps Neon approval requirements into Mastra's requireApproval field and forwards its abort signal.

import { createTool } from "@mastra/core/tools";
import { createNeonTools } from "@neon/tools";
import { toMastraTools } from "@neon/tools/mastra";
const neonTools = createNeonTools({
  apiKey: process.env.NEON_API_KEY!,
  tools: ["projects.list", "projects.createAndConnect"],
});
const configs = toMastraTools(neonTools);
const listProjects = createTool(configs.list_projects);
const createProject = createTool(configs.create_and_connect_projects);

Eve

Eve is Vercel's durable agent framework. Its tools live as files under agent/tools/, and the filename becomes the model-facing name. The adapter maps approval requirements to Eve's approval hook and forwards its abort signal.

// agent/tools/create_and_connect_projects.ts
import { defineTool } from "eve/tools";
import { createNeonTool } from "@neon/tools";
import { toEveTool } from "@neon/tools/eve";
export default defineTool(
  toEveTool(
    createNeonTool("projects.createAndConnect", {
      apiKey: process.env.NEON_API_KEY!,
    }),
  ),
);

Getting started

We've treated agents as a core way to interact with Neon since we shipped our MCP server in December 2024. @neon/tools is the latest layer of that work.

Start building:

  • Use the hosted Neon MCP Server when you want a coding agent or MCP client to operate your Neon project. It includes OAuth, scopes, SQL and migration workflows, documentation search, and the expanded Management API catalog. The Neon MCP Server reference covers categories, access controls, and setup.
npx neon@latest mcp
  • Use @neon/tools when you are building an agent platform or embedding Neon tools inside your own agent runtime. Select only the SDK methods the agent needs, then expose them through your MCP server, an MCP-tool-capable agent, or frameworks like Mastra or Eve.
npm install @neon/tools
npx neon skills -s neon-postgres-agent-platforms