Neon MCP Server

Translates conversational requests into structured Neon API calls by mapping natural language intents to a pre-defined tool registry exposed via the Model Context Protocol. The system uses a layered architecture where LLM clients send text prompts, the MCP server parses tool invocations, and a Neon API client layer executes authenticated requests. This enables users to manage databases through conversation rather than direct API calls or CLI commands.

Implements two distinct deployment modes with different transport and authentication mechanisms: local mode uses stdio transport with API key authentication for IDE integration, while remote mode uses Server-Sent Events (SSE) with OAuth 2.0 for web-based clients. The architecture abstracts transport differences behind a unified MCP tool interface, allowing the same tool definitions to work across both modes. This enables developers to choose deployment based on security posture and client architecture.

Implements a built-in OAuth 2.0 server supporting multiple identity providers (Google, GitHub, etc.) for authenticating remote MCP clients. The implementation handles OAuth flows (authorization code, token refresh), manages user sessions, and issues access tokens that are validated on subsequent requests. This enables secure remote deployment of the MCP server without requiring users to manage API keys directly.

Provides structured logging of all MCP tool invocations, including request parameters, execution time, and response status. The implementation logs to stdout in JSON format suitable for log aggregation systems, enabling monitoring of tool usage patterns and performance. Metrics include execution latency, error rates, and tool popularity, helping teams understand how the MCP server is being used and identify performance bottlenecks.

Executes arbitrary SQL queries against Neon databases by accepting SQL text, managing database connections through Neon's connection string API, and streaming results back to the client. The implementation handles connection pooling, error recovery, and result formatting (JSON, CSV, or raw). Queries are executed in the context of a specific Neon project and database, with optional branch selection for testing migrations before production deployment.

Automates creation, deletion, and configuration of Neon projects and database branches by wrapping Neon's project management API. Supports operations like creating new projects, listing existing branches, creating test branches from production, and managing branch compute resources. The implementation maintains state consistency by validating project existence before operations and handling async branch creation workflows. This enables LLMs to provision isolated testing environments and manage multi-branch database architectures.

Retrieves database schema information (tables, columns, indexes, constraints) by querying PostgreSQL system catalogs through the SQL execution layer. The implementation caches schema metadata to reduce API calls and provides structured output suitable for LLM context windows. This enables LLMs to understand database structure before generating queries or migrations, improving query accuracy and preventing schema-related errors.

Orchestrates database migrations by creating isolated test branches, applying schema changes, validating results, and optionally promoting to production. The workflow uses Neon's branching to create a safe testing environment, executes migration SQL on the test branch, allows validation queries, and then applies the same migration to production only after confirmation. This pattern prevents production downtime by catching migration errors in isolation before they affect live databases.

Analyzes query performance by executing EXPLAIN ANALYZE on test branches and providing optimization recommendations. The implementation runs queries on isolated branches to avoid impacting production, collects execution plans, identifies bottlenecks (sequential scans, missing indexes), and suggests optimizations. This enables LLMs to understand query performance characteristics and propose index creation or query rewrites without manual profiling.

Generates database connection strings dynamically through the Neon API, supporting multiple connection formats (psql, JDBC, Node.js, Python) and authentication methods. The implementation retrieves credentials from Neon's API rather than storing them statically, ensuring credentials are always current and can be rotated without code changes. Connection strings are scoped to specific projects, databases, and branches, enabling fine-grained access control.

Defines a comprehensive tool registry with JSON Schema descriptions for all database operations, enabling LLM clients to understand available tools and invoke them with proper parameters. The implementation uses OpenAI-compatible function calling format, allowing Claude, GPT-4, and other LLMs to automatically select and invoke appropriate tools based on user intent. Tool schemas include parameter validation, return type documentation, and usage examples suitable for LLM context windows.

Implements comprehensive error handling that catches Neon API errors, database connection failures, and SQL execution errors, then returns structured error responses with remediation guidance. The implementation distinguishes between recoverable errors (rate limits, temporary connection failures) and fatal errors (invalid credentials, schema errors), providing appropriate retry logic and user-facing error messages. This enables LLMs to understand what went wrong and suggest corrective actions.