> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bridger.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /mcp (JSON-RPC)

> MCP 표준 JSON-RPC 2.0 엔드포인트 — tools/list, tools/call.

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

## Request 헤더

```http theme={null}
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

Bridger에 등록된 모든 도구의 메타데이터를 반환합니다.

### Request

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

### Response 200

```json theme={null}
{
  "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

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "pingtool",
    "arguments": { "q": "hello" }
  }
}
```

### Response 200

```json theme={null}
{
  "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 전체 예시

<CodeGroup>
  ```bash tools/list theme={null}
  curl -X POST https://mcp.datari.kr/mcp \
    -H "x-api-key: $DATA_BRIDGE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  ```

  ```bash tools/call theme={null}
  curl -X POST https://mcp.datari.kr/mcp \
    -H "x-api-key: $DATA_BRIDGE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tools/call",
      "params": {
        "name": "pingtool",
        "arguments": { "q": "hello" }
      }
    }'
  ```
</CodeGroup>

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

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

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

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