{"slug": "give-your-agent-neon-tools", "title": "Give your agent Neon tools", "summary": "Neon launched @neon/tools, a package that converts its @neon/sdk ergonomic client into typed agent tools with adapters for MCP, Mastra, and Eve, and expanded its hosted Neon MCP Server to expose 101 tools total—82 Management API tools plus 19 hand-written tools for SQL, migrations, diagnostics, docs, and search. The release addresses context bloat and workflow inefficiencies by layering product-level decisions over the raw OpenAPI spec, enabling agents to execute complex operations like branch creation in a single call.", "body_md": "**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](https://neon.com/docs/ai/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.**\n\nIf 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:\n\n## Rethinking generated agent tools, one year later\n\nAbout a year ago, we wrote that [turning an OpenAPI spec directly into an MCP server](https://neon.com/blog/autogenerating-mcp-servers-openai-schemas) was a shaky default. What has changed?\n\nBack then, we identified two problems:\n\n1. 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.\n2. 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.\n\nMCP 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](https://modelcontextprotocol.io/docs/2026-07-28/develop/clients/client-best-practices) describe the flow as search, inspect, execute. That makes larger tool catalogs practical, and it solves the first problem.\n\nThe 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.\n\nNeon 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`.\n\nA generated schema can describe a request body, but it does not decide:\n\n- whether a create call should wait until the resource is ready\n- whether the result should include a connection string\n- which low-level operations should stay hidden\n- when several API calls should become one workflow\n- which tool names and descriptions help a model choose correctly\n\nThese are product decisions that happen at a level above the raw API spec.\n\nTraditional 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.\n\nThe [Neon OpenAPI spec](https://neon.com/api_spec/release/v2.json) code-generates typed fetch functions and Zod request schemas. [`@neon/sdk`](https://neon.com/blog/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.\n\nTwo packages `@neon/sdk` and `@neon/tools` now build on top of each other:\n\n`@neon/sdk`: OpenAPI spec → code generation → `@neon/sdk` raw methods → coding-agent-authored layer → `createNeonClient()` ergonomic client\n`@neon/tools`: OpenAPI spec → code generation → `@neon/tools` Zod request schemas + `@neon/sdk` ergonomic layer → agent tools\n\n`@neon/tools` is the agent-facing end of that pipeline.\n\n## Building @neon/tools\n\nWe built `@neon/tools` in part to expand the hosted [Neon MCP Server](https://neon.com/docs/ai/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.\n\n### Building great MCP and CLIs for agents\n\nCLIs 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.\n\nFor 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.\n\nOnce 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.\n\n### Turning SDK methods into agent tools\n\n`@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:\n\n`@neon/tools` lets you select the functions from the `@neon/sdk` ergonomic layer and turns them into MCP tools.\n\n- `projects.list` becomes`list_projects`\n- `projects.createAndConnect` becomes`create_and_connect_projects`\n- `postgres.roles.resetPassword` becomes`reset_password_postgres_roles`\n\n## @neon/tools now powers Neon MCP\n\nWith `@neon/tools`, we grew the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server) to over 101 tools. The expanded surface includes:\n\n- project updates, recovery, members, permissions, regions, and operations\n- branch, Postgres role, and database management\n- compute endpoint lifecycle operations\n- snapshot creation, schedules, and restore\n- Managed Better Auth providers, trusted domains, and users\n- Data API configuration\n- Functions deployment and management\n- Object Storage buckets, objects, and presigned URLs\n\nThe 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.\n\nThis is still the hybrid model [we argued for in 2025](https://neon.com/blog/autogenerating-mcp-servers-openai-schemas):\n\n- Use generated schemas and shared runtime behavior for broad Management API coverage.\n- Keep opinionated tools for tasks where the agent needs a workflow, not an HTTP operation.\n\nThe 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:\n\nYou can also scope the connection to one project or make it read-only:\n\n## Safety stays with the host\n\nEvery 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.\n\nThose annotations are advice to the host. The protocol does not enforce approval by itself.\n\nThe hosted Neon MCP Server builds on top of the `@neon/tools`:\n\n- OAuth or API-key authentication\n- read-only mode\n- project-scoped grants\n- category filtering\n- project and branch ID injection\n- result sanitization\n- fixed model-facing names and descriptions\n\n## With native adapters for MCP, Mastra, and Eve\n\nOnce we figured out MCP tools, we didn't stop there. `@neon/tools` publishes the same descriptors through three adapters:\n\n### MCP\n\n`@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`.\n\nThe 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.\n\n### Mastra\n\n[Mastra](https://mastra.ai/) 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.\n\n### Eve\n\n[Eve](https://eve.dev/) 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.\n\n## Getting started\n\nWe've treated agents as a core way to interact with Neon since we [shipped our MCP server](https://neon.com/blog/let-claude-manage-your-neon-databases-our-mcp-server-is-here) in December 2024. `@neon/tools` is the latest layer of that work.\n\nStart building:\n\n- **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](https://neon.com/docs/ai/neon-mcp-server) covers categories, access controls, and setup.\n\n- **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.", "url": "https://wpnews.pro/news/give-your-agent-neon-tools", "canonical_source": "https://neon.com/blog/give-your-agent-neon-tools", "published_at": "2026-09-03 12:00:00+00:00", "updated_at": "2026-09-08 20:26:09.792286+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Neon", "@neon/tools", "@neon/sdk", "Neon MCP Server", "Mastra", "Eve"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/give-your-agent-neon-tools", "markdown": "https://wpnews.pro/news/give-your-agent-neon-tools.md", "text": "https://wpnews.pro/news/give-your-agent-neon-tools.txt", "jsonld": "https://wpnews.pro/news/give-your-agent-neon-tools.jsonld"}}