메인 콘텐츠로 건너뛰기
MCP 설정 문제는 대부분 세 가지로 나뉘어요: auth 헤더, transport, 클라이언트 캐시. 순서대로 짚어보세요. 단계 사이에 클라이언트를 재시작해야 설정을 다시 읽어요.

​
연결 문제

​
서버를 찾을 수 없음

MCP 서버 URL이 맞는지 확인하세요: https://mcp.tiro.ooo/mcp 자주 하는 실수:
  • /mcp 경로 suffix 누락
  • https:// 대신 http:// 사용
연결 테스트: 
curl https://mcp.tiro.ooo/mcp
예상 응답: 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 값 사용
# Correct format
TIRO_API_KEY=abc123.xyz789secretvalue

# Wrong — missing the dot separator
TIRO_API_KEY=abc123xyz789secretvalue
만료되거나 폐기된 Key API Key는 Tiro Dashboard에서 만료되거나 폐기될 수 있어요. 이전에 쓰던 API key로 401 UNAUTHORIZED 에러가 나면:
  1. Tiro Platform API Keys로 가세요
  2. key가 아직 활성인지 확인하고, 필요하면 새로 발급하세요
  3. MCP 클라이언트 설정을 새 key로 업데이트하세요
잘못된 Key 종류(User vs Team) 일부 도구는 특정 key 종류가 필요해요:
  • User API Key — 개인 계정에 연결됨, 사용자별 도구(예: user folders)에 필요
  • Team API Key — 팀에 연결됨, 팀별 도구(예: team folders)에 필요
도구가 USER_REQUIRED나 TEAM_REQUIRED를 반환하면, 작업에 맞는 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일 동안 유효해요.

​
설정 문제

​
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'])를 쓰세요

​
에러 레퍼런스

CodeHTTP설명해결
UNAUTHORIZED401유효한 인증 없음API key 확인 또는 클라이언트 재시작해 OAuth 재인증
TOKEN_EXPIRED401token 만료됨새 API key 발급 또는 클라이언트 재시작해 OAuth 재인증
FORBIDDEN403필요한 scope 없음API key scope 확인 또는 클라이언트 재시작해 OAuth 재인증
INSUFFICIENT_SCOPE403인증된 key/token에 이 도구에 필요한 scope가 없음Setup 페이지의 scope 표를 확인하고 올바른 scope의 key를 쓰세요
USER_REQUIRED403도구가 user 기반 API key를 요구하는데 team 전용 key가 제공됨이 작업엔 user API key로 전환
TEAM_REQUIRED403도구가 team API key를 요구하는데 user 전용 key가 제공됨team API key로 전환
MISSING_PARAMETERS400필수 param 누락param 요건 확인
INVALID_NOTE_ID400잘못된 note ID양의 정수 사용
INVALID_DATE_FORMAT400잘못된 날짜 형식ISO 8601 datetime 사용
NOTE_NOT_FOUND404노트가 없음note ID 확인
INTERNAL_SERVER_ERROR500서버 에러재시도 또는 지원 문의
REQUEST_TIMEOUT504요청 timeoutsummary 사용 또는 재시도

​
도움 받기

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