Connect Neon PostgreSQL to Claude and Cursor with MCP

The short answer

Neon is managed PostgreSQL, so you can connect it to Claude or Cursor through datamcp without a provider-specific integration.

The request path is:

Neon PostgreSQL → DataMCP connection → scoped MCP link → Claude or Cursor

Use the standard PostgreSQL connection string from the target Neon branch, create a dedicated database role, start with a read-only MCP link, and give the AI client the remote MCP credential rather than the Neon database password.

datamcp currently supports PostgreSQL connections. It does not use the Neon Management API and does not expose Neon projects, branches, compute settings, billing, or platform administration tools.

What this setup gives Claude and Cursor

Through the PostgreSQL MCP connection, Claude and Cursor can use schema and database tools to:

• list schemas and tables
• inspect columns, relationships, indexes, and constraints
• understand the live database structure before proposing SQL
• run queries allowed by both the MCP link and PostgreSQL role
• return bounded query results to the AI client

The client does not receive the Neon connection string. datamcp stores the database credential server-side and the client authenticates separately to the remote MCP endpoint.

This is database access, not a native Neon control-plane integration.

Direct vs pooled Neon connections

Neon offers direct and pooled PostgreSQL connection strings. Both reach the selected database branch, but they have different session behavior.

Start with the direct connection string for a hosted MCP gateway. It avoids transaction-pool limitations around session state, SET, LISTEN, session-level advisory locks, and similar PostgreSQL behavior.

Use the pooled endpoint when direct connection limits are the actual constraint and your intended tools only need ordinary schema reads and short transactions. Neon's connection pooling documentation explains the PgBouncer transaction-mode limitations.

Before you start

You need:

• a Neon project and target branch
• permission to create or configure a PostgreSQL role on that branch
• a datamcp account
• Cursor, Claude, Claude Desktop, or Claude Code with remote MCP support available
• a clear list of schemas and tables the AI client should access

Use a development branch for the first test. Neon branches make it practical to validate schema discovery and prompts without starting against the primary production branch.

Step 1: Copy the Neon connection string

Open the Neon Console, select the project and branch, then open Connect.

Choose the database and role, select the direct connection when available, and copy the PostgreSQL URI. It follows this pattern:

postgresql://YOUR_ROLE:YOUR_PASSWORD@ep-example-123456.us-east-2.aws.neon.tech/neondb?sslmode=require

A pooled hostname includes -pooler:

postgresql://YOUR_ROLE:YOUR_PASSWORD@ep-example-123456-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require

Treat the full URI as a secret. Do not paste it into Claude, Cursor, prompts, source control, screenshots, or team chat.

Neon requires TLS for PostgreSQL connections and supports verify-full, which verifies both the certificate authority and server hostname. Use the secure connection values provided by Neon and prefer sslmode=verify-full where your client trust-store configuration supports it. Do not change the URI to sslmode=disable.

Step 2: Create a restricted Neon role

The role selected in Neon's Connect dialog may be an owner-level project role. Do not use that broad credential for routine AI access when a narrower role is possible.

Create a dedicated login on the target branch with SQL. For a read-only public schema example:

create role ai_mcp_reader
  login
  password 'GENERATE_A_LONG_UNIQUE_PASSWORD';

grant connect on database neondb to ai_mcp_reader;
grant usage on schema public to ai_mcp_reader;
grant select on all tables in schema public to ai_mcp_reader;

alter default privileges in schema public
grant select on tables to ai_mcp_reader;

Review and adapt this SQL before execution:

• replace neondb with the selected database
• grant only the schemas the workflow needs
• omit default privileges if future tables should require explicit review
• add individual table grants when the whole schema is too broad
• create a different role for each environment or risk level

Neon documents an important role distinction: roles created through its Console, CLI, or API can receive membership in neon_superuser, while a role created with SQL receives only the privileges you explicitly grant. A SQL-created dedicated role is therefore a useful starting point for least-privilege MCP access.

Test the role before connecting it:

psql "postgresql://ai_mcp_reader:YOUR_PASSWORD@YOUR_DIRECT_HOST/neondb?sslmode=require"

Then confirm that expected SELECT statements succeed and writes fail.

Step 3: Add Neon to datamcp

Open the datamcp dashboard, create a connection, and choose PostgreSQL.

Paste the complete Neon connection string or enter the values individually:

• host: the direct or pooled Neon endpoint
• port: 5432
• database: the selected Neon database
• username: the dedicated role
• password: the role password
• SSL mode: the verified TLS mode supported by the connection

datamcp accepts PostgreSQL URIs beginning with postgresql:// or postgres:// and requires an SSL-enabled mode for remote database validation.

Validate the connection. datamcp should discover only the schemas and objects visible to the dedicated PostgreSQL role.

If the connection wakes a suspended Neon compute, the first validation or query may take longer than later requests. This is normal for branches configured to scale to zero.

Step 4: Create a read-only MCP link

Open the Neon connection and create an MCP link. Choose Read Only for the first client.

The effective access is the intersection of two layers:

1. Neon PostgreSQL role: the database-enforced maximum
2. datamcp link: the client-specific policy applied before execution

A read-only database role prevents writes even if a broader MCP preset is selected later. A read-only MCP link can further restrict a more capable database credential.

datamcp also supports read-write, full-access, and custom table-level operation policies. Expand access only for a documented workflow after the read-only path has been tested.

Create separate links for Claude and Cursor rather than sharing one link across both. This improves attribution and lets you revoke or narrow one client without interrupting the other.

Step 5: Connect Cursor

Cursor supports remote MCP servers through project or global mcp.json configuration.

Use a project-specific file when the Neon branch belongs to one codebase:

.cursor/mcp.json

Use the global file only when the same connection should appear in every project:

