Connect your assistant to Neon.

Use Neon's MCP server when you want your coding assistant to inspect or work on a Neon project. For the API-key route, the credential is a Neon management API key. A database password, a postgresql:// connection string, and an application's end-user login token are different credentials.

1. Choose how to connect

Start with browser authorization, also called OAuth. Your client opens Neon in your browser, where you review and approve access. You do not need to create an API key or pass a value through Keyhole.

Use a development or test project containing no personal or production data. Neon recommends its MCP server for development and testing. Depending on configuration, its tools can read database contents and make changes. See Neon's security guidance.

2. Authorize in your browser

1. In your terminal, run npx neon@latest mcp --oauth --read-only. It uses Neon's installer and requires Node.js and npx.
2. Choose the configuration location and only the client you intend to use. For a personal setup, choose the per-user location. Review the destination displayed before the installer writes.
3. Restart the client if needed. On the first Neon tool request, complete the browser sign-in and review the requested access.
4. Continue to the connection check.

The explicit --oauth option avoids minting an API key. Without it, the installer can create a key and write it into client configuration. The --read-only option restricts MCP operations; it does not change an API key's scope. See Neon's installer reference.

The installer selects a file for the chosen client. This is a client configuration step, not a write to your project's .env. See Assistant settings before choosing another destination.

For Claude Desktop, Neon also offers a browser-authorized connector under Customize → Connectors. See Neon's connector instructions.

Keep the first connection narrow

Neon's server supports readonly=true and an optional projectId in its URL. A project restriction limits this MCP connection, separately from the credential's scope. A database role can further limit SQL access, but creating and granting that role is a separate task. Consult Neon's access-control reference before enabling writes or connecting another project.

Alternative: obtain a management API key

1. Prepare the receiving configuration first. Sign in to the Neon Console.
2. For a personal key, open your profile menu, then Settings → API keys, and create a key for this client.
3. If you administer an organization and need only one project, use its Settings → API keys → Create new → Project-scoped route and select the project.
4. Copy the new value directly to the receiving field. It is shown once; a lost value must be replaced.

Personal keys follow your account's access. Organization-wide keys grant broad access. A project-scoped key still permits changes within its project; it is not read-only. Only organization administrators can create organization and project-scoped keys. See Neon's key types and creation instructions.

Put the key in the client's configuration

Have your assistant prepare a placeholder configuration before you enter the value. Apply the file-access protections. Keep the key out of assistant-run commands, chat, and shared files. Do not ask the assistant to open the receiving file after you enter it.

Claude Code: reference the key by name

Prepare this project-root .mcp.json configuration. Merge the neon entry with existing servers rather than replacing them.

{
  "mcpServers": {
    "neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?readonly=true",
      "headers": {"Authorization": "Bearer ${NEON_API_KEY}"}
    }
  }
}

1. Leave ${NEON_API_KEY} unchanged. Privately set env.NEON_API_KEY in the project's .claude/settings.local.json, following the protected settings walkthrough. Enter the raw key, without a Bearer prefix.
2. Restart Claude Code in this project. Review its MCP approval request and approve the intended Neon server. Then check the connection below.

This combines Neon's bearer authentication with Claude Code's variable references and Neon's read-only option. It is documentation-derived, not account-tested. For another client, follow Neon's client-specific instructions.

This configuration stores the key locally and connects to Neon's hosted server. Use the /mcp endpoint. The old /sse endpoint and @neondatabase/mcp-server-neon local package are deprecated; see Neon's migration notes.

3. Check the connection without reading a secret

For a connection without a single-project restriction, ask:

Use Neon's MCP tools to list only my project names and IDs.
Do not run SQL, retrieve a connection string, or change anything.

If you restricted the connection to one project, ask for that project's name and ID instead. Do not widen access merely to make a cross-project listing work. These inspection tasks are supported by Neon's server.

Success means Neon accepted that lookup. It does not prove database-query access or permission to make changes. If it fails, share the client name and error category without the key, settings file, connection string, request headers, or raw debug log.

4. Remove or replace access

For an API key, return to its API keys page and use Revoke. Revocation is immediate and permanent. For planned rotation, create a replacement, update each client, verify, then revoke the old key. If exposed, revoke it first. See Neon's revocation and rotation instructions.

For Claude Code OAuth, open /mcp, select Neon, and use Clear authentication; disable the server if it is no longer needed. See Claude Code's authentication controls. Deleting local settings is not evidence that every issued OAuth token was revoked. This review did not establish Neon Console clicks for provider-side OAuth revocation; contact Neon support if an OAuth credential may have been exposed.

For the assistant guiding this step

Use the assistant handoff reference to present this guide through Porthole. OAuth needs no Keyhole request. For an API key, establish the receiving client, exact setting name, value format, destination, and loading step first. Report the observed result without asking to see the value.

Source notes

The linked Neon and client documentation was reviewed on 24 October 2026. Commands, configuration, and account flows are documentation-checked, not verified in a running MCP client or Neon account.