SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

How to integrate Neon MCP with OpenAI Agents SDK

Connect OpenAI Agents SDK to Neon MCP. Create a new neon project with autoscaling, add a developer's email permission to a project, and more using natural language, with authentication handled for you.

Get started for freeGet a demo
Neon logoNeon
Api Key

Neon is a serverless Postgres platform for building scalable apps faster. Its serverless architecture helps you launch, scale, and manage Postgres with zero overhead.

106 Tools

Introduction

This guide walks you through connecting Neon to the OpenAI Agents SDK using the Composio tool router. By the end, you'll have a working Neon agent that can create projects and branches, manage databases and roles, get connection strings, restore from snapshots, and configure compute endpoints through natural language commands.

This guide will help you understand how to give your OpenAI Agents SDK agent real control over a Neon account through Composio's Neon MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Neon with

Claude CodeClaude CoworkClaude Agent SDKMuseCodexOpenClawHermesAtomic AgentGoogle ADKLangChainVercel AI SDKMastra AILlamaIndexCrewAIPydantic AIAutoGen

TL;DR

Here's what you'll learn:
  • Get and set up your OpenAI and Composio API keys
  • Install the necessary dependencies
  • Initialize Composio and create a Tool Router session for Neon
  • Configure an AI agent that can use Neon as a tool
  • Run a live chat session where you can ask the agent to perform Neon operations

What is OpenAI Agents SDK?

The OpenAI Agents SDK is a lightweight framework for building AI agents that can use tools and maintain conversation state. It provides a simple interface for creating agents with hosted MCP tool support.

Key features include:

  • Hosted MCP Tools: Connect to external services through hosted MCP endpoints
  • SQLite Sessions: Persist conversation history across interactions
  • Simple API: Clean interface with Agent, Runner, and tool configuration
  • Streaming Support: Real-time response streaming for interactive applications

What is the Neon MCP server, and what's possible with it?

The Neon MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Neon account. It provides structured and secure access to your serverless Postgres projects, branches, databases, authentication, and network settings, so your agent can inspect projects, create branches, manage databases, protect access, and maintain credentials on your behalf.

  • Project creation and administration: Have your agent review project details, create projects with quotas and settings, transfer projects, or remove projects you no longer need.
  • Database branching and recovery: Let the agent create or delete project branches, count existing branches, build anonymized branches, and manage snapshots for safer development and testing.
  • Database and role management: Direct your agent to create databases within branches, remove obsolete databases, and add or delete PostgreSQL roles.
  • Authentication and user control: Instruct your agent to enable or disable Neon Auth, create or delete users, manage approved domains and OAuth providers, and configure keys for token authentication.
  • Private access and credential management: Have your agent manage private AWS network access rules and create or revoke personal and organization API keys.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
1

Prerequisites

Before starting, make sure you have:
  • Composio API Key and OpenAI API Key
  • Primary know-how of OpenAI Agents SDK
  • A live Neon project
  • Some knowledge of Python or Typescript
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key. You'll need credits to use the models, or you can connect to another model provider.
  • Keep the API key safe.
Composio API Key
3

Install dependencies

npm install @composio/openai-agents @openai/agents dotenv

Install the Composio SDK and the OpenAI Agents SDK.

4

Set up environment variables

bash
OPENAI_API_KEY=sk-...your-api-key
COMPOSIO_API_KEY=your-api-key
USER_ID=composio_user@gmail.com

Create a .env file and add your OpenAI and Composio API keys.

5

Import dependencies

import 'dotenv/config';
import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';
import { Agent, hostedMcpTool, run, OpenAIConversationsSession } from '@openai/agents';
import * as readline from 'readline';
What's happening:
  • You're importing all necessary libraries.
  • The Composio and OpenAIAgentsProvider classes are imported to connect your OpenAI agent to Composio tools like Neon.
6

Set up the Composio instance

dotenv.config();

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.USER_ID;

if (!composioApiKey) {
  throw new Error('COMPOSIO_API_KEY is not set. Create a .env file with COMPOSIO_API_KEY=your_key');
}
if (!userId) {
  throw new Error('USER_ID is not set');
}

// Initialize Composio
const composio = new Composio({
  apiKey: composioApiKey,
  provider: new OpenAIAgentsProvider(),
});
What's happening:
  • dotenv.config() loads your .env file so COMPOSIO_API_KEY and USER_ID are available as environment variables.
  • Creating a Composio instance using the API Key and OpenAIAgentsProvider class.