~/.cursor/mcp.json

Copy the Cursor configuration generated by the datamcp setup guide. It follows this structure:

{
  "mcpServers": {
    "neon-postgres": {
      "url": "https://api.datamcp.app/api/mcp/YOUR_CONNECTION_ID",
      "headers": {
        "Authorization": "Bearer YOUR_DATAMCP_API_KEY"
      }
    }
  }
}

The Bearer value is a datamcp API key, not the Neon password.

Do not commit a real key in a shared project file. Use the secret-handling mechanism appropriate for your environment, then open Cursor Settings → Tools & MCP and verify that the server connects.

Keep tool approval enabled while testing. Cursor's official MCP documentation recommends reviewing server permissions and tool calls before enabling broader automatic execution.

Step 6: Connect Claude or Claude Desktop

Anthropic currently supports custom remote MCP connectors for eligible Claude and Claude Desktop plans.

In Claude:

1. Open Customize → Connectors.
2. Choose Add custom connector.
3. Give the connector a recognizable name such as Neon read-only.
4. Paste the remote OAuth URL generated by the datamcp Claude setup guide.
5. Complete the datamcp authorization flow.
6. Enable only the database tools needed for the conversation.

Free, Pro, and Max users can add an individual custom connector; Free accounts currently have one custom connector slot. Team and Enterprise organizations require an Owner or Primary Owner to add the organization connector before members connect it individually. Anthropic's current custom connector guide documents plan availability and administrative steps.

Claude receives the remote MCP authorization, not the Neon database password.

Step 7: Connect Claude Code

Claude Code supports remote HTTP MCP servers. Use the exact URL and command shown in the datamcp connection's setup guide. The general command shape is:

claude mcp add --transport http neon-postgres YOUR_DATAMCP_MCP_URL

Then run /mcp inside Claude Code and complete the browser authentication flow when prompted.

Do not add the Neon connection string as a Claude Code environment variable for this hosted path. datamcp already holds the PostgreSQL credential behind the MCP endpoint.

Step 8: Test schema discovery first

Start with the same non-destructive prompt in each client:

Use the Neon PostgreSQL MCP server to list visible schemas and summarize the tables in public. Do not query row data and do not attempt writes.

Then inspect one table:

Show the columns, types, primary key, foreign keys, and indexes for public.orders. Do not run a data query yet.

Finally, test a bounded read:

Return at most five recent orders using only non-sensitive columns. Explain the SQL before executing it.

Review the tool request in Claude or Cursor, then check the datamcp activity history. Confirm that the connection, MCP link, query, status, execution time, and row count are attributable.

Step 9: Verify denial and revocation

A successful SELECT is only half of the test. Verify the controls:

1. Ask the client to propose an UPDATE without executing it.
2. Confirm the read-only link blocks the operation if execution is attempted.
3. Delete or revoke a test MCP link.
4. Confirm the configured client can no longer query Neon.
5. Create a replacement link rather than reusing a shared credential.

Test the PostgreSQL role independently as well. The strongest design has both layers rejecting unauthorized writes.

Neon branch strategy for AI clients

Neon branches can separate AI-assisted work from the primary branch.

Do not assume a branch automatically removes sensitive data. A branch can contain the same records as its parent at creation time. Review data classification and access grants separately.

Troubleshooting

datamcp cannot connect to Neon

Copy a fresh connection string from the exact Neon branch, confirm the hostname, database, role, and password, and retain the SSL parameters. Test the same URI with psql from another trusted environment.

Certificate or SSL validation fails

Do not disable TLS. Start from the URI Neon provides and select an SSL mode supported by both Neon and the PostgreSQL client. For strict hostname verification, use verify-full with the appropriate system trust roots.

The pooled connection behaves differently

Neon's pooler uses PgBouncer transaction mode. Session settings and session-dependent features do not persist across transactions. Switch to the direct endpoint when the workflow requires normal PostgreSQL session behavior.

The first query is slow

The branch compute may be waking from an idle state. Retry after the compute becomes active and review the Neon scale-to-zero configuration if consistent low first-query latency is required.

Claude or Cursor connects but sees no tables

Check the dedicated role's CONNECT, schema USAGE, and table privileges. datamcp can only discover objects visible to the PostgreSQL role. Resync the connection after changing grants or migrations.

A query is denied

Inspect both permission layers. The PostgreSQL role or MCP link may be blocking the table or operation. Treat the denial as a working control and expand only the smallest necessary scope.

Cursor reports the MCP server as disconnected

Validate the JSON, remote URL, and Authorization: Bearer ... header. Confirm the datamcp API key and MCP link are active, then restart Cursor after configuration changes.

Claude cannot add the connector

Confirm the account supports custom remote connectors and, for a managed organization, that an owner has enabled or added the connector. Use the OAuth URL generated for Claude rather than the Cursor API-key configuration.

Production checklist

• Target the intended Neon project, branch, and database
• Prefer a SQL-created dedicated role over an owner-level role
• Grant only required schemas and tables
• Keep TLS enabled and verify the server where supported
• Start with the direct Neon endpoint
• Use the pooled endpoint only with its transaction-mode limits understood
• Create separate MCP links for Claude and Cursor
• Start both links read-only
• Keep the Neon password out of every AI client
• Keep real datamcp API keys out of Git
• Test schema discovery before row queries
• Confirm writes are denied
• Review activity and test revocation

Next steps

Review the hosted PostgreSQL MCP server architecture, then use the dedicated Cursor PostgreSQL integration or Claude PostgreSQL integration page for client-specific details.

Before using a primary branch, complete the MCP security checklist for production databases. datamcp provides the hosted MCP and policy layer; you still own the Neon role, branch selection, TLS configuration, data sensitivity, backups, and incident response.