Neon

Neon MCP 서버

Neon MCP 서버는 자연어로 Neon의 Lakebase Postgres 데이터베이스와 상호작용할 수 있게 해주는 오픈소스 도구입니다.

Model Context Protocol(MCP)은 대규모 언어 모델(LLM)과 외부 시스템 간의 컨텍스트를 관리하기 위해 설계된 표준화된 프로토콜입니다. 이 저장소는 Neon용 원격 MCP 서버를 제공합니다.

Neon의 MCP 서버는 자연어 요청과 Neon API 사이의 브리지 역할을 합니다. MCP를 기반으로 구축된 이 서버는 요청을 필요한 API 호출로 변환하여 프로젝트 및 브랜치 생성, 쿼리 실행, 데이터베이스 마이그레이션 수행 등의 작업을 원활하게 관리할 수 있게 해줍니다.

Neon MCP 서버의 주요 기능은 다음과 같습니다:

• 자연어 상호작용: 직관적이고 대화형 명령을 사용하여 Neon 데이터베이스를 관리합니다.
• 간소화된 데이터베이스 관리: SQL을 작성하거나 Neon API를 직접 사용하지 않고도 복잡한 작업을 수행합니다.
• 비개발자 접근성: 다양한 기술적 배경을 가진 사용자가 Neon 데이터베이스와 상호작용할 수 있도록 지원합니다.
• 데이터베이스 마이그레이션 지원: 자연어로 시작된 데이터베이스 스키마 변경을 위해 Neon의 브랜칭 기능을 활용합니다.

예를 들어, Claude Code 또는 모든 MCP 클라이언트에서 자연어를 사용하여 Neon에서 다음과 같은 작업을 수행할 수 있습니다:

• Let's create a new Postgres database, and call it "my-database". Let's then create a table called users with the following columns: id, name, email, and password.
• I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".
• Can you give me a summary of all of my Neon projects and what data is in each one?

[!WARNING]
Neon MCP 서버 보안 고려 사항
Neon MCP 서버는 자연어 요청을 통해 강력한 데이터베이스 관리 기능을 제공합니다. 실행 전에 LLM이 요청한 작업을 항상 검토하고 승인하세요. 권한 있는 사용자와 애플리케이션만 Neon MCP 서버에 접근할 수 있도록 하세요.

Neon MCP 서버는 로컬 개발 및 IDE 통합 전용입니다. 프로덕션 환경에서 Neon MCP 서버를 사용하는 것은 권장하지 않습니다. 우발적이거나 권한 없는 변경을 초래할 수 있는 강력한 작업을 실행할 수 있습니다.

자세한 내용은 MCP 보안 가이드 →를 참조하세요.

Neon MCP 서버 설정

Neon MCP 서버를 설정하는 몇 가지 옵션이 있습니다:

1. API 키를 이용한 빠른 설정(Cursor, VS Code, Claude Code): neon@latest init을 실행하여 단일 명령으로 Neon의 MCP 서버, 에이전트 스킬, VS Code 확장을 자동으로 구성합니다.
2. 원격 MCP 서버(OAuth 기반 인증): OAuth를 사용한 인증으로 Neon의 관리형 MCP 서버에 연결합니다. 이 방법은 API 키를 관리할 필요가 없어 더 편리합니다. 또한 릴리스된 최신 기능과 개선 사항을 자동으로 받을 수 있습니다.
3. 원격 MCP 서버(API 키 기반 인증): API 키를 사용한 인증으로 Neon의 관리형 MCP 서버에 연결합니다. 이 방법은 OAuth를 사용할 수 없는 환경에서 원격 에이전트를 Neon에 연결하려는 경우 유용합니다. 또한 릴리스된 최신 기능과 개선 사항을 자동으로 받을 수 있습니다.

사전 요구 사항

• MCP 클라이언트 애플리케이션.
• Neon 계정.
• Node.js (>= v18.0.0): nodejs.org에서 다운로드하세요.
• IP 허용이 활성화된 경우, 허용 목록에 34.192.103.46 및 23.22.233.166를 추가하세요(mcp.neon.tech 고정 IP).

