Skip to main content
MCP 설정 문제는 주로 인증 헤더, 전송 방식, 클라이언트 캐시에서 생겨요. 아래 순서대로 확인하고 설정을 바꾼 뒤에는 클라이언트를 재시작하세요.

​
연결 문제

​
서버를 찾을 수 없음

MCP 서버 URL이 https://mcp.tiro.ooo/mcp인지 확인하세요.
  • 경로 끝의 /mcp 누락
  • https:// 대신 http:// 사용
다음 명령으로 연결을 확인하세요.
예상 응답: 405 Method Not Allowed (GET 요청에선 정상이에요).

​
도구가 안 보임

  1. MCP 클라이언트를 완전히 재시작하세요(창 새로고침 말고)
  2. AI에게 “List all available MCP servers”라고 물어 Tiro가 나오는지 확인하세요
  3. 그래도 없으면 클라이언트 설정을 다시 진행하세요

​
인증 에러

​
API Key 문제

잘못된 API Key 형식 API Key는 {id}.{secret} 형식(점으로 구분된 두 부분)을 따라야 해요. 자주 하는 실수:
  • key의 일부만 복사(점 앞이나 뒤 부분 누락)
  • key에 공백이나 줄바꿈 문자가 섞임
  • 실제 key 대신 placeholder 값 사용
만료되거나 폐기된 Key API Key는 Tiro Dashboard에서 만료되거나 폐기될 수 있어요. 이전에 쓰던 API key로 401 UNAUTHORIZED 에러가 나면:
  1. Tiro Platform API Keys로 가세요
  2. key가 아직 활성인지 확인하고, 필요하면 새로 발급하세요
  3. MCP 클라이언트 설정을 새 key로 업데이트하세요

​
401 Unauthorized / 403 Forbidden

API Key 사용 시: key가 유효하고 만료되지 않았으며 호출하려는 도구에 필요한 scope를 가졌는지 확인하세요. 전체 scope 표는 Setup 페이지를 보세요. OAuth 사용 시: MCP 클라이언트를 재시작해 새 OAuth 흐름을 트리거하세요.
  • Claude Code: CLI 세션 재시작
  • Claude Desktop: 앱을 완전히 종료 후 재실행
  • Cursor: 에디터 재시작 또는 MCP extension 리로드
  • VS Code: 에디터 재시작 또는 MCP extension 리로드
OAuth는 올바른 scope로 새 token을 자동 발급해요. token은 180일 동안 유효해요.

​
INSUFFICIENT_SCOPE 에러

도구 호출이 INSUFFICIENT_SCOPE 에러를 돌려주면, 자격증명에 그 도구가 요구하는 scope가 없는 거예요. 부족한 scope는 에러 메시지에 표시돼요(예: mcp:note:write).
  • API Key: Tiro Platform API Keys에서 필요한 scope를 가진 key를 발급하세요.
  • OAuth: 다시 연결하세요. 부족한 scope가 :write면 consent 화면에서 읽기 + 쓰기를 선택하고, 읽기 scope라면 읽기 전용으로도 충분해요. 클라이언트가 재인가를 지원하면 에러 응답의 안내에 따라 자동으로 승인 화면이 다시 열려요.

​
설정 문제

​
Claude Code 연결 실패

  1. 설정이 Claude Code setup과 맞는지 확인하세요
  2. CLI 세션을 재시작하세요
  3. OAuth를 쓰는데 브라우저 창이 안 열리면 기본 브라우저 설정을 확인하세요
  4. API Key를 쓴다면 key 값에 끝 공백이 없는지 확인하세요

​
Claude Desktop 연결 실패

  1. 설정이 Claude Desktop setup과 맞는지 확인하세요
  2. JSON 문법을 검증하세요 — 누락된 쉼표, 안 맞는 괄호, 누락된 따옴표 확인(JSONLint)
  3. Node.js가 설치돼 있는지 확인하세요(터미널에서 npx가 동작해야 함)
  4. Claude Desktop을 완전히 종료 후 재시작하세요(macOS는 Cmd+Q, 창만 닫지 말고)

​
Cursor 연결 실패

  1. Cursor 설정에서 MCP 서버 설정을 확인하세요
  2. 서버 URL이 https://mcp.tiro.ooo/mcp인지 확인하세요
  3. API Key를 쓴다면 설정에 올바르게 들어갔는지 확인하세요(따옴표·공백 없이)
  4. Cursor를 완전히 재시작하고 MCP 패널에서 연결 상태를 확인하세요

​
VS Code 연결 실패

  1. MCP extension 설정을 확인하세요(예: Continue 설정 또는 Copilot MCP config)
  2. 서버 URL이 https://mcp.tiro.ooo/mcp인지 확인하세요
  3. API Key를 쓴다면 올바른 config 필드에 들어갔는지 확인하세요
  4. VS Code 창을 리로드하고(Cmd+Shift+P → “Reload Window”) extension 로그에서 에러를 확인하세요

​
검색 & 데이터 문제

  • 결과가 없나요? 더 넓은 검색 조건을 써보세요 — content에 일반 키워드 하나만 쓰거나 createdAt 날짜 범위를 넓히세요
  • 날짜 형식 에러? timezone 포함 ISO 8601을 쓰세요: 2025-11-22T00:00:00Z (날짜만 있는 형식은 안 돼요)
  • 최근 노트가 안 보이나요? 캐싱 때문에 노트가 나타나기까지 최대 15분 걸릴 수 있어요. Tiro Dashboard에서 노트가 “Completed”인지 확인하세요
  • 요청 timeout? 긴 회의에는 get_note_transcript 대신 get_note(include: ['summary'])를 쓰세요

​
에러 레퍼런스

잘못된 파라미터(예: 날짜 형식, 빈 keyword)는 위 커스텀 코드가 아니라 MCP 표준 validation 에러로 거부돼요 — 도구 입력 스키마가 zod로 검증되기 때문이에요.

​
도움 받기

GitHub에 이슈를 열거나 support@tiro.ooo로 메일 주세요.