> ## 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에서 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)에서 만드세요. `abc123.xR7mK9pL2qW4...`처럼 점(.)을 포함한 전체 문자열을 복사해야 해요. 전체 키는 생성할 때 한 번만 볼 수 있어요.
</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>

***

## 권한 범위

권한 범위는 MCP 서버가 접근할 수 있는 리소스를 정의해요. 현재 API 키에는 모든 권한 범위가 자동으로 부여돼요.

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

<Note>
  세부 권한 범위 선택은 아직 지원하지 않아요. 인증된 연결에는 전체 접근 권한이 부여돼요.
</Note>

***

## API 키 종류

| 키 종류                | 묶이는 대상     | 접근 범위                                               |
| ------------------- | ---------- | --------------------------------------------------- |
| **사용자 범위 API 키**    | 한 명의 사용자   | 사용자가 접근할 수 있는 모든 노트, 요약, 문서, 폴더. 여러 워크스페이스에 걸칠 수 있음 |
| **워크스페이스 범위 API 키** | 하나의 워크스페이스 | 해당 워크스페이스의 모든 리소스. 사용자 신원 없음                        |

<Info>
  **어떤 키가 필요한가요?** 대부분 **사용자 범위 API 키**로 시작해요. 사용자가 속한 모든 워크스페이스에서 접근 권한이 있는 노트를 검색하고 읽을 수 있어요. **워크스페이스 범위 API 키**는 연결된 워크스페이스만 검색해요. 두 키 모두 `mcp:folders:read` 권한으로 폴더 도구(`search_private_folders`, `search_team_folders`)를 사용할 수 있어요.
</Info>

API 키는 [Tiro Platform API Keys 페이지](https://platform.tiro.ooo/dashboard/api-keys)에서 폐기하지 않는 한 만료되지 않아요. 개발용과 운영용 키를 분리하고 주기적으로 교체하세요.

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

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