개발을 위해서는 Node.js 22+가 필요합니다(pnpm은 Corepack을 통해 제공됩니다 — 활성화하려면 corepack enable을 실행하세요).

옵션 1. API 키를 이용한 빠른 설정

API 키를 수동으로 만들고 싶지 않으신가요?

neon@latest init을 실행하여 단일 명령으로 Neon의 MCP 서버를 자동으로 구성하세요:

npx neon@latest init

이 방법은 Cursor, VS Code(GitHub Copilot), Claude Code에서 작동합니다. OAuth를 통해 인증하고, Neon API 키를 생성하며, 편집기를 자동으로 구성합니다.

옵션 2. 원격 호스팅 MCP 서버(OAuth 기반 인증)

OAuth를 사용한 인증으로 Neon의 관리형 MCP 서버에 연결합니다. 이것은 가장 쉬운 설정이며, 이 서버의 로컬 설치가 필요 없고 클라이언트에 Neon API 키를 구성할 필요도 없습니다.

다음 명령을 실행하여 작업 공간의 모든 감지된 에이전트와 편집기에 Neon MCP 서버를 추가하세요:

npx add-mcp https://mcp.neon.tech/mcp

-g 플래그를 추가하면 프로젝트 범위 대신 전역 MCP 서버 목록에 Neon MCP 서버가 추가됩니다.

또는 클라이언트의 MCP 서버 구성 파일(예: mcp.json, mcp_config.json)에 다음 "Neon" 항목을 추가할 수 있습니다:

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Kiro: Kiro MCP 구성 파일(~/.kiro/settings/mcp.json은 전역, .kiro/settings/mcp.json은 프로젝트 범위)에 다음을 추가하세요:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

또는 이 README 상단의 원클릭 설치 버튼을 사용하세요. 자세한 내용은 Kiro MCP 문서를 참조하세요.

• MCP 클라이언트를 다시 시작하거나 새로고침하세요.
• 브라우저에서 OAuth 창이 열립니다. 프롬프트에 따라 MCP 클라이언트가 Neon 계정에 접근하도록 승인하세요.

OAuth 기반 인증을 사용하면 MCP 서버는 기본적으로 개인 Neon 계정의 프로젝트에서 작동합니다. 조직에 속한 프로젝트에 접근하거나 관리하려면 MCP 클라이언트에 대한 프롬프트에서 org_id 또는 project_id를 명시적으로 제공해야 합니다.

옵션 3. 원격 호스팅 MCP 서버(API 키 기반 인증)

원격 MCP 서버는 클라이언트가 지원하는 경우 Authorization 헤더의 API 키를 사용한 인증도 지원합니다.

Neon 콘솔에서 Neon API 키를 생성하세요. 그런 다음 다음 명령을 실행하여 작업 공간의 모든 감지된 에이전트와 편집기에 Neon MCP 서버를 추가하세요:

npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer <$NEON_API_KEY>"

또는 클라이언트의 MCP 서버 구성 파일(예: mcp.json, mcp_config.json)에 다음 "Neon" 항목을 추가할 수 있습니다:

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

조직의 API 키를 제공하면 조직 아래의 프로젝트에만 접근이 제한됩니다.

범위(Scopes) 및 읽기 전용 모드

Neon MCP는 OAuth 범위 read, write, *를 지원합니다(*은 둘 다를 의미). MCP 클라이언트는 이러한 범위를 직접 요청하거나 OAuth 권한 UI에서 선택할 수 있습니다.

읽기 전용 모드는 사용 가능한 도구를 제한하여 프로젝트 생성, 브랜치 생성, 마이그레이션 실행과 같은 쓰기 작업을 비활성화합니다. 읽기 전용 도구에는 프로젝트 나열, 스키마 설명, 데이터 쿼리, 성능 메트릭 보기가 포함됩니다.

읽기 전용 모드는 두 가지 방법으로 설정할 수 있습니다:

