> ## 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.

# BYOAPI — 자체 API 등록

> OpenAPI 스펙이 있는 어떤 API든 Bridger에 도구로 등록하는 멀티-테넌트 ID 기반 파이프라인.

Bridger의 **BYOAPI(Bring Your Own API)** 는 OpenAPI 스펙만 가지고 있다면 어떤 API든
**별도 컨테이너 빌드/배포 없이** Bridger Gateway의 MCP 도구로 등록하는 기능입니다.

<Note>
  BYOAPI는 **추후 제공 예정**입니다. 아래 내용은 동작 방식을 미리 안내하는 것으로, 현재는
  공식 프리셋 카탈로그를 통해 도구를 제공합니다.
</Note>

## 핵심 아이디어 — 배포가 아니라 등록

<CardGroup cols={2}>
  <Card title="기존 방식" icon="container-storage">
    API 한 개당 컨테이너 한 개를 빌드·배포·운영. 비용·관리 모두 폭증.
  </Card>

  <Card title="Bridger BYOAPI" icon="bolt">
    Tool 정의만 DB에 등록. 단일 Gateway가 ID로 라우팅 → 수 초 내 완료.
  </Card>
</CardGroup>

```text theme={null}
하나의 Bridger Gateway (mcp.datari.kr)
  ├─ 공식 프리셋   tool_id: @datari/weather-ultra-shortcast   → tool: getultrashortcast
  ├─ 공식 프리셋   tool_id: @datari/realestate-apt-trade      → tool: getapttrade
  ├─ BYOAPI       tool_id: @user123/my-petstore              → tool: listpets, getpetbyid
  ├─ BYOAPI       tool_id: @company/internal-crm             → tool: ...
  └─ ... 230+ tools
```

## 도구 이름과 식별자 체계

Bridger에는 두 가지 등록 경로가 있고, 식별자 체계가 다릅니다.

**1. 공식 프리셋** — `vendor/spec`의 OpenAPI YAML에서 Gateway가 직접 로드합니다.

* **Tool ID**(레지스트리 등록 ID)는 프리셋 파일 경로 기반의 `@datari/{category}-{name}` 형식입니다. 예: `@datari/weather-ultra-shortcast`. 인메모리 서버 카탈로그(`/registry/servers`)에서는 동일 그룹이 `servers[].id` = `{category}/{name}`(예: `weather/ultra-shortcast`)로 노출됩니다.
* **도구 이름**(`tools[].name`)은 OpenAPI `operationId`에서 파생됩니다. 영숫자가 아닌 문자를 밑줄(`_`)로 치환한 뒤 소문자로 변환합니다. 예: `getUltraShortcast` → `getultrashortcast`. 도구 이름 자체에는 네임스페이스 접두사가 없으며, `tools/call`에는 이 이름을 그대로 사용합니다.

**2. BYOAPI 도구** — 사용자가 `/api/v1/register`로 등록한 도구입니다.

* **Tool ID**는 `@{owner}/{slug}` 네임스페이스를 가집니다. 예: `@user123/my-petstore`, `@company/internal-crm`. owner가 `@`로 시작하지 않으면 자동으로 `@`가 붙습니다.
* 개별 도구 이름은 프리셋과 동일하게 `operationId`에서 파생된 이름입니다. 예: `listpets`.
* 등록 시 카테고리를 지정하지 않으면 기본값은 `byoapi`이며, 공개 데이터로 감지되면 해당 카테고리가 적용됩니다.

| 구분                | 식별자 형식                      | 예시                                |
| ----------------- | --------------------------- | --------------------------------- |
| 공식 프리셋 (Tool ID)  | `@datari/{category}-{name}` | `@datari/weather-ultra-shortcast` |
| 공식 프리셋 (도구 이름)    | `operationId` 파생            | `getultrashortcast`               |
| BYOAPI (tool\_id) | `@{owner}/{slug}`           | `@user123/my-petstore`            |

## 등록 파이프라인

<Steps>
  <Step title="Ingestion">
    OpenAPI 스펙을 URL · 파일 업로드 · 인라인 텍스트 중 하나로 입력합니다.
  </Step>

  <Step title="Validation">
    스펙 유효성과 변환 가능한 엔드포인트 수를 점검하고 적합성 점수(`score`)를 계산합니다.
    유효하지 않거나 변환할 엔드포인트가 없으면 `422`로 거부됩니다.
  </Step>

  <Step title="Generation">
    OpenAPI `paths`를 MCP Tool 정의로 변환합니다 (`name`, `description`, `inputSchema`).
  </Step>

  <Step title="Registration">
    Tool Registry DB에 등록 — **컨테이너 배포 없음**.
  </Step>

  <Step title="Ready">
    즉시 `mcp.datari.kr/mcp`의 `tools/list`에 노출, `tools/call` 시 런타임 프록시로 upstream 호출.
  </Step>
</Steps>

## 등록 후 동작

| 단계     | 설명                                            |
| ------ | --------------------------------------------- |
| 도구 노출  | 등록된 도구는 `tools/list` 응답에 포함됩니다.               |
| 호출 라우팅 | `tools/call` 요청의 도구 ID를 기준으로 대상 API를 선택합니다.   |
| 인증 주입  | 저장된 인증 설정에 따라 upstream 요청에 필요한 헤더나 토큰을 주입합니다. |
| 응답 정규화 | upstream 응답을 MCP 클라이언트가 읽기 쉬운 형태로 반환합니다.      |

## tools/list 응답 예시

```json theme={null}
{
  "tools": [
    {
      "name": "getweatherforecast",
      "description": "기상청 단기예보 — 위치 기반 날씨 정보",
      "inputSchema": {
        "type": "object",
        "properties": {
          "nx": { "type": "integer", "description": "예보지점 X 좌표" },
          "ny": { "type": "integer", "description": "예보지점 Y 좌표" }
        },
        "required": ["nx", "ny"]
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": false
      }
    },
    {
      "name": "listpets",
      "description": "List all pets in the store",
      "inputSchema": { /* ... */ }
    }
  ]
}
```

## 데이터 모델 (요약)

```sql theme={null}
CREATE TABLE tool_registrations (
  id            UUID PRIMARY KEY,
  owner_id      UUID NOT NULL REFERENCES users(id),
  tool_id       VARCHAR(128) NOT NULL UNIQUE,   -- 프리셋: @datari/{category}-{name}, BYOAPI: @{owner}/{slug}
  display_name  VARCHAR(256),
  description   TEXT,
  category      VARCHAR(64),

  source_type   VARCHAR(16),     -- preset | byoapi | manual
  source_spec   TEXT,            -- 원본 OpenAPI (압축)
  spec_hash     VARCHAR(64),     -- SHA-256

  upstream_base_url VARCHAR(512),
  upstream_paths    JSONB,       -- [{method, path, operationId, inputSchema, ...}]
  auth_config       JSONB        -- {type, header, tokenEndpoint, ...}
);
```

세부 등록 화면과 필드 설명은 어드민 대시보드의 BYOAPI 등록 플로우에서 확인할 수 있습니다.

<Note>
  내 API를 공용 프리셋으로 모두에게 제공하고 싶다면 [support@datari.kr](mailto:support@datari.kr)
  또는 채널톡으로 문의해 주세요.
</Note>

## 다음 단계

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Registry · MCP JSON-RPC · SSE 전체 스펙.
  </Card>

  <Card title="인증·보안" icon="shield" href="/concepts/auth-and-security">
    BYOAPI 등록 도구의 시크릿/감사/PII 처리.
  </Card>
</CardGroup>