7

Create a Tool Router session

// Create Tool Router session for Neon
const session = await composio.create(userId as string, {
  toolkits: ['neon'],
});
const mcpUrl = session.mcp.url;

What is happening:

  • You give the Tool Router the user id and the toolkits you want available. Here, it is only neon.
  • The router checks the user's Neon connection and prepares the MCP endpoint.
  • The returned session.mcp.url is the MCP URL that your agent will use to access Neon.
  • This approach keeps things lightweight and lets the agent request Neon tools only when needed during the conversation.
8

Configure the agent

// Configure agent with MCP tool
const agent = new Agent({
  name: 'Assistant',
  model: 'gpt-5',
  instructions:
    'You are a helpful assistant that can access Neon. Help users perform Neon operations through natural language.',
  tools: [
    hostedMcpTool({
      serverLabel: 'tool_router',
      serverUrl: mcpUrl,
      headers: { 'x-api-key': composioApiKey },
      requireApproval: 'never',
    }),
  ],
});
What's happening:
  • We're creating an Agent instance with a name, model (gpt-5), and clear instructions about its purpose.
  • The agent's instructions tell it that it can access Neon and help with queries, inserts, updates, authentication, and fetching database information.
  • The tools array includes a hostedMcpTool that connects to the MCP server URL we created earlier.
  • The headers object includes the Composio API key for secure authentication with the MCP server.
  • requireApproval: 'never' means the agent can execute Neon operations without asking for permission each time, making interactions smoother.
9

Start chat loop and handle conversation

// Keep conversation state across turns
const conversationSession = new OpenAIConversationsSession();

// Simple CLI
const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: 'You: ',
});

console.log('\nComposio Tool Router session created.');
console.log('\nChat started. Type your requests below.');
console.log("Commands: 'exit', 'quit', or 'q' to end\n");

try {
  const first = await run(agent, 'What can you help me with?', { session: conversationSession });
  console.log(`Assistant: ${first.finalOutput}\n`);
} catch (e) {
  console.error('Error:', e instanceof Error ? e.message : e, '\n');
}

rl.prompt();

rl.on('line', async (userInput) => {
  const text = userInput.trim();

  if (['exit', 'quit', 'q'].includes(text.toLowerCase())) {
    console.log('Goodbye!');
    rl.close();
    process.exit(0);
  }

  if (!text) {
    rl.prompt();
    return;
  }

  try {
    const result = await run(agent, text, { session: conversationSession });
    console.log(`\nAssistant: ${result.finalOutput}\n`);
  } catch (e) {
    console.error('Error:', e instanceof Error ? e.message : e, '\n');
  }

  rl.prompt();
});

rl.on('close', () => {
  console.log('\n👋 Session ended.');
  process.exit(0);
});
What's happening:
  • The program prints a session URL that you visit to authorize Neon.
  • After authorization, the chat begins.
  • Each message you type is processed by the agent using run().
  • The responses are printed to the console.
  • Typing exit, quit, or q cleanly ends the chat.

Complete Code

Here's the complete code to get you started with Neon and OpenAI Agents SDK:

import 'dotenv/config';
import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';
import { Agent, hostedMcpTool, run, OpenAIConversationsSession } from '@openai/agents';
import * as readline from 'readline';

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.USER_ID;

if (!composioApiKey) {
  throw new Error('COMPOSIO_API_KEY is not set. Create a .env file with COMPOSIO_API_KEY=your_key');
}
if (!userId) {
  throw new Error('USER_ID is not set');
}

// Initialize Composio
const composio = new Composio({
  apiKey: composioApiKey,
  provider: new OpenAIAgentsProvider(),
});