1. OAuth 범위 선택(권장): OAuth에서 승인 UI의 전체 액세스 체크를 해제하여 읽기 전용을 선택합니다.
2. readonly 쿼리 매개변수: MCP 서버 URL에 ?readonly=true을 추가하세요:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true"
    }
  }
}

쿼리 매개변수의 작동 방식:

• API 키 플로우: readonly=true이 읽기 전용 모드를 활성화하는 방법입니다(이 플로우에는 OAuth 범위 교환이 없습니다).
• OAuth 플로우: readonly=true이 OAuth 범위를 재정의합니다. 이 매개변수가 없으면 읽기 전용 여부는 OAuth 동의 UI에서 선택한 범위에 따라 결정됩니다.

레거시 HTTP 헤더 x-read-only도 폴백으로 지원됩니다(쿼리 매개변수보다 낮은 우선순위).

참고: 읽기 전용 모드는 사용 가능한 _도구_를 제한합니다. 또한 run_sql 도구는 읽기 전용 쿼리에 대해서만 계속 사용할 수 있습니다.

접근 제어를 위한 URL 쿼리 매개변수

권한 컨텍스트(범위 카테고리, 프로젝트 범위 지정, 읽기 전용 모드)는 MCP 서버 URL의 쿼리 매개변수를 통해 구성됩니다. 구성은 모든 요청과 함께 전송되며 재인증 없이 즉시 적용됩니다.

매개변수	설명	예시
readonly	읽기 전용 모드 활성화(true/false)	?readonly=true
category	특정 도구 카테고리로 제한(반복 또는 CSV)	?category=querying&category=schema
projectId	모든 작업을 단일 프로젝트로 범위 지정	?projectId=proj-123

읽기 전용 + 프로젝트 범위 지정 예시:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=my-project-id"
    }
  }
}

카테고리 필터 예시(쿼리 및 스키마 도구만):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?category=querying&category=schema"
    }
  }
}

/api/list-tools 엔드포인트를 사용하여 모든 구성에서 볼 수 있는 도구를 미리 볼 수 있습니다(인증 불필요):

curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

읽기 전용 모드에서 사용 가능한 도구

• list_projects, list_shared_projects, describe_project, list_organizations
• describe_branch, list_branch_computes, compare_database_schema
• run_sql, run_sql_transaction, get_database_tables, describe_table_schema
• list_slow_queries, explain_sql_statement
• get_connection_string
• get_neon_auth_config
• query_logs, list_log_fields, list_log_field_values
• search, fetch, list_docs_resources, get_doc_resource

쓰기 접근이 필요한 도구:

• create_project, delete_project
• create_branch, delete_branch, reset_from_parent
• provision_neon_auth, configure_neon_auth, provision_neon_data_api
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

SSE(Server-Sent Events) 전송(더 이상 사용되지 않음)

MCP는 두 가지 원격 서버 전송을 지원합니다: 더 이상 사용되지 않는 SSE(Server-Sent Events)와 더 새롭고 권장되는 Streamable HTTP입니다. LLM 클라이언트가 아직 Streamable HTTP를 지원하지 않는 경우, 엔드포인트를 https://mcp.neon.tech/mcp에서 https://mcp.neon.tech/sse으로 전환하여 SSE를 사용할 수 있습니다.

다음 명령을 실행하여 SSE 전송을 사용하여 작업 공간의 모든 감지된 에이전트와 편집기에 Neon MCP 서버를 추가하세요:

npx add-mcp https://mcp.neon.tech/sse --type sse

원격 서버 아키텍처

원격 서버는 mcp.neon.tech의 Vercel에서 Next.js App Router 애플리케이션으로 실행됩니다.

[!NOTE] 루트 / 경로는 Neon MCP 서버 문서로 리디렉션됩니다. 랜딩 페이지는 없습니다.

핵심 구현 영역:

