Neon

공식

Neon 서버리스 Postgres 플랫폼과 상호작용합니다.

Neon MCP(으)로 무엇을 할 수 있나요?

프로젝트 생성 및 관리 — 새 Postgres 데이터베이스를 만들고, 기존 프로젝트를 나열하거나, create_project 또는 list_projects를 통해 삭제하도록 요청합니다.
SQL 쿼리 및 트랜잭션 실행 — run_sql 또는 run_sql_transaction을 사용하여 쓰기를 포함한 단일 또는 다중 문 SQL을 데이터베이스에 대해 실행합니다.
성능 검사 및 최적화 — list_slow_queries, explain_sql_statement 또는 inspect_database를 통해 느린 쿼리를 식별하고, 실행 계획을 얻거나 캐시 적중률과 같은 진단을 실행합니다.
스키마 안전 마이그레이션 — 임시 브랜치에서 마이그레이션을 시작하고, 테스트한 후 prepare_database_migration 및 complete_database_migration으로 메인 브랜치에 커밋합니다.
데이터베이스 구조 탐색 — get_database_tables, describe_table_schema 또는 compare_database_schema를 사용하여 테이블을 나열하고, 열 스키마를 설명하거나 브랜치 간 스키마를 비교합니다.

호스팅형 MCP 서버

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

Claude Code, Codex, Cursor 등에 설치됩니다

문서

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 서버를 설정하는 몇 가지 옵션이 있습니다:

API 키를 사용한 빠른 설정(Cursor, VS Code 및 Claude Code): neon@latest init을 실행하여 단일 명령으로 Neon의 MCP 서버, 에이전트 스킬 및 VS Code 확장을 자동으로 구성합니다.
원격 MCP 서버(OAuth 기반 인증): OAuth를 사용하여 인증을 위해 Neon의 관리형 MCP 서버에 연결합니다. 이 방법은 API 키를 관리할 필요가 없어 더 편리합니다. 또한 릴리스되는 즉시 최신 기능과 개선 사항을 자동으로 받을 수 있습니다.
원격 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?category=projects&category=branches&category=endpoints&category=querying&category=schema"

해당 URL은 프로젝트, 브랜치, 컴퓨팅 엔드포인트, 쿼리 및 스키마를 게시합니다. /api/list-tools?category=projects&category=branches&category=endpoints&category=querying&category=schema으로 미리 보세요. 필터링되지 않은 URL은 모든 카테고리를 게시합니다:

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?category=projects&category=branches&category=endpoints&category=querying&category=schema"
    }
  }
}

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

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

또는 이 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?category=projects&category=branches&category=endpoints&category=querying&category=schema" --header "Authorization: Bearer <$NEON_API_KEY>"

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

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

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

범위 및 읽기 전용 모드

Neon MCP는 OAuth 범위 read 및 write을 광고합니다. MCP 클라이언트가 이를 요청하거나 OAuth 권한 UI에서 선택할 수 있습니다. 클라이언트가 여전히 *을 보내는 경우 쓰기로 처리됩니다.

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

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

기본 MCP URL(편집 가능한 동의): https://mcp.neon.tech/mcp으로 연결하고 권한 부여 페이지에서 쓰기 허용을 선택 해제하세요. 또한 해당 페이지에서 하나의 프로젝트와 도구 카테고리의 하위 집합을 선택할 수 있습니다.
매개변수화된 MCP URL(고정 동의): MCP 서버 URL에 readonly, projectId 및/또는 category을 넣으세요. 권한 부여 페이지는 해당 권한을 확인하고 편집기를 제공하지 않습니다. 권한을 변경하려면 URL을 변경하고 다시 승인하세요.

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

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

API 키 흐름: readonly=true은 읽기 전용 모드를 활성화하는 방법입니다(이 흐름에는 OAuth 범위 교환이 없습니다). URL 변경은 다음 요청에 적용됩니다.
OAuth 흐름: MCP URL의 projectId, category 및 readonly은 승인 시 확인된 고정 권한입니다. readonly=true은 해당 페이지에서 쓰기로 확장할 수 없습니다. 토큰이 발급된 후 URL을 변경해도 해당 토큰이 확장되지 않습니다. 다시 승인하세요.

OAuth 등록의 경우 x-read-only은 편집 가능한 동의에 대한 초기 쓰기 허용 기본값입니다. 확인을 잠그지 않으며 readonly=false을 포함하는 매개변수화된 URL을 축소하지 않습니다. API 키 요청은 readonly 쿼리 매개변수 아래에서 요청별로 x-read-only을 계속 준수합니다.

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

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

