개발자 · API 키
TypeHop API 키 레퍼런스
API 키를 사용하면 AI 앱이나 직접 작성한 코드가 어느 기기에서든 TypeHop 계정에 동기화된 받아쓰기를 읽을 수 있습니다. 키는 읽기 전용이라 받아쓰기와 사용자 지정 단어를 검색하고 읽을 수만 있으며, 무엇도 변경하거나 삭제할 수 없습니다. 접근은 하나의 원격 MCP 엔드포인트를 통해 이루어지므로 Claude Code, Cursor, Codex 같은 앱을 한 줄 설정으로 사용할 수 있습니다.
키 만들기
- TypeHop Mac 앱을 열고 Integrations → API keys로 이동하세요.
- Press Create API key를 누르고 키를 사용할 앱이나 기기의 이름을 붙이세요. 예: “내 노트북의 Cursor”.
- 키는 바로 복사하세요. TypeHop은 해시만 저장하므로 전체 키는 한 번만 표시됩니다. 잃어버렸다면 새 키를 만들고 이전 키를 폐기하세요.
키는 thp_mcp_로 시작합니다. 앱의 목록에는 각 키의 첫 글자, 생성 시점, 마지막 사용 시점이 표시됩니다. 키를 폐기하면 해당 키를 사용하는 모든 앱이 즉시 중단됩니다.
인증
모든 요청에 키를 Bearer 토큰으로 보내세요. OAuth 흐름이나 열어야 할 세션은 없습니다.
- 엔드포인트
https://api.typehop.com/v1/mcp- 메서드
POST만 지원합니다.GET과DELETE는 405를 반환합니다.- 헤더
Authorization: Bearer thp_mcp_YOUR_KEY- 본문
- JSON-RPC 2.0,
Content-Type: application/json
키가 없거나 폐기된 경우
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="typehop-mcp"
{ "jsonrpc": "2.0", "id": null, "error": { "code": -32001, "message": "This token is invalid or was revoked." } }AI 앱 연결
대부분의 사용자는 엔드포인트를 직접 호출하지 않습니다. Mac 앱의 Connect an app 아래에 Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI, Zed, Claude Desktop의 정확한 설정 방법이 새 키가 이미 채워진 상태로 표시됩니다. 같은 스니펫은 MCP 페이지에도 있습니다. 예를 들어 Claude Code는 다음과 같습니다.
claude mcp add --transport http typehop https://api.typehop.com/v1/mcp --header "Authorization: Bearer thp_mcp_YOUR_KEY"
Streamable HTTP 방식의 원격 MCP 서버를 지원하는 다른 클라이언트도 엔드포인트 URL과 위의 헤더로 사용할 수 있습니다. Claude.ai와 ChatGPT의 사용자 지정 커넥터는 OAuth가 필요한데, TypeHop은 아직 지원하지 않습니다.
코드에서 호출하기
엔드포인트는 Model Context Protocol을 사용합니다. POST로 JSON-RPC 2.0 메시지를 보내면 JSON 응답이 하나 돌아옵니다. 상태를 저장하지 않으므로 세션 헤더나 서버 전송 이벤트가 없습니다. 지원하는 프로토콜 버전은 다음과 같습니다. 2025-06-18, 2025-03-26, 2024-11-05.
1. 초기화 (선택 사항이지만 MCP 클라이언트는 수행합니다)
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0.0"}}}'2. 도구 목록 조회
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'3. 도구 호출
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_dictations","arguments":{"query":"launch plan","limit":5}}}'응답 · 200
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "[2026-11-03T09:14:22.000Z · Slack · id 3f6c1a2e-8b1d-4c55-9a0e-6b2f7d1e4c90]\nThe launch plan moves to next Tuesday..."
}
],
"isError": false
}
}결과에 포함된 각 받아쓰기는 [created at · app · id <id>] 형태의 헤더 줄로 시작하고, 그 뒤에 정리된 텍스트가 이어집니다. 원본 전사본이 필요하면 해당 id를 get_dictation에 전달하세요. 한 요청에 최대 20개의 메시지를 배열로 보낼 수도 있으며, 알림(id가 없는 메시지)에는 본문 없이 202가 반환됩니다. ping도 지원합니다.
도구
모든 도구는 읽기 전용이며 result.content[0].text에 일반 텍스트를 반환합니다.
search_dictations · 받아쓰기 검색
사용자가 받아쓴 모든 내용에 대한 전체 텍스트 검색입니다. 최신 일치 항목부터 반환합니다.
query(string, 필수): 찾을 단어 또는 문구.limit(integer 1–50, 기본값 20)
recent_dictations · 최근 받아쓰기
사용자의 최근 받아쓰기이며, 선택적으로 최근 며칠 동안의 항목만 가져올 수 있습니다.
limit(integer 1–50, 기본값 20)days(integer 1–365): 최근 N일 이내의 받아쓰기만.
get_dictation · 받아쓰기 하나 가져오기
id로 받아쓰기 하나를 가져옵니다. 정리된 텍스트와 원본 전사본을 반환합니다.
id(string, 필수): 검색 또는 최근 결과에 표시된 id.
list_dictionary · 사용자 지정 단어
사용자의 사용자 지정 단어와 철자(이름, 전문 용어)입니다.
인수 없음.
도구가 답할 수 없는 경우(빈 쿼리, 알 수 없는 id, 일시적인 읽기 실패)에도 응답은 200 결과로 반환되며, isError: true와 모델이 읽을 수 있는 문장이 포함됩니다.
오류
프로토콜 오류는 JSON-RPC error 객체로 반환됩니다. { "code": <number>, "message": "<text>" }.
401 · -32001Authorization 헤더가 없거나 키가 유효하지 않거나 폐기되었습니다.400 · -32700본문이 올바른 JSON이 아닙니다.413 · -32600본문이 256 KB보다 큽니다.200 · -32600메시지가 JSON-RPC 2.0이 아닙니다("jsonrpc": "2.0" 또는 "method"가 없음).200 · -32601알 수 없는 메서드입니다.200 · -32602tools/call이 존재하지 않는 도구를 지정했습니다.500 · -32603서버 오류입니다. 백오프를 적용해 다시 시도하세요.
제한 사항 및 보안
- 활성 키
- 계정당 최대 10개. 새로 만들려면 기존 키 하나를 폐기하세요.
- 요청 크기
- 요청당 256 KB, 배치당 최대 20개 메시지.
- 결과
- 호출당 최대 50개의 받아쓰기.
recent_dictations는 최대 365일 전까지 조회합니다. - 범위
- 계정에 동기화된 받아쓰기와 사용자 지정 단어입니다. 아무것도 기록되지 않습니다.
- 앱이나 기기마다 키를 하나씩 사용하면 다른 키에 영향을 주지 않고 하나만 폐기할 수 있습니다.
- 키는 내 컴퓨터나 백엔드에만 보관하세요. 브라우저 코드, 모바일 앱 번들, 공개 저장소에는 절대 넣지 마세요.
- 키가 유출되었다면 Integrations → API keys에서 폐기하세요. 다음 요청부터 작동하지 않습니다.
문의: support@typehop.com. 개요가 필요하신가요? TypeHop API를 참고하세요.