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

# TokenLab MCP Server

> MCP 클라이언트를 TokenLab 모델 검색, 가격, OpenAI 호환 채팅 및 네이티브 추론 엔드포인트와 연결합니다.

[TokenLab MCP 서버](https://github.com/hedging8563/tokenlab-mcp-server)는 MCP 호환 에이전트에 실시간 모델 검색, 가격, OpenAI 호환 Chat Completions 및 네이티브 추론 도구를 제공합니다.

에이전트가 모델을 비교하고, 요청 형식을 확인하고, 가격을 조회하거나 OpenAI Chat Completions, Responses, Anthropic Messages 또는 Gemini generateContent로 TokenLab을 호출할 때 사용하세요.

<Note>
  공개 카탈로그 도구는 TokenLab API 키가 필요하지 않습니다. 4개의 유료 추론 도구를 사용하려면 `TOKENLAB_API_KEY`를 설정하세요.
</Note>

## 제공 기능

* `https://api.tokenlab.sh/v1/models`를 통한 실시간 모델 검색.
* `/v1/models/{model}`을 통한 모델 세부 정보 조회.
* `/v1/models/{model}/pricing`을 통한 가격 정보 조회.
* `https://api.tokenlab.sh/llms.txt`를 통한 에이전트 가독형 API 개요 제공.
* OpenAI 호환 채팅, Responses, Anthropic Messages, Gemini, 미디어, 오디오, 임베딩, 리랭크(rerank) 및 번역을 위한 엔드포인트 제품군 가이드.
* OpenAI 호환 Chat Completions, Responses, Anthropic Messages 및 Gemini generateContent를 통한 선택적 추론.

## GitHub에서 설치

공개 저장소를 복제하고 의존성을 설치합니다:

```bash theme={null}
git clone https://github.com/hedging8563/tokenlab-mcp-server.git
cd tokenlab-mcp-server
npm install
npm test
```

stdio를 통해 서버를 시작합니다:

```bash theme={null}
npm start
```

선택 사항인 `TOKENLAB_API_BASE` 환경 변수의 기본값은 `https://api.tokenlab.sh`입니다.

## Codex에 설치

공개 카탈로그 서버를 Codex 구성에 추가합니다:

```bash theme={null}
codex mcp add tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

추가한 후 새 Codex 세션을 시작하세요. 공개 카탈로그 도구에는 `TOKENLAB_API_KEY`가 필요하지 않습니다.

추론 도구를 활성화하려면 서버를 추가할 때 TokenLab API 키를 포함하세요:

```bash theme={null}
codex mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

## Cline에 설치

Cline CLI로 게시된 stdio 서버를 설치합니다:

```bash theme={null}
cline mcp add tokenlab --yes -- npx -y @tokenlabai/mcp-server
```

이 명령은 Cline CLI에서 검증되었으며 설정 경고 없이 완료됩니다. 공개 카탈로그 도구는 즉시 사용할 수 있고, 추론 도구가 필요하면 Cline 환경에 `TOKENLAB_API_KEY`를 설정하세요.

## Claude Desktop 설정

게시된 npm 패키지를 MCP 클라이언트 설정에 추가하세요:

```json theme={null}
{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"]
    }
  }
}
```

설정을 저장한 후 MCP 클라이언트를 재시작하세요.

## Cursor, Windsurf 및 기타 MCP 클라이언트

stdio MCP 서버를 지원하는 모든 클라이언트에서 동일한 명령과 인수를 사용하세요:

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@tokenlabai/mcp-server"],
  "env": {
    "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
  }
}
```

클라이언트가 명명된 서버를 저장하는 경우, 서버 이름으로 `tokenlab-model-catalog`를 사용하세요.

## 도구

| 도구                         | 목적                                                                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `list_models`              | 공개 TokenLab 모델을 나열합니다. `image`, `video`, `embedding`, `rerank` 또는 `translation`과 같은 `recommended_for`를 사용하여 선택적으로 필터링할 수 있습니다. |
| `get_model`                | 특정 모델의 공개 세부 정보와 지원되는 요청 형식을 가져옵니다.                                                                                            |
| `get_model_pricing`        | 특정 모델의 공개 가격 정보를 가져옵니다.                                                                                                        |
| `compare_models`           | 여러 모델 ID의 세부 정보와 가격을 비교합니다.                                                                                                    |
| `create_chat_completion`   | OpenAI 호환 `/v1/chat/completions` 엔드포인트를 호출합니다. 멀티모달 메시지와 도구 호출을 지원하며 `TOKENLAB_API_KEY`가 필요합니다.                                |
| `create_response`          | `/v1/responses` 엔드포인트를 호출합니다. `TOKENLAB_API_KEY`가 필요합니다.                                                                       |
| `create_anthropic_message` | Anthropic Messages `/v1/messages` 엔드포인트를 호출합니다. `TOKENLAB_API_KEY`가 필요합니다.                                                     |
| `create_gemini_content`    | Gemini 네이티브 `generateContent` 엔드포인트를 호출합니다. `TOKENLAB_API_KEY`가 필요합니다.                                                         |
| `get_api_overview`         | 에이전트가 읽을 수 있는 엔드포인트 가이드를 위해 TokenLab의 `llms.txt` 개요를 가져옵니다.                                                                    |

추론 도구는 일반 JSON 결과를 반환합니다. MCP 도구 호출에서는 스트리밍을 의도적으로 비활성화합니다.

## 권장 에이전트 워크플로우

1. 사용자가 모델 이름을 지정하지 않은 경우 `list_models`를 호출합니다.
2. 이미지, 비디오, 음악, 3D, TTS, STT, 임베딩, 리랭크 또는 번역과 같은 비채팅 작업에는 `recommended_for`를 사용합니다.
3. 비채팅 요청을 생성하거나, 실패한 요청을 재시도하거나, 엔드포인트 제품군을 전환하기 전에 `get_model`을 호출합니다.
4. 모델 비용이 사용자의 선택에 영향을 미치는 경우 `get_model_pricing`을 호출합니다.
5. 여러 후보를 비교할 때 `compare_models`를 사용합니다.
6. 필요한 API 계약에 맞는 추론 도구를 호출하거나 `get_api_overview`로 TokenLab API 제품군의 간략한 지도를 확인합니다.

## 네이티브 엔드포인트 가이드

TokenLab은 OpenAI 호환 경로와 네이티브 엔드포인트 제품군을 지원합니다. MCP 서버는 에이전트가 코드를 작성하기 전에 올바른 경로를 선택하도록 돕습니다:

| 제품군                | 일반적인 경로                                                                  |
| ------------------ | ------------------------------------------------------------------------ |
| OpenAI 호환 채팅       | `/v1/chat/completions`                                                   |
| Responses          | `/v1/responses`                                                          |
| Anthropic Messages | `/v1/messages`                                                           |
| Gemini 네이티브        | `/v1beta/models/{model}:generateContent`                                 |
| 이미지                | `/v1/images/generations`, `/v1/images/edits`                             |
| 비디오                | `/v1/videos/generations`                                                 |
| 음악                 | `/v1/music/generations`                                                  |
| 3D                 | `/v1/3d/generations`                                                     |
| 오디오                | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| 임베딩 및 리랭크          | `/v1/embeddings`, `/v1/rerank`                                           |
| 텍스트 번역             | `/v1/translations`                                                       |

## 호스팅 Model Explorer

Streamable HTTP를 지원하는 클라이언트는 다음 주소에 연결할 수 있습니다:

```text theme={null}
https://tokenlab-model-explorer.vercel.app/mcp
```

호스팅 Explorer는 공개되어 있으며 `open_tokenlab_model_explorer`, `compare_tokenlab_models`, `generate_tokenlab_endpoint_example`을 제공합니다. 9개 도구 전체 또는 인증된 추론에는 위의 로컬 npm 서버를 사용하세요.

## TokenLab Skills와 함께 사용하기

MCP 서버는 런타임에 유용하며, [TokenLab skills 저장소](https://github.com/hedging8563/tokenlab-skills)는 코딩 에이전트에게 통합 코드를 생성하고 수정하는 방법을 교육합니다.

사용 가능한 경우 둘 다 사용하세요:

* MCP 서버: 현재 모델, 가격 및 엔드포인트 세부 정보를 검색합니다.
* `tokenlab-api-integration` 스킬: 실행 가능한 API 예제를 생성하고 구조화된 TokenLab 오류를 처리합니다.
* `tokenlab-model-picker` 스킬: 사용자의 작업에 적합한 강력한 모델을 선택합니다.
* `tokenlab-native-endpoints` 스킬: Responses, Anthropic Messages, Gemini, 미디어, 오디오, 임베딩, 리랭크 또는 번역 경로를 사용할 시기를 결정합니다.

## 문제 해결

<AccordionGroup>
  <Accordion title="클라이언트가 서버를 시작할 수 없습니다">
    Node.js 18.17 이상인지 확인한 다음 터미널에서 `npx -y @tokenlabai/mcp-server`를 한 번 실행해 npm 또는 네트워크 오류를 확인하세요.
  </Accordion>

  <Accordion title="모델 목록이 비어 있습니다">
    기계에서 `https://api.tokenlab.sh/v1/models`에 접근할 수 있는지 확인하세요. `TOKENLAB_API_BASE`를 재정의하는 경우, 끝에 슬래시(/)가 포함되지 않았는지 확인하세요.
  </Accordion>

  <Accordion title="에이전트가 여전히 오래된 모델 ID를 선택합니다">
    모델 이름을 하드코딩하기 전에 에이전트에게 `list_models` 또는 `get_model`을 호출하도록 요청하세요. MCP 서버를 `tokenlab-model-picker`와 함께 사용하면 더 나은 결과를 얻을 수 있습니다.
  </Accordion>

  <Accordion title="이 서버로 유료 TokenLab 추론 API를 호출할 수 있나요?">
    예. `TOKENLAB_API_KEY`를 설정한 다음 `create_chat_completion`, `create_response`, `create_anthropic_message` 또는 `create_gemini_content`를 사용하세요. 카탈로그와 가격 도구는 키 없이도 사용할 수 있습니다.
  </Accordion>