• app/api/[transport]/route.ts: Streamable HTTP(/mcp) 및 SSE(/sse)용 MCP 전송 엔드포인트
• app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: OAuth 플로우 엔드포인트
• app/.well-known/: OAuth 검색 메타데이터 엔드포인트
• mcp/: MCP 서버, 도구, 핸들러, 분석, Sentry 통합
• lib/: Next.js 호환 헬퍼(OAuth, 구성, 오류 처리)
• mcp/utils/read-only.ts: 읽기 전용 모드 및 범위 처리

가이드

• Neon MCP 서버 가이드
• MCP 클라이언트를 Neon에 연결
• Neon MCP 서버와 함께 사용하는 Cursor
• Neon MCP 서버와 함께 사용하는 Claude Code
• Neon MCP 서버와 함께 사용하는 Claude Desktop
• Neon MCP 서버와 함께 사용하는 Cline
• Neon MCP 서버와 함께 사용하는 Windsurf
• Neon MCP 서버와 함께 사용하는 Zed

기능

지원되는 도구

Neon MCP 서버는 MCP 클라이언트에 "도구"로 노출되는 다음 작업을 제공합니다. 이러한 도구를 사용하여 자연어 명령으로 Neon 프로젝트와 데이터베이스와 상호작용할 수 있습니다.

도구 범위 메타데이터

각 도구 정의에는 허가 기반 도구 필터링 및 동의 UX에 사용되는 scope 카테고리가 포함됩니다. 현재 카테고리는 다음과 같습니다:

• projects
• branches
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• null (범위 카테고리가 없는 도구)

참고:

• compare_database_schema는 schema로 분류됩니다.
• provision_neon_data_api은 data_api로 분류됩니다(neon_auth와는 구분됨).
• 읽기 전용 강제는 여전히 readOnlySafe 및 서버 측 읽기 전용 로직에 의존합니다. scope은 카테고리 메타데이터일 뿐이며, 독립적인 읽기/쓰기 스위치가 아닙니다.
• 프로젝트 범위 모드(?projectId=...)에서는 search 및 fetch을 사용할 수 없습니다.

프로젝트 관리:

• list_projects: 계정의 처음 10개 Neon 프로젝트를 나열하고 각 프로젝트에 대한 요약을 제공합니다. 특정 프로젝트를 찾을 수 없는 경우 limit 매개변수에 더 높은 값을 전달하여 제한을 늘리세요.
• list_shared_projects: 현재 사용자와 공유된 Neon 프로젝트를 나열합니다. 검색 매개변수와 반환할 프로젝트 수 제한(기본값: 10)을 지원합니다.
• describe_project: 특정 Neon 프로젝트에 대한 자세한 정보(프로젝트 ID, 이름, 연결된 브랜치 및 데이터베이스 포함)를 가져옵니다.
• create_project: Neon 계정에 새 Neon 프로젝트를 생성합니다. 프로젝트는 브랜치, 데이터베이스, 역할 및 컴퓨트의 컨테이너 역할을 합니다.
• delete_project: 기존 Neon 프로젝트와 연결된 모든 리소스를 삭제합니다.
• list_organizations: 현재 사용자가 액세스할 수 있는 모든 조직을 나열합니다. 검색 매개변수를 사용하여 조직 이름 또는 ID로 선택적으로 필터링할 수 있습니다.

브랜치 관리:

• create_branch: 지정된 Neon 프로젝트 내에 새 브랜치를 생성합니다. 개발, 테스트 또는 마이그레이션을 위해 Neon의 브랜칭 기능을 활용합니다.
• delete_branch: Neon 프로젝트에서 기존 브랜치를 삭제합니다.
• describe_branch: 특정 브랜치의 이름, ID, 부모 브랜치와 같은 세부 정보를 검색합니다.
• list_branch_computes: 프로젝트 또는 특정 브랜치의 컴퓨트 엔드포인트를 나열합니다. 컴퓨트 ID, 유형, 크기, 마지막 활성 시간 및 자동 확장 정보를 포함합니다.
• compare_database_schema: 하위 브랜치와 부모 브랜치 간의 스키마 차이를 표시합니다.
• reset_from_parent: 현재 브랜치를 부모의 상태로 재설정하고 로컬 변경 사항을 버립니다. 브랜치에 하위 브랜치가 있는 경우 자동으로 백업을 보존하며, 선택적으로 사용자 지정 이름으로 백업 보존을 요청할 수도 있습니다.