async function main() {
  // Create Tool Router session
  const session = await composio.create(userId as string, {
    toolkits: ['neon'],
  });
  const mcpUrl = session.mcp.url;

  // Configure agent with MCP tool
  const agent = new Agent({
    name: 'Assistant',
    model: 'gpt-5',
    instructions:
      'You are a helpful assistant that can access Neon. Help users perform Neon operations through natural language.',
    tools: [
      hostedMcpTool({
        serverLabel: 'tool_router',
        serverUrl: mcpUrl,
        headers: { 'x-api-key': composioApiKey },
        requireApproval: 'never',
      }),
    ],
  });

  // Keep conversation state across turns
  const conversationSession = new OpenAIConversationsSession();

  // Simple CLI
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: 'You: ',
  });

  console.log('\nComposio Tool Router session created.');
  console.log('\nChat started. Type your requests below.');
  console.log("Commands: 'exit', 'quit', or 'q' to end\n");

  try {
    const first = await run(agent, 'What can you help me with?', { session: conversationSession });
    console.log(`Assistant: ${first.finalOutput}\n`);
  } catch (e) {
    console.error('Error:', e instanceof Error ? e.message : e, '\n');
  }

  rl.prompt();

  rl.on('line', async (userInput) => {
    const text = userInput.trim();

    if (['exit', 'quit', 'q'].includes(text.toLowerCase())) {
      console.log('Goodbye!');
      rl.close();
      process.exit(0);
    }

    if (!text) {
      rl.prompt();
      return;
    }

    try {
      const result = await run(agent, text, { session: conversationSession });
      console.log(`\nAssistant: ${result.finalOutput}\n`);
    } catch (e) {
      console.error('Error:', e instanceof Error ? e.message : e, '\n');
    }

    rl.prompt();
  });

  rl.on('close', () => {
    console.log('\nSession ended.');
    process.exit(0);
  });
}

main().catch((err) => {
  console.error('Fatal error:', err);
  process.exit(1);
});

Conclusion

This was a starter code for integrating Neon MCP with OpenAI Agents SDK to build a functional AI agent that can interact with Neon.

Key features:

  • Hosted MCP tool integration through Composio's Tool Router
  • SQLite session persistence for conversation history
  • Simple async chat loop for interactive testing
You can extend this by adding more toolkits, implementing custom business logic, or building a web interface around the agent.
TOOLS

Supported Tools

Every Neon action and event your agent gets out of the box.

Accept project transfer request

Accepts a pending transfer request and irreversibly moves the Neon project to the authenticated account or specified organization.

Count project branches

Tool to get the total number of branches in a Neon project.

Create API key

Creates a new personal API key for the authenticated Neon user account.

Create API Key for Organization

Creates a new API key for the specified organization in Neon.

Create Auth Provider SDK Keys

Tool to generate SDK or API keys for authentication providers.

Create auth user

Creates a Neon Auth user with an email and name for a specified project branch.

Create branch database

Creates a new database within a specified project and branch in the Neon platform.

Enable Neon Auth for branch

Tool to enable Neon Auth integration for a branch.

Create Neon Data API

Creates a Neon Data API REST endpoint for an existing branch database.

Create branch snapshot

Creates a snapshot from the specified branch at a specific point in time.

Create compute endpoint

Creates a compute endpoint for a Neon branch.

Create project branch

Creates a new branch in a Neon project.

Create anonymized branch

Creates a Beta anonymized branch using PostgreSQL Anonymizer.

Create project branch role

Creates a PostgreSQL role in a Neon branch.

Create project JWKS

Adds a new JSON Web Key Set (JWKS) URL to a Neon project for JWT-based authentication.

Create project permission

Grants the specified email address access to a Neon project.

Create project transfer request

Creates a transfer request for a Neon project.

Create project with quota and settings

Creates a Neon project and can also enable logical replication in its project settings.

Set VPC endpoint restriction

Sets or updates a VPC endpoint restriction for a Neon project.

Assign or Update VPC Endpoint

Assigns an existing AWS VPC endpoint to a Neon organization, or updates the label of that assignment.

Delete api key by id

Deletes a specific API key from the Neon platform.

Delete OAuth provider

Deletes an OAuth provider configuration from a specific branch in a Neon project.

Delete auth user

Deletes an authentication user from a specified branch within a Neon project.

Delete branch auth domains

Deletes domains from the redirect_uri whitelist for a specific branch's authentication configuration.

Delete branch data API

Deletes the Neon Data API for a specified branch and database.

Delete database from branch

Permanently deletes a database and all of its data from the specified project branch.

Delete organization api key

Deletes a specific API key associated with an organization in the Neon platform.

Delete organization member

Removes a specific member from a Neon organization.

Delete project branch by id

Deletes a branch and idles its compute endpoints, breaking existing client connections.

Delete project branch role

Deletes a PostgreSQL role from a specific branch within a Neon project.

Delete project by id

Deletes a Neon PostgreSQL project and all its associated resources.

Delete project endpoint

Deletes a specific endpoint within a Neon project.

Delete project jwks by id