권한 컨텍스트(범위 카테고리, 프로젝트 범위 지정, 읽기 전용 모드)는 MCP 서버 URL의 URL 쿼리 매개변수를 통해 구성됩니다. API 키 요청은 각 요청에 해당 매개변수를 적용합니다. OAuth 토큰은 승인 시 확인되거나 편집된 권한을 저장합니다.

매개변수	설명	예시
`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_organizations, describe_branch, run_sql, run_sql_transaction, get_database_tables, describe_table_schema, list_slow_queries, explain_sql_statement, inspect_database, get_neon_auth_config, search, fetch, list_docs_resources, get_doc_resource.

비밀을 반환하지 않는 GET 방식의 생성된 관리 API 도구와 query_logs(POST, 읽기 전용). 정확한 집합은 /api/list-tools?readonly=true으로 미리 보세요.

쓰기 접근이 필요한 도구:

생성된 관리 API 쓰기(create_project, create_branch, delete_project, …)
get_connection_string(연결 문자열에 권한 있는 역할 비밀번호가 포함되어 있으므로 읽기 전용 모드에서는 제공되지 않습니다. 대신 Neon 콘솔에서 복사하세요)
prepare_database_migration, complete_database_migration
prepare_query_tuning, complete_query_tuning

서버 전송 이벤트(SSE) 전송(더 이상 사용되지 않음)

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 프로젝트 및 데이터베이스와 상호 작용할 수 있습니다.

도구 범위 메타데이터

각 도구 정의에는 권한 기반 도구 필터링 및 동의 UX에 사용되는 scope 범주가 포함됩니다. 현재 범주는 다음과 같습니다:

projects
branches
endpoints
snapshots
schema
querying
neon_auth
data_api
observability
docs
functions
storage
null (범주가 없는 도구)

참고:

관리 API 도구는 @neon/tools에서 제공됩니다. 선택자는 SDK 경로(projects.list)이며, 게시된 MCP 이름은 동사 우선입니다(list_projects, delete_project, query_logs). 기존 이름은 이미 존재하는 위치에 유지됩니다(describe_project, create_branch, reset_from_parent, compare_database_schema, provision_neon_auth, provision_neon_data_api, list_branch_computes).
?category=branches에는 브랜치, 역할 및 데이터베이스 도구가 포함됩니다(list_postgres_roles, create_postgres_database, …). branches에 대해 이미 발급된 토큰은 해당 쓰기 권한을 얻습니다. 컴퓨팅 목록은 ?category=endpoints입니다. 스냅샷 복원은 ?category=snapshots입니다.
프로젝트 멤버 및 권한 쓰기는 게시되지 않습니다. list_project_members 및 list_project_permissions는 읽기 전용입니다.
스키마 도구(?category=schema)는 호스트 도구 get_database_tables 및 describe_table_schema와 생성된 compare_database_schema입니다.
읽기 전용 적용은 여전히 readOnlySafe 및 서버 측 읽기 전용 로직에 의존합니다. scope은 범주 메타데이터이며 독립적인 읽기/쓰기 스위치가 아닙니다.
프로젝트 범위 모드(?projectId=...)에서는 프로젝트 경로가 없는 도구(list_projects, create_project, list_organizations, list_regions, search, fetch, …)가 숨겨집니다. delete_project도 숨겨집니다.

프로젝트 관리:

list_projects: Neon 프로젝트를 나열합니다. limit은 반환되는 항목 수를 제한합니다.
describe_project: ID로 Neon 프로젝트를 가져옵니다({ "project_id": "…" }).
create_project: Neon 프로젝트를 생성하고 기본 컴퓨팅이 준비될 때까지 기다립니다. 연결 문자열은 반환하지 않습니다. 인수는 { "name": "…", "org_id": "…", "region_id": "…" }입니다. 성공 후 get_connection_string을 호출하세요.
delete_project: 기존 Neon 프로젝트를 삭제합니다. 인수는 { "project_id": "…" }입니다.
list_organizations: 현재 사용자가 액세스할 수 있는 모든 조직을 나열합니다. 선택적으로 검색 매개변수를 사용하여 조직 이름 또는 ID로 필터링할 수 있습니다.

브랜치 관리:

list_branches: 프로젝트의 브랜치를 나열합니다. 브랜치 이름을 br-… ID로 확인하는 데 사용합니다.
list_credentials, create_credential, revoke_credential, rotate_credential: 객체 스토리지 및 AI 게이트웨이에 대한 브랜치 범위 자격 증명입니다. reveal은 도구가 아닙니다. 회전은 비밀을 제자리에서 교체하며 멱등적이지 않습니다.
create_branch: 읽기-쓰기 컴퓨팅으로 브랜치를 생성하고 준비될 때까지 기다립니다. 연결 문자열은 반환하지 않습니다. 인수는 { "project_id": "…", "name": "feature-x" }입니다. 엔드포인트를 건너뛰려면 no_compute: true을 전달하세요. 성공 후 get_connection_string을 호출하세요.
reset_from_parent: 브랜치를 상위 브랜치의 현재 HEAD로 재설정합니다({ "project_id": "…", "branch_id": "br-…" }). 브랜치가 분기된 이후의 쓰기를 버립니다. 브랜치에 하위 브랜치가 있는 경우 preserve_under_name이 필요합니다. 해당 하위 브랜치는 새 브랜치로 이동합니다. 상위 HEAD만 해당됩니다. 특정 시점 복원은 restore_snapshot입니다.
delete_branch: 브랜치를 삭제합니다({ "project_id": "…", "branch_id": "br-…" }).
describe_branch: 브랜치의 데이터베이스, 스키마, 테이블, 뷰 및 함수 트리를 검색합니다.
생성된 브랜치 도구는 이름이 아닌 브랜치 ID(br-...)로 branch_id을 사용합니다.
restore_snapshot: 스냅샷을 복원합니다. 기존 브랜치에 복원하려면 target_branch_id을 전달하고, 새 브랜치를 만들려면 생략하세요.

컴퓨팅 엔드포인트 (?category=endpoints):

list_postgres_endpoints, list_branch_computes, get_postgres_endpoint, create_postgres_endpoint, update_postgres_endpoint, delete_postgres_endpoint, start_postgres_endpoint, suspend_postgres_endpoint, restart_postgres_endpoint

스냅샷 (?category=snapshots):

list_snapshots, get_snapshot_schedule, set_snapshot_schedule, create_snapshot, update_snapshot, delete_snapshot, restore_snapshot

스키마 (?category=schema):

get_database_tables, describe_table_schema
compare_database_schema: 한 데이터베이스를 다른 브랜치와 비교하는 SQL 스키마 차이입니다. database_name이 필요합니다. base_branch_id을 생략하면 상위 브랜치와 비교합니다. 선택적 lsn, timestamp, base_lsn, base_timestamp은 특정 시점 전용입니다.

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 쿼리 및 최적화:

inspect_database: 브랜치에 대해 15개의 사전 정의된 읽기 전용 Postgres 진단 중 하나를 실행합니다 — 관계 및 인덱스 크기, 인덱스 및 순차 스캔 사용량, 활성 쿼리 및 잠금, 가장 무겁고 빈번한 쿼리, 캐시 적중률 및 작업 세트 크기, autovacuum 및 블로트 추정치, 복제 상태. neon inspect db CLI 명령과 동일한 검사입니다. database_name을 생략하면 브랜치의 모든 데이터베이스를 포함하고, 이름을 전달하면 하나를 검사합니다. 그 중 4개는 pg_stat_statements 또는 neon 확장이 필요합니다.
list_slow_queries: 데이터베이스에서 가장 느린 쿼리를 찾아 성능 병목 현상을 식별합니다. pg_stat_statements 확장이 필요합니다.
explain_sql_statement: SQL 쿼리에 대한 자세한 실행 계획을 제공하여 성능 병목 현상을 식별하는 데 도움을 줍니다.
prepare_query_tuning: 쿼리 성능을 분석하고 인덱스 생성과 같은 최적화를 제안합니다. 이러한 최적화를 안전하게 테스트하기 위해 임시 브랜치를 생성합니다.
complete_query_tuning: 최적화를 기본 브랜치에 적용하거나 폐기하여 쿼리 튜닝을 최종화합니다. 임시 튜닝 브랜치를 정리합니다.

Neon 인증 (?category=neon_auth):

provision_neon_auth, get_auth, disable_auth, update_auth_config
get_neon_auth_config: 호스트 도구, 비밀은 편집됩니다. 설정을 변경하려면 생성된 인증 쓰기 도구를 사용하세요.
list_auth_oauth_providers, add_auth_oauth_provider, update_auth_oauth_provider, delete_auth_oauth_provider
list_auth_trusted_domains, add_auth_trusted_domain, delete_auth_trusted_domain
create_auth_user, delete_auth_user, update_auth_user_role

Neon 데이터 API (?category=data_api):

provision_neon_data_api, get_data_api, update_data_api, delete_data_api: 브랜치 데이터베이스의 데이터 API를 관리합니다.

검색 및 검색:

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

관찰 가능성 (?category=observability): 이러한 도구는 Neon 플랫폼 베타가 필요하며 현재 aws-us-east-2 지역의 프로젝트에서만 사용할 수 있습니다. 로그 액세스 권한이 없는 브랜치는 이유 telemetry_not_enabled과 함께 HTTP 404를 반환합니다.

query_logs: 브랜치에 대한 OpenTelemetry 로그를 쿼리합니다. 관리 API의 POST, 이 서버에서는 읽기 전용으로 처리됩니다.
list_log_fields: 브랜치에서 값을 열거할 수 있는 로그 필드를 나열합니다.
list_log_field_values: 브랜치 및 시간 창 내에서 로그 필드의 고유 값을 나열합니다.

문서 및 리소스 (?category=docs):

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

함수 (?category=functions):

list_functions, get_function, update_function, delete_function, deploy_function
list_functions_custom_domains, register_functions_custom_domain, delete_functions_custom_domain
list_triggers, get_trigger, create_trigger, update_trigger, delete_trigger: 예약된 함수 트리거(type: "schedule", 5개 필드 UTC cron).

스토리지 (?category=storage):

list_storage_buckets, create_storage_bucket, delete_storage_bucket
list_storage_objects, delete_storage_object, delete_storage_objects_by_prefix
presign_storage_object, get_storage

마이그레이션

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

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

개발

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

프로젝트 구조

MCP 서버 코드는 저장소 루트에 있으며, mcp.neon.tech의 Vercel에 배포된 Next.js 애플리케이션입니다.

corepack enable
pnpm install

도구 추가 방법은 CONTRIBUTING.md를 참조하세요. 도구 인수는 snake_case입니다.

로컬 개발

# 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 클라이언트 비밀
`KV_URL`	Vercel KV(Upstash Redis) URL
`OAUTH_DATABASE_URL`	토큰 저장을 위한 Postgres URL

선택 사항:

변수	설명
`LOG_LEVEL`	Winston 로그 레벨: `error`, `warn`, `info` (기본값), `debug`, `verbose`, `silly`
`NEON_MCP_DISABLE_ANALYTICS`	`1`로 설정하면 제품 분석을 비활성화합니다

테스트 피라미드

모든 테스트는 저장소 루트에서 실행됩니다.

# 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를 선호합니다.
결정적인 도구 계약 및 워크플로 동작에는 통합 테스트를 사용합니다.
순수 로직 및 엣지 케이스에는 단위 테스트를 사용합니다.
병합 게이트 테스트에서 타사 가용성에 의존하지 마십시오. 통합/단위 계층에서 외부 종속성을 모의(mock) 처리합니다.

배포

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

텔레메트리

Neon MCP 서버는 사용 패턴을 이해하고 안정성을 개선하기 위해 제품 분석 및 오류 보고서를 수집합니다:

제품 분석 (Segment): 인증된 계정으로 연결하면 서버는 Neon 계정 ID, 이름, 이메일 주소가 포함된 identify 이벤트를 전송합니다. 또한 세션 시작(server_init), 각 도구 호출(tool_call), 예기치 않은 서버 오류(server_error)를 추적합니다. 도구 호출 이벤트에는 도구 이름, 인증 방법, 클라이언트가 포함되며 도구 인수나 쿼리 결과는 포함되지 않습니다. 계정 없이 문서 전용 도구 호출은 익명으로 추적됩니다. 이벤트는 Neon 자체 분석 엔드포인트인 track.neon.tech로 전송됩니다.
오류 보고 (Sentry): 예기치 않은 서버 오류는 스택 추적 및 요청 컨텍스트와 함께 보고됩니다.

이 수집은 Neon 개인정보 보호정책에 포함됩니다. 서버를 직접 실행할 때 분석을 비활성화하려면 NEON_MCP_DISABLE_ANALYTICS=1을 설정하십시오. 해당 플래그는 Sentry를 비활성화하지 않습니다.