Neon MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

즉각적인 Copy-On-Write 분기 — 마이그레이션 테스트에 적합
프로젝트, 지점, 역할 및 데이터베이스 관리
모든 분기에서 SQL 실행(읽기 또는 쓰기)
모든 지점에 대한 연결 문자열 검색
기본: Neon에서 구축 및 유지 관리

라이브 데모

실제 사용 모습

neon.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "neon",
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "neon": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@neondatabase/mcp-server-neon"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add neon -- npx -y @neondatabase/mcp-server-neon

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Neon

쓰기 중 복사 분기에서 파괴적인 Postgres 마이그레이션 테스트

👤 실제 데이터 DB에 대해 스키마 변경을 실행하는 엔지니어 ⏱ ~20 min intermediate

언제 쓸까: 마이그레이션(DROP COLUMN, 대규모 업데이트, 인덱스 재구축)이 있고 프로덕션 위험 없이 프로덕션 형태의 데이터에서 이를 실행하려고 합니다.

사전 조건

네온 API 키 — console.neon.tech → 계정 → API 키

흐름

메인에서 브랜치 생성

Neon 프로젝트 <id>의 메인 브랜치에서 'test-drop-legacy'라는 브랜치를 생성합니다. 새 분기에 대한 연결 문자열을 반환합니다.✓ 복사됨

→ 2초 이내에 분기가 생성되고 conn 문자열이 반환됨
브랜치에 마이그레이션 적용

새 분기에 연결하고 <paste migration SQL>을 실행합니다. 행 수 및 오류를 보고합니다.✓ 복사됨

→ 마이그레이션이 완료되었습니다. 카운트가 의미가 있다
확인 후 정리

변경된 테이블에 대해 온전성 쿼리를 실행합니다. 결과가 정확해 보이면 알려주시면 메인에 지원하겠습니다. 그런 다음 어느 쪽이든 지점을 삭제하십시오.✓ 복사됨

→ 스토리지 비용을 피하기 위해 검증 + 분기 삭제

결과: 프로덕션 위험 없이 마이그레이션이 실제 데이터에서 작동한다는 확신을 가지세요.

함정

Branch는 쓰기량에 비례하여 스토리지를 소비합니다. — 테스트 후 즉시 브랜치를 삭제합니다. 쓰기가 많은 버려진 브랜치로 인해 비용이 많이 듭니다.
Branch is a snapshot — doesn't see writes that happen on main after branch creation — Branch close to apply time; or use Neon time-travel to branch from a specific timestamp

함께 쓰기: github · postgres

Spin up a per-PR ephemeral database for integration tests

👤 Teams running CI integration tests against real Postgres ⏱ ~15 min intermediate

언제 쓸까: Each PR needs its own isolated DB; SQLite mocks aren't enough.

흐름

Create a branch named after the PR

Create a Neon branch in project <id> named 'pr-482' from main. Return the connection string.✓ 복사됨

→ Branch ready, conn string returned
Run the test suite against it

Set DATABASE_URL to that conn string. Run npm run test:integration and report results.✓ 복사됨

→ Tests run, pass/fail summary
Tear down

Delete branch 'pr-482'.✓ 복사됨

→ Branch removed

결과: Real-DB integration tests with seconds-to-spin-up isolation, no shared-state contamination.

함정

Branch limits per project on lower plans — Free tier limits matter; either upgrade or implement a max-N-branches sweeper

함께 쓰기: github

Give Claude safe read-only access to a production Neon DB

👤 Engineers debugging prod data without giving the model write power ⏱ ~10 min beginner

언제 쓸까: You want to investigate a prod issue but you're nervous about a misfired UPDATE.

흐름

Create a read-only role

In Neon project <id>, create a role 'claude_readonly' with SELECT-only access on schema public. Return its connection string.✓ 복사됨

→ Role created; conn string returned
Connect via Postgres MCP

Use that conn string with the Postgres MCP. Confirm I can run SELECT but not INSERT.✓ 복사됨

→ SELECT works, INSERT errors with 'permission denied'
Investigate the issue

Now query the orders table for the affected user_id 99214. What's the row state and is anything unusual?✓ 복사됨

→ Concrete diagnosis from real data

결과: A productive prod debug session with provable read-only safety.

함정

Forgetting to scope future tables — new tables aren't covered — Use ALTER DEFAULT PRIVILEGES to ensure new tables grant SELECT to claude_readonly automatically

함께 쓰기: postgres

Review schema evolution across branches before merging