Permanently deletes a JWKS configuration from a Neon project.

Delete project permission

Revokes project access for the user associated with a permission ID.

Delete project snapshot

Deletes a specific snapshot for a project in Neon.

Delete vpc endpoint by ids

Permanently deletes a VPC endpoint from a Neon organization in a specified AWS region.

Delete vpc endpoint by project id

Removes a VPC endpoint restriction from a Neon project.

Disable branches auth

Disables Neon Auth for a specified project branch, removing its connection to the authentication provider.

Finalize branch restore

Finalizes the restore operation for a branch created from a snapshot.

Get account consumption history

Retrieves selected consumption metrics for projects in a Neon organization, grouped by project, billing period, and the requested granularity.

Get auth

Retrieves authentication information about the current API request credentials.

Get auth allow localhost

Retrieves the allow localhost configuration for a specific branch in a Neon project.

Get auth email provider

Retrieves the email provider configuration for Neon Auth on a specific branch.

Get branch database

Returns metadata and configuration for one database in a project branch without modifying the database.

Get branches anonymized status

Retrieves the current status of an anonymized branch, including its state and progress information.

Get branches backup schedule

Retrieves the backup schedule configuration for a specified branch within a Neon project.

Get Neon Data API for branch

Retrieves the Neon Data API information for a specific branch and database.

Get branches masking rules

Retrieves the masking rules for the specified anonymized branch.

Get current user information

Gets account identifiers, plan details, and linked auth accounts for the currently authenticated Neon user.

Get organization

Retrieves one Neon organization's identity and account settings, including its name, handle, billing plan, management source, timestamps, and available organization-level flags.

Get organization member

Returns one organization's member record, including the associated user ID, organization role, and join timestamp.

Get project

Retrieves detailed information about a specific Neon serverless Postgres project.

Get project branch

Retrieves detailed information about a specific branch within a Neon project.

Get project branch role

Returns a specific PostgreSQL role's branch ID, name, protected status, authentication method, creation and update timestamps, and any related Neon operations.

Get project branch schema comparison

Compares the database schema of a branch with another branch's schema in a Neon project.

Get project connection uri

Returns a PostgreSQL connection URI for a database and role in a Neon project.

Get project endpoint

Retrieves detailed information about a specific compute endpoint within a Neon serverless PostgreSQL project.

Get project operation by id

Retrieves detailed information about a specific operation within a Neon serverless PostgreSQL project.

Get schema for project branch

Retrieves the PostgreSQL database schema (DDL) for a specific database on a branch within a Neon project.

Get VPC endpoint details

Retrieves the current state and configuration details of a specific VPC endpoint assigned to a Neon organization.

List api keys

Lists API keys for the authenticated user's Neon account, including key IDs, names, creators, creation times, and last-use metadata.

List auth domains

Lists trusted redirect domains for the specified project and branch.

List available preload libraries

Retrieves the list of available shared preload libraries for a Neon project.

List branch auth OAuth providers

Lists OAuth providers configured for a specific branch's Neon Auth integration.

List branch databases

Retrieves a list of databases associated with a specific project and branch in the Neon platform.

List branch endpoints

Retrieves all compute endpoints associated with a specific branch in a Neon project.

List organization API keys

Lists API keys for a Neon organization, including key IDs, names, creators, creation times, and last-use metadata.

List organization invitations

Lists pending invitations for a Neon organization.

List organization members

Retrieves one paginated page of organization members.

List project branches

Lists branches in a Neon project, optionally filtering by a partial branch name or ID.

List project branch roles

Lists Postgres roles on a specific Neon project branch.

List project consumption history

Lists paginated legacy project consumption history for an organization or the authenticated user's projects on eligible Scale, Business, and Enterprise plans, without waking sleeping computes.

List project endpoints

Lists compute endpoints for a Neon project, including each endpoint's ID, branch, hostname, state, region, autoscaling limits, and pooling settings.

List project JWKS configurations

Lists the JWKS URL configurations Neon uses to verify JWTs for a project.

List project operations

Lists one cursor-paginated page of asynchronous operations for a Neon project, including each operation's action, current status, timestamps, failure count, and associated branch or endpoint when applicable.

List project permissions

Lists email-based grants that give users access to a Neon project.

List projects

Lists one cursor-paginated page of projects for the specified organization, with summary project fields and installed application/integration maps.

List project snapshots

