MCP · Model Context Protocol

AI 도구에 공공데이터 API 연결하기

Claude, Cursor, VS Code 같은 AI 도구에 PubGate MCP 서버를 등록하면, AI가 필요한 공공데이터 API를 스스로 찾고, 파라미터를 확인하고, 호출합니다. 예: “서울 종로구 지금 미세먼지 알려줘”, “강남역 근처 지진 대피소 찾아줘”.

필요한 것

서버 주소: https://pubgate.gino.im/api/mcp
방식: Streamable HTTP (원격 서버, 설치 없음)
인증: Authorization: Bearer <PubGate API 키>
받는 데이터: 원본 인증키를 등록하기 전에는 예시 응답(형식 확인용 고정 값)입니다. 실제 데이터는 원본 인증키를 등록하면 받습니다.

무료 가입하고 API 키를 받으세요. 이미 계정이 있으면 로그인. 가입 전에 연결만 확인하려면 키 자리에 데모 키 pg_demo를 쓰세요(예시 응답).

내 API 키 (아래 설정에 넣어 줍니다. 이 화면에서만 쓰고 저장하지 않습니다.)

도구별 설정

Claude Code

터미널에서 한 줄 실행하세요.

claude mcp add --transport http pubgate https://pubgate.gino.im/api/mcp --header "Authorization: Bearer PUBGATE_KEY"

Cursor

~/.cursor/mcp.json(모든 프로젝트) 또는 프로젝트의 .cursor/mcp.json에 넣으세요.

{
  "mcpServers": {
    "pubgate": {
      "url": "https://pubgate.gino.im/api/mcp",
      "headers": { "Authorization": "Bearer PUBGATE_KEY" }
    }
  }
}

VS Code (GitHub Copilot)

프로젝트의 .vscode/mcp.json에 넣으세요.

{
  "servers": {
    "pubgate": {
      "type": "http",
      "url": "https://pubgate.gino.im/api/mcp",
      "headers": { "Authorization": "Bearer PUBGATE_KEY" }
    }
  }
}

Claude Desktop

설정 파일 claude_desktop_config.json에 넣고 앱을 다시 여세요. Node.js가 필요합니다(mcp-remote가 원격 서버를 이어 줍니다).

{
  "mcpServers": {
    "pubgate": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://pubgate.gino.im/api/mcp", "--header", "Authorization:${PUBGATE_AUTH}"],
      "env": { "PUBGATE_AUTH": "Bearer PUBGATE_KEY" }
    }
  }
}

AI가 쓰는 도구

도구	하는 일
`search_catalog`	검색어로 API를 찾습니다. 예: 버스 도착, 단기예보, 대피소.
`describe_operation`	찾은 API의 파라미터, 예시 값, 출처, 응답 형식을 알려 줍니다.
`call_operation`	API를 호출합니다. 기본은 정리된 JSON(`optimized`)입니다. 응답에 `status`(fresh·cached·stale·sample 등)가 함께 옵니다.

연결 확인 (curl)

AI 도구 없이 서버가 응답하는지 보려면 아래를 실행하세요. 도구 목록이 나오면 정상입니다.

curl -s https://pubgate.gino.im/api/mcp \
  -H "Authorization: Bearer PUBGATE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

자주 묻는 질문

값이 늘 같아요: 원본 인증키를 등록하지 않아 예시 응답이 오는 중입니다. status가 sample입니다. 원본 인증키를 등록하세요.
401 오류: API 키가 없거나 틀렸습니다. Authorization 헤더에 Bearer 를 붙였는지 확인하세요.
호출 한도: MCP 호출도 같은 API 키의 레이트리밋과 사용량에 들어갑니다. 사용량에서 확인하세요.

코드에서 직접 부르려면 API 찾기의 복사용 코드나 SDK를 보세요. AI가 읽기 좋은 요약: llms.txt.