SQL 쿼리 실행:

• get_connection_string: 데이터베이스 연결 문자열을 반환합니다.
• run_sql: 지정된 Neon 데이터베이스에 대해 단일 SQL 쿼리를 실행합니다. 읽기 및 쓰기 작업을 모두 지원합니다.
• run_sql_transaction: Neon 데이터베이스에 대해 단일 트랜잭션 내에서 일련의 SQL 쿼리를 실행합니다.
• get_database_tables: 지정된 Neon 데이터베이스 내의 모든 테이블을 나열합니다.
• describe_table_schema: 특정 테이블의 스키마 정의를 검색하여 열, 데이터 유형 및 제약 조건을 자세히 설명합니다.

데이터베이스 마이그레이션(스키마 변경):

• prepare_database_migration: 데이터베이스 마이그레이션 프로세스를 시작합니다. 중요하게도, 메인 브랜치에 영향을 주기 전에 임시 브랜치를 생성하여 마이그레이션을 안전하게 적용하고 테스트합니다.
• complete_database_migration: 준비된 데이터베이스 마이그레이션을 메인 브랜치에 최종 적용합니다. 이 작업은 임시 마이그레이션 브랜치의 변경 사항을 병합하고 임시 리소스를 정리합니다.

SQL 쿼리 및 최적화:

• list_slow_queries: 데이터베이스에서 가장 느린 쿼리를 찾아 성능 병목 현상을 식별합니다. pg_stat_statements 확장이 필요합니다.
• explain_sql_statement: SQL 쿼리에 대한 자세한 실행 계획을 제공하여 성능 병목 현상을 식별하는 데 도움을 줍니다.
• prepare_query_tuning: 쿼리 성능을 분석하고 인덱스 생성과 같은 최적화를 제안합니다. 이러한 최적화를 안전하게 테스트하기 위해 임시 브랜치를 생성합니다.
• complete_query_tuning: 메인 브랜치에 최적화를 적용하거나 폐기하여 쿼리 튜닝을 마무리합니다. 임시 튜닝 브랜치를 정리합니다.

Neon Auth:

• provision_neon_auth: Neon 프로젝트에 Neon Auth를 프로비저닝합니다. 개발자가 인증 공급자와의 통합을 생성하여 인증 인프라를 쉽게 설정할 수 있게 합니다.
• configure_neon_auth: 브랜치에 대한 기존 Neon Auth 통합을 구성합니다 — 신뢰할 수 있는 출처, localhost 액세스, 인증 방법, OAuth 공급자 및 트랜잭션 이메일 공급자를 관리합니다.
• get_neon_auth_config: 브랜치에 대한 전체 Neon Auth 구성을 읽습니다. 통합 메타데이터와 구성 가능한 설정을 포함합니다(비밀은 마스킹됨).

Neon Data API:

• provision_neon_data_api: HTTP 기반 데이터베이스 액세스를 위한 Neon Data API를 프로비저닝합니다. Neon Auth 또는 외부 JWKS 공급자를 통한 선택적 JWT 인증을 지원합니다.

검색 및 탐색:

• search: 쿼리와 일치하는 조직, 프로젝트 및 브랜치를 검색합니다. ID, 제목 및 Neon 콘솔에 대한 직접 링크를 반환합니다.
• fetch: ID(일반적으로 검색 도구에서 가져옴)를 사용하여 특정 조직, 프로젝트 또는 브랜치에 대한 자세한 정보를 가져옵니다.

관찰 가능성:

• query_logs: 구조화된 필터(소스, 서비스 이름, 심각도, 시간 범위)를 사용하여 Neon 서버리스 함수 및 기타 서비스에서 내보낸 로그를 쿼리합니다. 로그는 OpenTelemetry 기반입니다.
• list_log_fields: 브랜치에 대해 필터링할 수 있는 로그 필드(라벨)를 나열합니다(예: service_name, severity_text, scope_name). query_logs 전에 사용하세요.
• list_log_field_values: 브랜치 및 시간 범위 내에서 로그 필드의 고유 값을 나열하여 query_logs에 전달할 구체적인 값을 찾습니다.

문서 및 리소스:

• list_docs_resources: https://neon.com/docs/llms.txt에서 인덱스를 가져와 사용 가능한 모든 Neon 문서 페이지를 나열합니다. get_doc_resource 도구를 사용하여 개별적으로 가져올 수 있는 페이지 URL과 제목을 반환합니다.
• get_doc_resource: 특정 Neon 문서 페이지를 마크다운 콘텐츠로 가져옵니다. 먼저 list_docs_resources 도구를 사용하여 사용 가능한 페이지 슬러그를 찾은 다음 이 도구에 슬러그를 전달하세요.

마이그레이션

마이그레이션은 시간이 지남에 따라 데이터베이스 스키마의 변경 사항을 관리하는 방법입니다. Neon MCP 서버를 통해 LLM은 별도의 "시작"(prepare_database_migration) 및 "커밋"(complete_database_migration) 명령으로 마이그레이션을 안전하게 수행할 수 있습니다.

"시작" 명령은 마이그레이션을 수락하고 새 임시 브랜치에서 실행합니다. 반환 시 이 명령은 LLM에게 이 브랜치에서 마이그레이션을 테스트해야 한다고 힌트를 줍니다. 그런 다음 LLM은 "커밋" 명령을 실행하여 마이그레이션을 원래 브랜치에 적용할 수 있습니다.

개발

이 프로젝트는 Corepack을 통해 고정된 패키지 관리자로 pnpm을 사용합니다.

프로젝트 구조

MCP 서버 코드는 리포지토리 루트에 있으며, mcp.neon.tech에 Vercel로 배포되는 Next.js 애플리케이션입니다.

corepack enable
pnpm install

로컬 개발

# Start the Next.js dev server (for the remote MCP server)
pnpm dev

린트 및 타입 검사

pnpm lint
pnpm typecheck

환경 변수

원격 서버 런타임에 필요:

변수	설명
SERVER_HOST	서버 URL(기본값: VERCEL_URL)
UPSTREAM_OAUTH_HOST	Neon OAuth 공급자 URL
CLIENT_ID	OAuth 클라이언트 ID
CLIENT_SECRET	OAuth 클라이언트 시크릿
COOKIE_SECRET	서명된 쿠키용 시크릿
KV_URL	Vercel KV(Upstash Redis) URL
OAUTH_DATABASE_URL	토큰 저장용 Postgres URL

선택 사항:

변수	설명
LOG_LEVEL	Winston 로그 수준: error, warn, info(기본값), debug, verbose, silly

테스트 피라미드

모든 테스트는 리포지토리 루트에서 실행됩니다.

# Unit tests
pnpm test:unit

# Integration tests
pnpm test:integration

# MCP protocol end-to-end tests (real MCP client/server tool calls)
pnpm test:e2e:mcp

# Website end-to-end tests (Playwright; provisions/validates ephemeral DB first)
pnpm test:e2e:web

# Full end-to-end suite
pnpm test:e2e

# Full test pyramid (unit + integration + e2e; used in CI)
pnpm test

테스트 전략:

• 전송/프로토콜 및 사용자에게 보이는 동작에는 E2E를 선호합니다.
• 결정적인 도구 계약 및 워크플로 동작에는 통합 테스트를 사용합니다.
• 순수 로직 및 엣지 케이스에는 단위 테스트를 사용합니다.
• 병합 게이트 테스트에서 타사 가용성에 의존하지 마세요. 통합/단위 계층에서 외부 종속성을 목킹하세요.

배포

Vercel은 리포지토리 브랜치 구성에서 원격 서버를 자동으로 배포합니다. 풀 리퀘스트에는 미리보기 환경이 제공됩니다.