POST /mcp (JSON-RPC)

Bridger Gateway의 핵심 MCP 호출 엔드포인트입니다. JSON-RPC 2.0 규격을 그대로 따릅니다.

Request 헤더

POST /mcp HTTP/1.1
Content-Type: application/json
x-api-key: dk_live_...

공통 에러 코드

코드	의미
`-32600`	Invalid JSON-RPC request
`-32601`	Method not found
`-32602`	Invalid params (예: 도구 이름 누락)
`-32000`	Internal gateway error

tools/list

도구 메타데이터를 반환합니다. 기본 호출은 기본 프로필 — search_tools + 사용량 상위 도구 + 대시보드에서 직접 켠 도구로 구성된 최대 40개의 목록 — 을 반환합니다. 전체 카탈로그(230+ 도구)가 필요하면 엔드포인트 URL에 ?activation=all을 붙이세요.

전체 카탈로그 (개발자용)

POST https://mcp.bridger.kr/mcp?activation=all

기본 프로필은 클라이언트의 도구 선택 품질을 높이기 위한 짧은 목록입니다. 목록에 없는 도구도 tools/call로 호출할 수 있으며, search_tools로 자연어 검색해 찾을 수 있습니다. 클라이언트별 상한도 적용됩니다 — Gemini Enterprise(?connector=gemini 또는 /mcp/gemini)는 최대 100개 actions까지 노출됩니다.

도구 변경 알림 (`notifications/tools/list_changed`)

대시보드에서 도구를 켜거나 끄면 SSE 스트림(GET /mcp)으로 notifications/tools/list_changed JSON-RPC 알림이 전송됩니다. 알림을 받으면 tools/list를 다시 호출해 최신 목록을 가져오세요.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Response 200

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "pingtool",
        "description": "Ping endpoint",
        "inputSchema": { "type": "object", "properties": {} },
        "annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "openWorldHint": false
        }
      }
    ]
  }
}

tools/call

도구 한 개를 실행합니다.

Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "pingtool",
    "arguments": { "q": "hello" }
  }
}

Response 200

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tool": "pingtool",
    "upstream": {
      "method": "GET",
      "url": "http://127.0.0.1:9921/ping?q=hello",
      "status": 200
    },
    "data": { "ok": true, "q": "hello" },
    "cacheStatus": "MISS",
    "auditId": "aud_..."
  }
}

필드	설명
`result.tool`	호출된 도구 이름
`result.upstream.method`	upstream HTTP 메서드
`result.upstream.url`	upstream 최종 URL (ServiceKey 등 미들웨어 주입 후)
`result.upstream.status`	upstream HTTP 상태 코드
`result.data`	upstream 응답 본문 (XML→JSON 정규화 후)
`result.cacheStatus`	캐시 적중 여부 (`HIT`/`MISS` 등)
`result.auditId`	이 호출의 감사 로그 식별자

cURL 전체 예시

curl -X POST https://mcp.bridger.kr/mcp \
  -H "x-api-key: $BRIDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -X POST https://mcp.bridger.kr/mcp \
  -H "x-api-key: $BRIDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "pingtool",
      "arguments": { "q": "hello" }
    }
  }'

공공데이터 미들웨어 자동 동작

isPublicData=true인 프리셋의 도구 호출 시 다음이 자동 적용됩니다.

ServiceKey 주입 (PUBLIC_DATA_SERVICE_KEY)
lat/lon → nx/ny 격자좌표 변환 (기상청 DFS)
XML/JSON payload 정규화
공공데이터 에러코드 → 사람이 읽는 메시지 매핑

코드	메시지
`00`	정상
`30`	등록되지 않은 서비스키
`31`	활용기간 만료 서비스키
`32`	등록되지 않은 IP
기타	`알 수 없는 공공데이터 에러 (<code>)`

​Request 헤더

​공통 에러 코드

​tools/list

​도구 변경 알림 (notifications/tools/list_changed)

​Request

​Response 200

​tools/call

​Request

​Response 200

​cURL 전체 예시

​공공데이터 미들웨어 자동 동작

Request 헤더

공통 에러 코드

tools/list

도구 변경 알림 (`notifications/tools/list_changed`)

Request

Response 200

tools/call

Request

Response 200

cURL 전체 예시

공공데이터 미들웨어 자동 동작