</AccordionGroup>

## 리소스

<CardGroup cols={2}>
  <Card title="GitHub 저장소" icon="github" href="https://github.com/hedging8563/tokenlab-mcp-server">
    소스 코드 및 로컬 설정 지침
  </Card>

  <Card title="TokenLab Skills" icon="sparkles" href="https://github.com/hedging8563/tokenlab-skills">
    TokenLab 통합을 위해 유지 관리되는 에이전트 스킬
  </Card>

  <Card title="모델 카탈로그 API" icon="list" href="https://api.tokenlab.sh/v1/models">
    공개 모델 검색 엔드포인트
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    에이전트 가독형 TokenLab API 개요
  </Card>

  <Card title="Glama MCP Server" icon="globe" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-mcp-server">
    검증된 TokenLab MCP Server 목록 보기
  </Card>

  <Card title="Glama 모델 탐색기" icon="search" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-openai-apps-model-explorer">
    모델, 가격, 네이티브 엔드포인트 예시 살펴보기
  </Card>

  <Card title="MCP.so 목록" icon="compass" href="https://mcp.so/servers/tokenlab-mcp-server">
    AI & Agents 디렉터리에서 TokenLab 찾기
  </Card>

  <Card title="호스팅 Model Explorer" icon="rocket" href="https://tokenlab-model-explorer.vercel.app">
    공개 모델 탐색기와 원격 MCP 엔드포인트 열기
  </Card>
</CardGroup>