메인 콘텐츠로 건너뛰기

​
소개

MCP 서버를 쓰면 커스텀 데이터 소스에 연결하고, 그걸 Cursor 안에서 바로 쓸 수 있어. 브라우저, 데이터베이스, 오류·시스템 로그 같은 곳의 컨텍스트가 필요할 때 특히 유용해. MCP 서버 설정은 간단하고, Cursor에서라면 금방 끝낼 수 있어. 이 가이드에선 Postgres용 MCP 서버를 만드는 방법을 차근차근 살펴볼게. 목표는 Cursor가 Postgres 데이터베이스에 직접 SQL 쿼리를 실행하고, 테이블 스키마를 구조화된 형태로 제공하도록 하는 거야.
이 튜토리얼은 MCP 서버를 만드는 기본기를 익히도록 설계되어 있어.

​
MCP 서버란 뭐야?

MCP 서버는 Cursor와 통신하고 외부 데이터나 작업에 접근할 수 있게 해주는 프로세스야. 구현 방법은 여러 가지가 있지만, 여기서는 가장 단순한 방법을 쓸 거야: 네 컴퓨터에서 stdio (표준 입력/출력 스트림)로 로컬 실행되는 서버. 이렇게 하면 복잡한 보안 이슈를 피하고 MCP 로직 자체에 집중할 수 있어. MCP의 가장 흔한 사용 사례 중 하나는 데이터베이스 액세스야. 대시보드를 만들거나, 분석을 돌리거나, 마이그레이션을 만들 때는 데이터베이스를 쿼리하고 살펴봐야 할 때가 많지. 우리가 만들 Postgres MCP 서버는 핵심 기능 두 가지를 지원해: 임의 쿼리 실행과 테이블 스키마 나열. 이 작업들은 순수 SQL만으로도 할 수 있지만, MCP는 이를 더 강력하고 범용적으로 유용하게 만들어주는 기능을 제공해. 툴은 쿼리 실행 같은 작업을 노출하는 수단을 제공하고, 리소스는 스키마 정보 같은 표준화된 컨텍스트를 공유할 수 있게 해줘. 이 가이드 뒤에서는 더 고급 워크플로를 가능하게 하는 프롬프트도 살펴볼 거야. 내부적으로는 postgres npm 패키지를 사용해 데이터베이스에 SQL 문을 실행할 거야. MCP SDK는 이런 호출을 감싸는 래퍼로 동작해서 Postgres 기능을 Cursor에 자연스럽게 통합할 수 있게 해줄 거야.

​
MCP 서버를 빌드하는 방법

서버를 빌드하는 첫 단계는 새 프로젝트를 설정하는 거야. 새 폴더를 만들고 Bun 프로젝트를 초기화하는 것부터 시작하자 
> mkdir postgres-mcp-server
> Bun init
여기서 Blank 프로젝트를 선택할 거야. 보일러플레이트 설정이 끝나면 필요한 의존성을 설치해야 해. zod는 MCP SDK에서 I/O 스키마를 정의하는 데 필요해 
bun add postgres @modelcontextprotocol/sdk zod
여기부터 각 라이브러리의 저장소로 이동해서 해당 README 파일의 원시 파일 콘텐츠 링크를 가져올 거야. 서버를 만들 때 이걸 컨텍스트로 사용할 거야 이제 서버가 어떻게 동작하길 원하는지 정의하자. 그러려면 spec.md를 만들고 상위 수준의 목표를 작성할 거야 
# 사양

- MCP 환경 설정을 통해 DATABASE_URL 정의 허용
- 도구를 통해 Postgres 데이터 쿼리
  - 기본값은 읽기 전용
  - ENV `DANGEROUSLY_ALLOW_WRITE_OPS=true|1` 설정 시 쓰기 작업 허용
- 테이블에 `resources`로 접근
- 스키마 정의에 Zod 사용
보다시피, 이건 꽤 가벼운 스펙이야. 필요하면 더 자세한 내용을 자유롭게 추가해줘. README 링크들과 함께 최종 프롬프트를 구성할 거야. 
우리가 원하는 바를 파악하려면 아래 내용을 읽고 @spec.md를 따르자. 필요한 종속성은 모두 설치되어 있어
- @https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/refs/heads/main/README.md
- @https://raw.githubusercontent.com/porsager/postgres/refs/heads/master/README.md
이 세 가지 구성 요소(스펙, MCP SDK 문서, Postgres 라이브러리 문서)가 준비됐으니, Cursor로 서버 구현을 스캐폴딩할 수 있어. Cursor가 MCP SDK와 Postgres를 연결하는 코드를 생성해서, 각각의 조각을 잘 엮어 줄 거야. 몇 번의 프롬프트 주고받기를 거쳐 이제 MCP 서버의 첫 버전이 돌아가고 있어. 직접 써 보려면 MCP Inspector를 사용하면 돼 
npx @modelcontextprotocol/inspector bun run index.ts

​
MCP 서버 테스트하기

초기 구현이 끝나면 MCP Inspector로 테스트할 수 있어. Inspector는 서버가 어떤 기능을 노출하는지 확인하고, 도구와 리소스가 기대대로 동작하는지 검증할 수 있는 방법을 제공해. 쿼리가 실행되는지, 스키마 정보가 정확히 반환되는지 확인하자. MCP Inspector 인터페이스 모든 게 괜찮아 보이면, 서버를 Cursor에 직접 연결해서 실제 환경에서 테스트해 봐. 이 시점부터 Cursor는 Postgres MCP 서버를 기본 제공 기능처럼 사용할 수 있어서, 데이터베이스를 직접 쿼리하고 살펴볼 수 있어.

​
다음 단계

stdio로 로컬에서 MCP 서버를 실행하는 건 좋은 시작이지만, 팀에선 종종 MCP 서버를 통해 같은 데이터베이스에 공동으로 접근할 필요가 있어. 이런 상황에선 MCP 서버를 중앙집중식 HTTP 서비스로 배포하는 게 필요해. 배포된 MCP 서버는 개별 stdio 인스턴스보다 여러 가지 장점이 있어:
  • 공유 데이터베이스 접근: 여러 팀원이 Cursor를 통해 동일한 데이터베이스 인스턴스를 조회할 수 있어
  • 중앙집중식 구성: 스키마 업데이트와 권한 변경을 한 곳에서 관리할 수 있어
  • 강화된 보안: 적절한 인증, 레이트 리미팅, 접근 제어를 적용할 수 있어
  • 가시성: 팀 전반의 사용 패턴과 성능 지표를 모니터링할 수 있어
이걸 달성하려면 전송 방식을 stdio에서 HTTP로 전환하면 돼. 전체 설정을 전부 다루진 않지만, Cursor에 이렇게 시작하기 좋은 프롬프트를 줄 수 있어 
기존 MCP 서버를 기반으로 HTTP 프로토콜을 구현하는 새 파일을 만들어.

공유 로직은 mcp-core로 옮기고, 각 전송 구현은 이름으로 분리해 (mcp-server-stdio, mcp-server-http)

@https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/refs/heads/main/README.md
최종 결과는 여기에서 볼 수 있어: pg-mcp-server
⌘I