👤 DBAs and platform engineers ⏱ ~25 min advanced

언제 쓸까: Multiple feature branches each have their own schema changes; you want to see the cumulative diff.

흐름

List branches and their states

List all Neon branches for project <id>. For each, give me a one-line description of how its schema differs from main.✓ 복사됨

→ Per-branch schema delta summary
Compare two branches in detail

For branch 'feature-payments' vs main: diff the tables, columns, indexes, and constraints. Format as a SQL migration.✓ 복사됨

→ Reviewable SQL diff
Identify conflicts

If both feature-payments and feature-auth get merged, do their schema changes conflict? Where?✓ 복사됨

→ Specific conflict list, not 'no obvious issues'

결과: Merge order plus conflicts known before they hit main.

함정

Diff misses changes inside materialized views or stored procs — Be explicit — ask Claude to also diff pg_proc and view definitions, not just tables

함께 쓰기: github

조합

다른 MCP와 조합해 10배 효율

neon + github

Per-PR ephemeral DB for CI tests, with PR comments showing connection info

When PR #482 opens, create a Neon branch 'pr-482', run migrations + seeds against it, post the conn string as a private comment on the PR.✓ 복사됨

neon + postgres

Use Postgres MCP for safer read-only querying once Neon spins up the branch

Create a Neon branch with read-only role 'claude_ro'. Then use Postgres MCP with that conn string to investigate the user-99214 issue.✓ 복사됨

neon + filesystem

Apply local SQL migration files to a Neon branch in order

Read every .sql file under /db/migrations/ in name order. Apply them in sequence to Neon branch 'staging'.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
list_projects	none	See your Neon projects	free
describe_project	project_id	Get an overview of a project	free
create_branch	project_id, name?, parent_id?, parent_lsn? or parent_timestamp?	Fork a branch for testing or per-PR DBs	branch storage billed by writes
list_branches	project_id	Inventory branches	free
delete_branch	project_id, branch_id	Clean up after testing — important to control storage cost	free
get_connection_string	project_id, branch_id?, role_name?, database_name?	Get a conn string scoped to a branch/role/db	free
run_sql	project_id, branch_id?, sql: str	Execute SQL against any branch	compute time billed
describe_table_schema	project_id, branch_id?, table_name	Inspect a table without writing the SQL yourself	free
create_role / drop_role	project_id, role_name	Manage roles for scoped access	free
create_database / list_databases	project_id, name	Multi-DB-per-project setups	free

비용 및 제한

운영 비용

API 쿼터: Standard Neon API limits per plan
호출당 토큰: Most ops are small; SQL results scale with row count — always LIMIT exploratory queries
금액: MCP free; Neon Free tier covers small projects, paid plans bill compute-hours and storage
팁: Branches are nearly free until they accumulate writes. The #1 cost surprise is forgotten branches — set a sweep policy or always delete after use.

보안

권한, 시크릿, 파급범위

최소 스코프: scope API key to a single project when possible

자격 증명 저장: API key in env var NEON_API_KEY

데이터 외부 송신: Calls to console.neon.tech API; SQL traffic to your project's regional endpoint

절대 부여 금지: org-wide admin keys to long-running agents

run_sql can mutate. For prod main branch, prefer creating a read-only role and connecting via Postgres MCP instead.
Branches inherit data from parent at creation time — they contain whatever PII the parent contains. Treat them as sensitive.

문제 해결

자주 발생하는 오류와 해결

401 Unauthorized

API key invalid or revoked. Generate new at console.neon.tech → Account → API keys.

확인: curl -H 'Authorization: Bearer $NEON_API_KEY' https://console.neon.tech/api/v2/projects

Branch creation fails: 'limit reached'

You've hit your plan's branch limit. Delete unused branches or upgrade.

run_sql times out on a long migration

Long-running statements may exceed default timeout. Use psql with the connection string for very long ops, or split the migration.

Connection string works once then fails (compute paused)

Neon free-tier compute auto-suspends. First connection wakes it (cold start ~1s); subsequent connections are fine. Don't treat first-call latency as failure.

대안

Neon 다른 것과 비교

대안	언제 쓰나	단점/장점
Supabase MCP	You want auth, edge functions, storage in addition to Postgres	Heavier surface; branching gated to Pro plan
Postgres MCP	You only need read-only SQL access and don't use branching	No branch/project management
AWS RDS via aws MCP	You're on AWS-managed Postgres (RDS/Aurora)	No branching; provisioning is heavier and slower

Neon