Neon MCP Server

Translates conversational requests into executable SQL queries against Neon PostgreSQL databases by mapping natural language intents to a structured tool registry that invokes the Neon API. The system maintains a layered architecture where user prompts are parsed by the MCP server, routed through tool handlers that construct parameterized SQL statements, and executed against live Neon connections with error handling and result formatting. This bridges the gap between LLM reasoning and database operations without requiring users to write SQL directly.

Provides structured tools for creating, listing, and managing Neon projects and database branches via the Neon API, exposed through the MCP tool system. Each operation (create_project, create_branch, delete_branch, list_branches) is implemented as a discrete MCP tool with schema validation, parameter binding, and response transformation. The system maintains a mapping between natural language requests and these tools, allowing LLMs to orchestrate multi-step workflows like creating isolated test branches, running migrations, and promoting changes to production.

Provides a web-based landing page and client UI that enables users to discover and interact with the MCP server through a browser. The landing page displays available tools, their descriptions, and usage examples. The client UI allows users to authenticate (via OAuth), invoke tools through a form-based interface, and view results. This web interface serves as both documentation and a testing ground for tools, enabling non-technical users to interact with the MCP server without writing code. The UI is built with Next.js and includes OAuth integration for authentication.

Generates and manages Neon connection strings with role-based access control through the MCP tool system. The system constructs connection strings with configurable parameters (SSL mode, application name, statement timeout) and exposes them through tools that respect Neon's connection pooling requirements and role isolation. Connection credentials are never stored in the MCP server — they are generated on-demand and passed to clients, maintaining security boundaries between the MCP server and consuming applications.

Orchestrates safe database schema migrations by leveraging Neon's branching feature to test changes in isolation before applying them to production. The workflow creates a temporary branch from the production database, executes migration SQL against the branch, validates results, and conditionally promotes changes to the main branch. This is implemented through a multi-step tool sequence that coordinates branch creation, SQL execution, validation checks, and branch promotion/deletion, all exposed through the MCP tool registry.

Analyzes query execution plans and generates optimization recommendations by executing EXPLAIN ANALYZE against Neon databases and parsing the output. The system runs queries in isolation on test branches to avoid impacting production, collects execution statistics (sequential scans, index usage, row estimates), and uses pattern matching to identify common performance anti-patterns (missing indexes, full table scans, inefficient joins). Recommendations are returned as structured data that can be presented to users or automatically applied as schema changes.

Implements the Model Context Protocol server with two distinct transport mechanisms: local stdio mode for IDE integration (Claude Desktop, Cursor) and remote SSE/streaming mode for web-based clients. The architecture abstracts transport differences behind a unified tool registry, allowing the same tools to be exposed through both transports. Local mode uses stdio for synchronous request-response patterns with API key authentication, while remote mode uses Server-Sent Events for streaming responses with OAuth 2.0 authentication. This dual-mode design enables the same MCP server to serve both development (IDE) and production (web) use cases.

Implements an OAuth 2.0 authorization server that authenticates remote MCP clients and issues access tokens for API access. The system supports multiple OAuth providers (GitHub, Google, or custom implementations) and manages token lifecycle (issuance, refresh, revocation). Tokens are validated on every MCP request, and scopes are used to control which tools each client can access. The authentication system is integrated with the remote SSE transport mode, enabling secure multi-client deployments where each client has isolated credentials and audit trails.

Implements a structured tool registry that defines MCP tools with JSON schemas, parameter validation, and automatic binding to handler functions. Each tool (create_project, execute_query, create_branch, etc.) is registered with a schema that describes its inputs, outputs, and error conditions. When an MCP client calls a tool, the registry validates parameters against the schema, binds them to the handler function, executes the handler, and validates the response against the output schema. This pattern ensures type safety and enables LLMs to understand tool capabilities through schema introspection.

Provides a set of utility functions and error handling patterns tailored to Neon's serverless Postgres architecture. The system includes helpers for connection management (handling auto-suspend, connection limits), error classification (distinguishing between transient and permanent failures), and retry logic with exponential backoff. Error responses are structured to include diagnostic information (error code, message, suggested remediation) that helps LLMs understand what went wrong and how to recover. Utilities also handle Neon-specific edge cases like branch creation timeouts and connection pooling configuration.

Implements structured logging and observability for all MCP operations, including tool invocations, API calls, authentication events, and errors. The system logs events in JSON format with contextual metadata (request ID, user, tool name, execution time, result status) that enables tracing requests through the system. Logs are designed to be machine-readable for integration with log aggregation systems (ELK, Datadog, CloudWatch) and human-readable for debugging. The observability system includes metrics collection (tool call counts, latency percentiles, error rates) that can be exported to monitoring systems.