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

# 클라이언트 연결하기

> Claude, ChatGPT, Cursor, Claude Code를 비롯한 MCP 호환 AI 클라이언트에서 Tiro MCP 서버를 설정해요.

export const ClientSetupAccordion = ({children}) => <div className="tiro-client-setup">
    <AccordionGroup>{children}</AccordionGroup>
  </div>;

Tiro MCP 서버는 `https://mcp.tiro.ooo/mcp`에 있어요. 사용하는 클라이언트를 골라 단계를 따라가면 연결돼요. 각 클라이언트마다 권장 인증 방식이 있고, 대부분 대체 방식도 지원해요.

<Note>
  **아직 API key가 없으신가요?** [Tiro Platform API Keys 페이지](https://platform.tiro.ooo/dashboard/api-keys)에서 만드세요. key는 `abc123.xR7mK9pL2qW4...` 형태이고, **점(.)을 포함한 전체 문자열**을 복사하세요. 대시보드에는 참고용으로 "Key ID"(예: `abc123`)가 표시되지만, Bearer token은 생성 시 단 한 번만 보이는 **전체 문자열**이에요. 잃어버리면 새로 생성하세요.
</Note>

<ClientSetupAccordion>
  <Accordion title="Claude Desktop" defaultOpen>
    **권장: OAuth.** 한 번 로그인하면 클라이언트가 token을 관리해요.

    <Note>
      [Node.js](https://nodejs.org/)가 필요해요. `mcp-remote` 패키지가 streamable-http를 Claude Desktop이 기대하는 stdio transport로 연결해 줘요.
    </Note>

    플랫폼에 맞는 설정 파일을 여세요.

    <CodeGroup>
      ```bash macOS theme={"system"}
      ~/Library/Application Support/Claude/claude_desktop_config.json
      ```

      ```bash Windows theme={"system"}
      %APPDATA%\Claude\claude_desktop_config.json
      ```

      ```bash Linux theme={"system"}
      ~/.config/Claude/claude_desktop_config.json
      ```
    </CodeGroup>

    OAuth 설정을 추가하세요.

    ```json claude_desktop_config.json theme={"system"}
    {
      "mcpServers": {
        "tiro": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.tiro.ooo/mcp"]
        }
      }
    }
    ```

    Claude Desktop을 재시작하세요. 처음 연결할 때 브라우저가 열리며 Google 로그인이 진행돼요. token은 로컬에 캐시되며 180일간 유효해요.

    **대체: API Key.** 브라우저 흐름을 원하지 않으면 다음을 사용하세요.

    ```json claude_desktop_config.json theme={"system"}
    {
      "mcpServers": {
        "tiro": {
          "command": "npx",
          "args": [
            "-y", "mcp-remote",
            "https://mcp.tiro.ooo/mcp",
            "--header", "Authorization:Bearer YOUR_API_KEY"
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Claude Code (CLI)">
    **권장: API Key.** 브라우저 의존성이 없고 교체하기 쉬워요.

    ```bash theme={"system"}
    claude mcp add --transport http tiro-mcp https://mcp.tiro.ooo/mcp \
      --header "Authorization:Bearer YOUR_API_KEY"
    ```

    **대체: OAuth.** `--header`를 생략하세요. Claude Code가 처음 연결할 때 브라우저를 열어요.

    ```bash theme={"system"}
    claude mcp add --transport http tiro-mcp https://mcp.tiro.ooo/mcp
    ```
  </Accordion>

  <Accordion title="ChatGPT">
    **권장: OAuth.** 브라우저를 사용할 수 있는 대부분의 MCP 클라이언트는 OAuth를 기본 지원해요.

    1. 서버 URL `https://mcp.tiro.ooo/mcp`를 추가하세요.
    2. ChatGPT가 Google 로그인용 브라우저 창을 열어요.
    3. 클라이언트가 access token을 캐시해요.

    내장 브라우저 흐름이 없는 클라이언트라면 `mcp-remote`를 로컬 stdio 프록시로 실행하고 ChatGPT가 그 로컬 프로세스를 가리키게 하세요.

    ```bash theme={"system"}
    npx -y mcp-remote https://mcp.tiro.ooo/mcp
    ```
  </Accordion>

  <Accordion title="Cursor">
    **권장: API Key.**

    1. **Settings** > **MCP**를 여세요.
    2. **Add new MCP server**를 클릭하세요.
    3. transport를 **HTTP**로 설정하세요.
    4. 서버 URL `https://mcp.tiro.ooo/mcp`를 입력하세요.
    5. header를 추가하세요: `Authorization: Bearer YOUR_API_KEY`.
  </Accordion>

  <Accordion title="VS Code (Copilot)">
    **권장: API Key.** workspace에 `.vscode/mcp.json`을 만들거나 편집하세요.

    ```json .vscode/mcp.json theme={"system"}
    {
      "servers": {
        "tiro": {
          "type": "http",
          "url": "https://mcp.tiro.ooo/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="기타 MCP 클라이언트">
    streamable-http를 지원하는 모든 MCP 클라이언트는 아래 원본 값으로 동작해요.

    | Field        | Value                                                        |
    | ------------ | ------------------------------------------------------------ |
    | Server URL   | `https://mcp.tiro.ooo/mcp`                                   |
    | Transport    | HTTP (streamable)                                            |
    | Auth header  | `Authorization: Bearer YOUR_API_KEY`                         |
    | OAuth issuer | `https://mcp.tiro.ooo` (클라이언트가 OAuth 2.0 with PKCE를 지원하는 경우) |

    stdio만 지원하는 클라이언트라면 endpoint를 `mcp-remote`로 감싸세요.

    ```bash theme={"system"}
    npx -y mcp-remote https://mcp.tiro.ooo/mcp \
      --header "Authorization:Bearer YOUR_API_KEY"
    ```
  </Accordion>
</ClientSetupAccordion>

***

## Scopes

scope는 MCP 서버가 사용자를 대신해 접근할 수 있는 범위를 정의해요. 현재 API key는 자동으로 **모든 scope**를 부여받아요.

| Scope              | 설명                             |
| ------------------ | ------------------------------ |
| `mcp:notes:read`   | 노트, transcript, 요약, 문서, 템플릿 읽기 |
| `mcp:folders:read` | 사용자 및 팀 폴더 구조 검색               |

<Note>
  세분화된 scope 선택은 아직 제공되지 않아요. 인증된 모든 연결은 전체 접근 권한을 받아요. 세밀한 scope 제어는 향후 릴리스에 계획되어 있어요.
</Note>

***

## API key 종류

| Key Kind             | 묶이는 대상     | 접근 범위                                                   |
| -------------------- | ---------- | ------------------------------------------------------- |
| **user 범위 key**      | 한 명의 사용자   | 해당 사용자가 접근할 수 있는 모든 노트, 요약, 문서, 폴더 — 여러 워크스페이스에 걸칠 수 있음 |
| **workspace 범위 key** | 하나의 워크스페이스 | 해당 단일 워크스페이스의 모든 것. 사용자 신원 없음                           |

<Info>
  **어떤 key가 필요한가요?** 대부분 **user 범위 key**로 시작해요. 본인이 속한 모든 워크스페이스에 걸쳐, 팀 폴더의 노트를 포함해 접근 권한이 있는 모든 노트를 검색하고 읽을 수 있어요. **workspace 범위 key**는 하나의 워크스페이스에 묶여 자동으로 그 워크스페이스를 검색해요. 두 종류 모두 폴더 도구(`search_private_folders`, `search_team_folders`)를 쓸 수 있어요 — 둘 다 `mcp:folders:read` scope만 있으면 되고, 개인/팀 구분은 폴더 타입이지 key 종류가 아니에요.
</Info>

API key는 [Tiro Platform API Keys 페이지](https://platform.tiro.ooo/dashboard/api-keys)에서 폐기하지 않는 한 만료되지 않아요. key는 주기적으로 교체하고, 개발용과 운영용으로 별도의 key를 사용하기를 권장해요.

OAuth token은 **180일**간 유효해요. 더 빨리 교체하려면 클라이언트에서 로그아웃한 뒤 다시 로그인하세요. 즉시 폐기가 필요하면 지원팀에 문의하세요.

연결되면 [사용 가능한 도구](/ko/developers/mcp/tools/overview)를 살펴보세요. 클라이언트가 연결되지 않으면 [문제 해결](/ko/developers/mcp/troubleshooting)로 이동하세요.