Neon MCP setup: project scope, branches and read-only mode

For Neon, identifying the right project is only the first step. A project may contain several branches, and tables with the same name may exist on different branches. Before setup, record the project identifier, branch, database and a known test value. Use a development environment with unimportant data. These steps propose checks for your own connection; they do not claim an authenticated account test.

Set project scope and read mode

Neon documents https://mcp.neon.tech/mcp as its remote endpoint. The readonly=true parameter limits the available tools to read operations; projectId scopes access to one project. OAuth records the confirmed grant. If the intended scope changes, review authorization as well. Editing the URL does not automatically expand a token that has already been issued.

VS Code remote configuration

Replace YOUR_PROJECT_ID with the identifier of your test project. Add the entry to .vscode/mcp.json and start the connection. Complete authorization with the intended account and inspect the grant shown in the browser. This example uses interactive OAuth, so it needs neither a local package command nor a database password in the file. Preserve other server entries when extending an existing configuration.

{
  "servers": {
    "neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=YOUR_PROJECT_ID"
    }
  }
}

A project identifier is not a password, but still belongs in the appropriate configuration. If several accounts are signed in, check the organization actually authorized. The VS Code guide explains where to put the file; the read-only guide separates permission layers. An available read tool does not yet establish which dataset its response will describe.

Verify the project and branch against the result

1. Open the test project in Neon and record the project, branch, database and expected table. Check the test value independently of MCP.

2. After authorization, inspect the connection and available tools. Select the prepared branch and database explicitly when retrieving data.

3. Start with the table structure. Then read a few known fields with a bounded query and an appropriate filter.

4. Compare the returned value with your note. Record the branch actually used before expanding the work to another dataset.

Handle missing results and changed grants

If the expected table is missing, first inspect the branch, database and schema. Do not create a replacement table immediately: the request may simply point to another dataset. If authorization itself fails, check the account and grant before investigating SQL. The troubleshooting navigator and database planner help separate these questions and preserve a clear expected result for the next attempt.

Repeat the same small check after changing the connection. Extend the scope to more tables or reports only after that comparison succeeds. One successful read does not establish that a later migration or branch creation will work; those actions need separate checks. The Neon registry search offers other entries. The data app guides also cover MongoDB, Supabase and local file access.

Does projectId also select a branch?

No. It scopes the project. Check the branch and database separately for the actual request.

Which parameter enables read mode?

Neon documents readonly=true for read tool scope. Select the project and dataset as well.

Does changing the URL expand an OAuth token?

Not automatically. Review the confirmed grant and authorize again when the intended scope changes.

Do I need npx for this example?

No. This example uses a directly connected HTTP endpoint with OAuth.

Provider sources checked on 2 October 2026. Test procedures are editorial suggestions.

1. Neon: MCP server, scopes and URL parameters
   Show retrieval command

   curl -s https://github.com/neondatabase/mcp-server-neon
2. Neon: Connect MCP clients
   Show retrieval command

   curl -s https://neon.com/docs/ai/connect-mcp-clients-to-neon

All posts