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

# MCP 활용 사례

> AI 에이전트를 위한 단계별 워크플로: Tiro MCP 도구로 미팅을 검색하고 문서를 생성하기

Tiro MCP 도구는 [Progressive Disclosure 패턴](/ko/developers/mcp/mcp-overview)을 중심으로 설계됐어요. 메타데이터를 먼저 불러오고, 세부 내용은 필요할 때만 가져와요. 아래 워크플로는 token 사용량을 최소로 유지하면서 흔한 작업을 위해 도구를 연결하는 방법을 보여줘요.

<Tip>
  **Tiro MCP가 처음이신가요?** 먼저 [개요](/ko/developers/mcp/mcp-overview)로 아키텍처를 이해한 뒤, 이 워크플로를 시도하기 전에 [클라이언트](/ko/developers/mcp/setup)를 설정하세요.
</Tip>

***

## 미팅을 찾고 논의 내용을 읽는 방법

Tiro의 노트 탐색 영역은 **3단계 진행 구조**예요. `list_notes`로 가볍게 시작하고, 문서 내용이 필요하면 `search_notes`로 들어가고, 발화 그대로의 원문이 필요할 때만 `get_note_transcript`까지 가요. 대부분의 사용자 질문은 1단계나 2단계에서 끝나요.

### 단계별 안내

<Steps>
  <Step title="후보 노트 나열하기 (가장 저렴)">
    [`list_notes`](/ko/developers/mcp/tools/list-notes)를 선택적 `query.keyword`와 `filter`와 함께 호출해 결과를 좁히세요. 메타데이터만 반환해요(노트당 약 50 tokens).

    ```json theme={"system"}
    {
      "query": { "keyword": "product roadmap" },
      "filter": { "createdAtFrom": "2026-04-01T00:00:00Z" },
      "pagination": { "size": 20 }
    }
    ```

    `filter.folderId`로 특정 폴더로 범위를 좁히거나, `query.keyword`를 아예 생략해 날짜순으로 폴더를 둘러보세요.
  </Step>

  <Step title="매칭된 노트의 문서 읽기">
    어떤 노트가 매칭되는지 보는 것을 넘어 논의 내용을 **이해**해야 한다면, 필수 `keyword`와 함께 [`search_notes`](/ko/developers/mcp/tools/search-notes)를 호출하세요. 응답에는 매칭된 각 노트의 주요 문서(one-pager, custom)가 HTML이 제거된 채 문서당 최대 5KB로 인라인 포함돼요.

    ```json theme={"system"}
    {
      "keyword": "product roadmap",
      "filter": { "createdAtFrom": "2026-04-01T00:00:00Z" },
      "pagination": { "size": 10 }
    }
    ```

    매칭된 노트를 최대 10개까지 문서와 함께 반환해요(노트당 약 1,500 tokens). **대부분의 쿼리는 여기서 끝나요.** 정제된 문서가 보통 팀의 결정 사항과 action item을 담고 있거든요.
  </Step>

  <Step title="단일 AI 요약 가져오기 (선택)">
    요약 개요가 필요하면 [`get_note`](/ko/developers/mcp/tools/get-note)를 `include: ["summary"]`와 함께 호출하세요.

    ```json theme={"system"}
    {
      "noteGuid": "f8a2c1e4-9b3d-4e7f-a6c8-1d2e3f4a5b6c",
      "include": ["summary"]
    }
    ```

    핵심 결정 사항, action item, 하이라이트를 반환해요(200\~800 tokens).
  </Step>

  <Step title="전체 transcript 불러오기 (최후의 수단)">
    **정확한 인용**이나 특정 발화가 필요할 때만 [`get_note_transcript`](/ko/developers/mcp/tools/get-transcript)를 호출하세요. 타임스탬프가 붙은 문단과 markdown 친화적인 전사 문자열을 반환해요(미팅 1시간당 약 3,000\~5,000 tokens).

    ```json theme={"system"}
    {
      "noteGuid": "f8a2c1e4-9b3d-4e7f-a6c8-1d2e3f4a5b6c"
    }
    ```
  </Step>
</Steps>

### Token 사용량

