# Connect your assistant to Neon.

Authorize the hosted MCP server, or choose an API key when your client needs one. A database connection string is a separate setting.

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.

 

> Guide preview. Steps checked against official documentation on 24 October 2026; sign-in and connection checks have not yet been tested here.

 

## 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](https://neon.com/docs/ai/neon-mcp-server#mcp-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](https://jlumbroso.github.io/keyhole-docs/neon-mcp.html#verify-connection).

 

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](https://neon.com/docs/cli/mcp).

 

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](https://jlumbroso.github.io/keyhole-docs/assistant-settings.html) before choosing another destination.

 

For Claude Desktop, Neon also offers a browser-authorized connector under **Customize → Connectors**. See [Neon's connector instructions](https://neon.com/docs/ai/neon-mcp-server#claude-connector).

 

## 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](https://neon.com/docs/ai/neon-mcp-server#access-control) 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](https://console.neon.tech).
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](https://neon.com/docs/manage/api-keys).

 

## 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](https://jlumbroso.github.io/keyhole-docs/keeping-secrets-out-of-the-conversation.html). 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](https://jlumbroso.github.io/keyhole-docs/assistant-settings.html). 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](https://neon.com/docs/ai/connect-mcp-clients-to-neon#claude-code) with [Claude Code's variable references](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcpjson) and Neon's read-only option. It is documentation-derived, not account-tested. For another client, follow [Neon's client-specific instructions](https://neon.com/docs/ai/connect-mcp-clients-to-neon).

 

> Keyhole currently writes the project's `.env`, not `.claude/settings.local.json`. Saving `NEON_API_KEY` through Keyhole does not complete the settings step above. For now, that step is a private human edit. See [the destination distinction](https://jlumbroso.github.io/keyhole-docs/assistant-settings.html).

 

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](https://neon.com/docs/ai/neon-mcp-server#troubleshooting).

 

## 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](https://github.com/neondatabase/mcp-server-neon).

 

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](https://neon.com/docs/manage/api-keys#revoke-api-keys).

 

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](https://code.claude.com/docs/en/mcp#authenticate-with-remote-mcp-servers). 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](https://jlumbroso.github.io/keyhole-docs/for-assistants.html) 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.

## Chapter notes

**Two credentials**

A Neon API key manages Neon resources. DATABASE_URL connects an application to a database.

**Documentation checked**

Official sources reviewed on 24 October 2026. This guide has not been tested against a signed-in account.

Keyhole 0.1.0 · previews labeled separately. Updated 24 October 2026. [Online chapter](https://jlumbroso.github.io/keyhole-docs/neon-mcp.html). [Source reference](https://github.com/jlumbroso/keyhole/blob/main/docs/manual/content/neon-mcp.html).

Source access currently requires a repository invitation.