​
소개

MCP 서버를 쓰면 커스텀 데이터 소스에 연결하고 Cursor 안에서 바로 쓸 수 있어. 브라우저, 데이터베이스, 에러/시스템 로그 같은 곳에서 컨텍스트가 필요할 때 특히 유용해. MCP 서버 설정은 간단하고, Cursor랑 함께라면 빠르게 끝낼 수 있어. 이 가이드에선 Postgres용 MCP 서버를 만드는 방법을 살펴볼 거야. 목표는 Cursor가 Postgres 데이터베이스에 직접 SQL 쿼리를 실행하고, 테이블 스키마를 구조적으로 노출할 수 있게 하는 거야.
이 튜토리얼은 MCP 서버를 만드는 기본기를 익히도록 설계됐어.

​
MCP 서버가 뭐야?

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

​
MCP 서버를 만드는 방법

서버를 빌드하는 첫 단계는 새 프로젝트를 설정하는 거야. 새 폴더를 만들고 Bun 프로젝트를 초기화하는 것부터 시작하자. 
> mkdir postgres-mcp-server
> Bun init
여기서는 Blank 프로젝트를 선택하면 돼. 보일러플레이트가 준비되면 필요한 의존성을 설치하자. MCP SDK에서 입출력 스키마를 정의하려면 zod가 필요해. 
bun add postgres @modelcontextprotocol/sdk zod
이제 각 라이브러리의 리포지토리로 가서 각 README 파일의 원본(raw) 콘텐츠 링크를 가져오자. 서버를 만들 때 참고 자료로 사용할 거야. 이제 서버의 동작 방식을 정의하자. 그러려면 spec.md를 만들고 상위 목표를 적어 두면 돼. 
# Spec

- 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를 통해 동일한 DB 인스턴스를 쿼리할 수 있어
  • 중앙집중형 구성: 스키마 업데이트와 권한 변경을 한 곳에서 관리할 수 있어
  • 보안 강화: 적절한 인증, rate limiting, 접근 제어를 적용할 수 있어
  • 가시성: 팀 전반의 사용 패턴과 성능 지표를 모니터링할 수 있어
이를 위해 전송 방식을 stdio에서 HTTP로 전환하면 돼. 전체 설정을 모두 다루진 않지만, Cursor에 이렇게 시작 프롬프트를 줄 수 있어 
Based on the existig MCP server, create a new file that implements the HTTP protocol.

Move shared logic to mcp-core, and name each transport implementation by name (mcp-server-stdio, mcp-server-http)

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