Neon

Translates conversational requests into structured Neon API calls through the Model Context Protocol (MCP) interface. The system implements a tool registry that maps natural language intents to specific database management operations (project creation, branch operations, SQL execution) by exposing tools with JSON schemas that LLM clients can invoke. Requests flow through stdio (local) or SSE/streaming (remote) transport layers, with the server parsing tool invocations and executing corresponding Neon API operations.

Enables creation, deletion, and configuration of Neon projects and database branches through conversational commands. The system exposes tools for project creation with configurable regions, branch creation/deletion with automatic parent tracking, and branch promotion workflows. Internally, it maintains state about project hierarchies and branch relationships, translating natural language requests like 'create a staging branch from main' into Neon API calls that handle branch isolation and resource provisioning.

Implements structured logging that captures request context, execution traces, and performance metrics. The system logs MCP protocol messages, tool invocations, API calls, and database queries with structured metadata (request ID, user ID, operation type, duration). Logs are formatted as JSON for easy parsing and aggregation, enabling monitoring and debugging of production deployments. Context is propagated through the request lifecycle, allowing correlation of related log entries.

Executes arbitrary SQL queries against Neon databases and returns structured result sets with automatic schema introspection. The system implements a query execution layer that connects to Neon databases via connection strings, executes parameterized queries, and returns results as JSON-serializable objects. It includes error handling that distinguishes between syntax errors, permission errors, and connection failures, providing diagnostic context to help LLM clients understand and recover from failures.

Orchestrates safe database migrations by creating isolated test branches, executing migration scripts, validating results, and promoting changes to production. The system implements a multi-step workflow that leverages Neon's branching feature: it creates a temporary branch from production, executes migration SQL on the branch, runs validation queries to verify correctness, and provides rollback capabilities. This pattern enables LLM agents to propose and test schema changes without risking production data.

Analyzes query performance by executing EXPLAIN ANALYZE on user queries, extracting execution plan details, and generating optimization suggestions. The system runs EXPLAIN ANALYZE to capture query execution plans, parses the plan output to identify expensive operations (sequential scans, nested loops), and uses heuristics to suggest optimizations (index creation, query restructuring). Results are returned as structured data that LLM clients can interpret and present to users.

Supports two deployment architectures with different authentication and transport mechanisms: local mode (stdio transport with API key authentication) for development and IDE integration, and remote mode (SSE/streaming transport with OAuth authentication) for production web clients. The system abstracts authentication differences behind a unified interface, allowing the same tool implementations to work across both modes. Local mode reads API keys from environment variables, while remote mode implements an OAuth server that handles token exchange and refresh.

Implements a complete OAuth 2.0 authorization server for remote mode deployment, handling token generation, validation, and refresh flows. The system includes an OAuth endpoint that exchanges authorization codes for access tokens, implements token expiration and refresh token rotation, and validates incoming requests using bearer tokens. This enables secure multi-user access to the MCP server without exposing API keys to clients.

Maintains a registry of available tools with JSON schema definitions that describe tool parameters, return types, and documentation. The system exposes this registry to MCP clients, enabling them to discover available operations and validate tool invocations before execution. Each tool is defined with a schema that specifies required parameters, parameter types, and descriptions, allowing LLM clients to generate appropriate tool calls without manual schema management.

Generates connection strings for Neon databases and manages database connections for query execution. The system constructs connection strings from project and branch metadata, handles connection pooling (or creates new connections per query), and manages connection lifecycle (opening, closing, error handling). It abstracts PostgreSQL connection details behind a simple interface that accepts database identifiers and returns query results.

Categorizes database and API errors into semantic categories (syntax errors, permission errors, connection failures, resource not found) and generates diagnostic context to help users understand and recover from failures. The system parses error messages and error codes from PostgreSQL and the Neon API, maps them to user-friendly categories, and provides suggestions for resolution. This enables LLM clients to present errors in context and suggest corrective actions.