Lists snapshots for a Neon project, including their source branch, creation and expiration times, LSN, and whether they were created manually.

List project VPC endpoints

Lists the VPC endpoints associated with a Neon project.

List regions

Lists active geographic regions available for Neon projects, including region identifiers, names, default status, and geographic coordinates.

List shared projects

Lists Neon Postgres projects shared with the authenticated account.

List user organizations

Lists organizations the currently authenticated user belongs to.

List VPC endpoints for organization

Lists VPC endpoints for a Neon organization across all regions, including each endpoint's ID, label, and region.

List VPC region endpoints

Lists VPC endpoints for a Neon organization in one region, including each endpoint's ID and label.

Reset role password for branch

Resets the password for a PostgreSQL role on a specific Neon branch and generates a new password.

Restart project endpoint

Restarts a Neon compute endpoint (Postgres instance) within a project.

Restore project branch

Restores a branch from another point in its own or another branch's history, replacing the target branch's current data and creating a branch for the restored state.

Restore snapshot to new branch

Restores a snapshot by creating a new preview branch.

Reveal role password in branch

Reveals the password for a specific role within a branch of a Neon project.

Send auth test email

Sends one test email to the specified recipient using the supplied SMTP configuration.

Send organization invitations

Invites one or more people to a Neon organization with assigned roles.

Set branch as default

Sets a specified branch as the default branch for a given project in Neon.

Start branch anonymization

Starts the Beta anonymization process on an anonymized branch in the `initialized`, `error`, or `anonymized` state.

Start endpoint for project

Starts a suspended or idle compute endpoint for a Neon PostgreSQL project.

Suspend project endpoint by id

Suspends a specified Neon project's compute endpoint, helping manage compute resource usage and costs.

Transfer projects between organizations

Transfers selected projects from one organization to another organization.

Update auth allow localhost

Updates the localhost allow setting for Neon Auth on a specific branch, enabling or disabling localhost origins for authentication flows.

Update branch auth email provider

Updates the email provider settings for a Neon Auth branch, including the sender address and name used for authentication emails.

Update branch database

Updates the properties of a specific database within a project branch in the Neon platform.

Update branches data API

Updates the Neon Data API configuration for the specified branch.

Update branches masking rules

Updates the masking rules for the specified anonymized branch.

Update organization member role

Changes an organization member's role between `admin` and `member`, updating their ability to manage organization resources and members.

Update project branch

Updates the details of a specific branch within a project in the Neon platform.

Update project compute endpoint settings

Updates the configuration of a specific compute endpoint within a Neon project.

Update project settings by id

Updates selected project settings, including quotas, network access, maintenance, history retention, and default compute settings.

Update project snapshot

Tool to update the name of a specific snapshot in a Neon project.

FRAMEWORKS

How to build Neon MCP Agent with another framework

Claude Code logo

Claude Code

Use Neon MCP with Claude Code

Claude Cowork logo

Claude Cowork

Use Neon MCP with Claude Cowork

Claude Agent SDK logo

Claude Agent SDK

Use Neon MCP with Claude Agent SDK

Muse logo

Muse

Use Neon MCP with Muse

Codex logo

Codex

Use Neon MCP with Codex

OpenClaw logo

OpenClaw

Use Neon MCP with OpenClaw

Hermes logo

Hermes

Use Neon MCP with Hermes

Atomic Agent logo

Atomic Agent

Use Neon MCP with Atomic Agent

Google ADK logo

Google ADK

Use Neon MCP with Google ADK

LangChain logo

LangChain

Use Neon MCP with LangChain

Vercel AI SDK logo

Vercel AI SDK

Use Neon MCP with Vercel AI SDK

Mastra AI logo

Mastra AI

Use Neon MCP with Mastra AI

LlamaIndex logo

LlamaIndex

Use Neon MCP with LlamaIndex

CrewAI logo

CrewAI

Use Neon MCP with CrewAI

Pydantic AI logo

Pydantic AI

Use Neon MCP with Pydantic AI

AutoGen logo

AutoGen

Use Neon MCP with AutoGen

FAQ

Frequently asked questions

With a standalone Neon MCP server, the agents and LLMs can only access a fixed set of Neon tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Neon and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. OpenAI Agents SDK fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Neon tools.

Yes, absolutely. You can configure which Neon scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Neon data and credentials are handled as safely as possible.

Start with Neon.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Neon tool your agent needs.Free to start.

Start building