| 방식                                    | Tokens             | 속도    |
| ------------------------------------- | ------------------ | ----- |
| `list_notes`만 (후보 찾기)                 | 노트당 약 50           | 가장 빠름 |
| `list_notes` → `search_notes` (문서 읽기) | 노트당 약 1,500        | 빠름    |
| `get_note_transcript` 직접 불러오기         | 시간당 약 3,000\~5,000 | 가장 느림 |
| **transcript 대비 절감**                  | **70\~80%**        | —     |

### 자주 묻는 질문

<AccordionGroup>
  <Accordion title="list_notes와 search_notes는 언제 쓰나요?">
    \*\*`list_notes`\*\*는 폴더, 날짜, 키워드 포함 여부로 **어떤 노트가 있는지 알아야 할 때** 쓰세요. 메타데이터만 반환해요.

    \*\*`search_notes`\*\*는 어떤 주제의 결정 사항, action item, 결론 등 **맥락을 이해해야 할 때** 쓰세요. 매칭된 노트를 문서와 함께 인라인으로 반환해요. 키워드는 필수예요.
  </Accordion>

  <Accordion title="list_notes가 결과를 반환하지 않으면?">
    더 넓은 조건으로 시도하세요.

    * `query.keyword`를 빼거나 짧게 줄이세요.
    * `filter.createdAtFrom` / `createdAtTo` 범위를 넓히거나 제거하세요.
    * [Tiro Dashboard](https://tiro.ooo)에서 노트가 "Completed" 상태인지 확인하세요. 완료되지 않은 노트는 자동으로 제외돼요.
  </Accordion>

  <Accordion title="search_notes 문서와 get_note_transcript 중 무엇을 선호해야 하나요?">
    \*\*`search_notes`\*\*를 선호하세요. 정제된 문서는 보통 원본 transcript보다 10배 더 압축적이고, 팀의 결정 사항, action item, 결론을 의도된 구조로 담고 있어요. 직접 인용을 위해 발화 그대로의 원문이 필요할 때만 \*\*`get_note_transcript`\*\*를 쓰세요.
  </Accordion>

  <Accordion title="createdAtFrom / createdAtTo는 어떤 날짜 형식을 받나요?">
    타임존이 포함된 ISO 8601 datetime이에요: `2026-04-01T00:00:00Z`. `2026-04-01`처럼 날짜만 있는 형식은 받지 않아요. 범위는 반열린 구간 `[from, to)`예요.
  </Accordion>

  <Accordion title="workspace 범위 API key로 키워드 검색을 쓸 수 있나요?">
    네. `list_notes`와 `search_notes`의 키워드 검색은 user 범위와 workspace 범위 API key 모두에서 동작해요. `workspaceGuid`를 생략하면 접근 가능한 모든 워크스페이스를 검색해요 — workspace 범위 key는 자동으로 자신의 워크스페이스를 검색해요. 특정 워크스페이스를 대상으로 하려면 명시적인 `workspaceGuid`(`list_workspaces`에서 확인)를 전달하세요.
  </Accordion>
</AccordionGroup>

***

## 미팅 노트에서 구조화된 문서를 생성하는 방법

AI 에이전트는 Tiro의 템플릿 기반 문서 시스템을 사용해 모든 미팅에서 action item, 결정 사항, 핵심 요점을 추출할 수 있어요. 각 문서는 템플릿으로 정의된 섹션 구조로 짜여 있어요.

### 단계별 안내

<Steps>
  <Step title="사용 가능한 템플릿 둘러보기">
    [`list_document_templates`](/ko/developers/mcp/tools/get-note)를 호출해 어떤 문서 유형이 있는지 확인하세요.

    ```json theme={"system"}
    {}
    ```

    "Meeting Minutes", "Action Items", "Decision Log" 같은 템플릿을 반환하며, 각각 `id`, `title`, `description`을 포함해요.
  </Step>

  <Step title="대상 미팅 찾기">
    [`list_notes`](/ko/developers/mcp/tools/list-notes)를 호출해 키워드(또는 폴더, 날짜 범위)로 미팅을 찾으세요.

    ```json theme={"system"}
    {
      "query": { "keyword": "sprint planning" }
    }
    ```
  </Step>

  <Step title="문서 가져오기">
    [`get_note`](/ko/developers/mcp/tools/get-note)를 `include: ["documents"]`와 함께 호출해 해당 노트의 생성된 모든 문서를 한 번에 가져오세요.

    ```json theme={"system"}
    {
      "noteGuid": "f8a2c1e4-9b3d-4e7f-a6c8-1d2e3f4a5b6c",
      "include": ["documents"]
    }
    ```

    미팅에 대해 생성된 모든 문서를 구조화된 섹션(예: "Decisions", "Action Items", "Next Steps")과 함께 반환해요.
  </Step>
</Steps>

### 자주 묻는 질문

<AccordionGroup>
  <Accordion title="어떤 템플릿을 써야 할지 어떻게 아나요?">
    먼저 [`list_document_templates`](/ko/developers/mcp/tools/get-note)를 호출하세요. 각 템플릿에는 용도를 설명하는 `description` 필드가 있어요. 문서를 요청하기 전에 [`get_document_template`](/ko/developers/mcp/tools/get-note)를 특정 `templateId`와 함께 사용해 전체 섹션 구조를 확인하세요.
  </Accordion>

  <Accordion title="노트에 아직 문서가 없으면?">
    `get_note(include: ["documents"])`는 빈 배열을 반환해요. 문서는 먼저 Tiro 앱에서 생성해야 해요. MCP 서버는 기존 문서에 대한 읽기 접근만 제공해요. 노트 소유자에게 Tiro에서 문서를 생성해 달라고 요청하세요.
  </Accordion>
</AccordionGroup>

***

***

## AI 에이전트 개발자를 위한 팁

### Token 최적화

* 항상 `list_notes`로 시작하세요(노트당 약 50 tokens). 문서 내용이 필요할 때만 `search_notes`로 들어가고(노트당 약 1,500 tokens), 발화 그대로의 인용이 필요할 때만 `get_note_transcript`까지 가세요.
* `pagination.size`로 결과 수를 제한하세요. `list_notes`는 기본 `20`(최대 `100`), `search_notes`는 기본 `10`(최대 `30`, 각 결과에 문서가 포함되어 더 작음)이에요.
* 요약과 문서에는 `MARKDOWN` 형식을 선호하세요. 더 구조적이고 LLM이 파싱하기 쉬워요.

### 오류 처리

* `401`과 `403` 응답에는 `action_url`과 `docs_url` 필드가 포함돼요. 사용자가 스스로 해결할 수 있도록 이를 노출하세요.
* `429` 응답에는 `Retry-After` 헤더가 포함돼요. 재시도하기 전에 이를 준수하세요.
* 전체 오류 레퍼런스는 [문제 해결](/ko/developers/mcp/troubleshooting)을 참고하세요.

### 올바른 도구 고르기

| 사용자 의도               | 시작 도구                                                          | 다음                                                                        |
| -------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| "X 주제로 어떤 미팅이 있지?"   | [`list_notes`](/ko/developers/mcp/tools/list-notes)            | — (메타데이터로 충분)                                                             |
| "이 미팅에서 무슨 얘기가 나왔지?" | [`search_notes`](/ko/developers/mcp/tools/search-notes)        | (문서 인라인 포함, 보통 충분)                                                        |
| "실제로 한 말을 인용해줘"      | [`list_notes`](/ko/developers/mcp/tools/list-notes)            | [`get_note_transcript`](/ko/developers/mcp/tools/get-transcript)          |
| "action item 알려줘"    | [`list_notes`](/ko/developers/mcp/tools/list-notes)            | [`get_note`](/ko/developers/mcp/tools/get-note), `include: ["documents"]` |
| "어떤 문서 템플릿이 있지?"     | [`list_document_templates`](/ko/developers/mcp/tools/get-note) | [`get_document_template`](/ko/developers/mcp/tools/get-note)              |
| "내가 인증되어 있나?"        | [`auth_status`](/ko/developers/mcp/tools/auth-status)          | —                                                                         |

전체 도구 목록은 [Tool Reference](/ko/developers/mcp/tools/overview)에서 둘러보세요.