문서
소유한 API에서 운영 중인 MCP 서버까지, 단계별로.
빠른 시작
아래 과정은 모두 웹 콘솔에서 이루어집니다. 가입 후 "새 프로젝트"를 클릭하고 세 단계를 따르세요. API 키는 필요 없습니다.
-
API 가져오기
OpenAPI 스펙 URL, curl 명령, 또는 Postman 컬렉션을 가져오면 Invokera가 타입이 지정된 MCP 도구로 변환합니다.
-
도메인 소유권 확인
DNS TXT 레코드 또는 well-known 파일로 API 도메인을 소유하고 있음을 증명하세요.
-
게시
게시되면 프로젝트에 MCP 엔드포인트, REST 엔드포인트, AI가 읽을 수 있는 랜딩 페이지가 제공됩니다.
성공하면 이런 모습입니다
실제 프로젝트의 네 가지 순간입니다. 제대로 가고 있는지 대조해 보세요. 완성된 결과를 직접 보기: 데모 프로젝트 Invokera Status.
세 가지 가져오기 방법
OpenAPI (URL)
공개 OpenAPI/Swagger 스펙 URL을 콘솔의 OpenAPI 탭에 붙여넣으세요. 가장 빠르고 완전한 방법입니다.
curl
동작하는 curl 명령을 콘솔의 curl 탭에 붙여넣으면 Invokera가 이를 바탕으로 타입이 지정된 도구를 만들어냅니다. 예:
curl https://api.example.com/v1/users -H "Authorization: Bearer KEY"Postman
Postman에서 컬렉션을 Collection v2.1 JSON으로 내보낸 다음, 그 JSON을 콘솔의 Postman 탭에 붙여넣으세요.
도메인 인증 문제 해결
인증은 _invokera-challenge.<내-도메인> 의 TXT 레코드(또는 /.well-known/invokera-challenge.txt 파일)를 확인합니다. 챌린지는 72시간 동안 유효하며 최대 30회까지 확인할 수 있습니다. 흔한 실패 원인:
| 증상 | 예상 원인 | 해결 방법 |
|---|---|---|
| 레코드를 추가했는데도 "TXT record not found"가 표시됨 | 대부분의 DNS 패널(Cloudflare, Aliyun, Tencent Cloud, GoDaddy)은 레코드 이름에 도메인을 자동으로 붙입니다. 전체 이름을 입력하면 _invokera-challenge.example.com.example.com 이 됩니다. | 레코드 이름/호스트에는 _invokera-challenge 만 입력하세요. 패널이 명시적으로 FQDN을 요구할 때만 전체 이름을 사용합니다. |
| 토큰이 맞는데도 값 불일치가 표시됨 | 값에 불필요한 따옴표나 공백이 들어갔습니다. 일부 패널은 붙여넣은 따옴표를 값의 일부로 저장합니다. | 따옴표와 공백 없이 토큰만 붙여넣으세요. 필요한 따옴표는 패널이 자동으로 추가합니다. |
| 레코드를 추가했지만 인증이 계속 실패함 | DNS 변경 사항이 전파되기까지 몇 분(때로는 그 이상)이 걸립니다. | 몇 분 기다린 뒤 다시 시도하세요. nslookup -type=TXT _invokera-challenge.<내-도메인> 으로 확인할 수 있습니다. |
| api.example.com 같은 서브도메인에 레코드를 추가함 | 인증 대상은 등록 가능 도메인(eTLD+1), 예: example.com 이며 서브도메인이 아닙니다. | TXT를 _invokera-challenge.example.com 에 만드세요. 호스팅 플랫폼의 공유 서브도메인에서는 .well-known 파일 방식을 사용하세요. |
| "Challenge expired" 또는 "too many attempts" 표시 | 각 챌린지는 72시간 동안 유효하며 최대 30회 확인이 허용됩니다. | 프로젝트 페이지에서 새 챌린지를 시작하고 DNS 레코드(또는 파일)를 새 토큰으로 업데이트하세요. |
MCP로 연결
Claude Code
가장 빠른 연결 방법 — 터미널에서 명령 하나만 실행하세요:
claude mcp add --transport http your-project https://invokera.com/r/your-project --header "Authorization: Bearer inv_YOUR_TOKEN"성공 확인: 채팅에서 질문을 하나 해 보세요. 도구 이름이 보이면 연결된 것입니다.
Claude Desktop
streamable HTTP 엔드포인트와 엔드포인트 토큰을 사용해 claude_desktop_config.json에 프로젝트를 추가하세요:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"your-project": {
"type": "http",
"url": "https://invokera.com/r/your-project",
"headers": { "Authorization": "Bearer inv_YOUR_TOKEN" }
}
}
}사용 중인 OS의 파일을 수정한 뒤 Claude Desktop을 재시작해야 변경이 적용됩니다.
성공 확인: 채팅에서 질문을 하나 해 보세요. 도구 이름이 보이면 연결된 것입니다.
Cursor
프로젝트 루트에 같은 JSON 형태로 .cursor/mcp.json을 만드세요:
{
"mcpServers": {
"your-project": {
"type": "http",
"url": "https://invokera.com/r/your-project",
"headers": { "Authorization": "Bearer inv_YOUR_TOKEN" }
}
}
}성공 확인: 채팅에서 질문을 하나 해 보세요. 도구 이름이 보이면 연결된 것입니다.
REST
MCP 클라이언트가 없나요? 모든 프로젝트는 자기 기술적인 REST 엔드포인트도 제공합니다:
curl https://invokera.com/v1/your-project/tools -H "Authorization: Bearer inv_YOUR_TOKEN"자동화 / CI
스크립트로 프로젝트를 관리하기 위한 플랫폼 API 키(ik_)는 아직 셀프서비스로 발급되지 않습니다. 자동화나 CI 연동이 필요하면 문의해 주세요. 계정에 키를 활성화해 드립니다. 호출 형태는 다음과 같습니다:
curl -X POST https://invokera.com/api/v1/projects -H "Authorization: Bearer ik_YOUR_API_KEY" -H "Content-Type: application/json" -d '{"specUrl":"https://api.example.com/openapi.json"}'FAQ
호출이 오류 코드와 함께 실패합니다. 무슨 의미인가요?
MCP 오류는 JSON-RPC 코드와 HTTP 상태를 함께 담고 있습니다. 자주 나오는 것들:
| 코드 | 의미 | 해결 |
|---|---|---|
-32001 (HTTP 404) |
이 slug에 MCP 엔드포인트가 없습니다. 프로젝트가 없거나 URL 오타입니다. | 프로젝트 페이지와 엔드포인트 URL을 대조하세요. slug는 정확히 일치해야 합니다. |
-32002 (HTTP 401) |
Bearer 토큰이 없거나 유효하지 않습니다. | Authorization: Bearer inv_… 형식으로 프로젝트 토큰을 보내세요. 확실하지 않으면 콘솔에서 다시 복사하세요. |
-32005 (HTTP 403) |
프로젝트가 아직 게시되지 않았습니다. 초안은 유효한 토큰이 있어도 호출할 수 없습니다. | 먼저 도메인 소유권을 인증하고 프로젝트를 게시하세요. |
-32004 (HTTP 409) |
활성화된 도구가 없습니다. | 콘솔에서 도구를 하나 이상 활성화한 뒤 다시 시도하세요. |
-32003 (HTTP 403) |
이 도구 세트는 플랫폼에 의해 정지되었습니다. | 오류라고 생각되면 지원팀에 문의하세요. |
도메인 확인이 계속 실패합니다 — 무엇을 점검해야 하나요?
DNS TXT 레코드는 전파에 시간이 걸릴 수 있습니다 — 몇 분 기다린 후 다시 확인해 주세요. 확인 대상은 서브도메인이 아니라 등록 가능한 도메인(eTLD+1)입니다. API가 호스팅 플랫폼의 서브도메인에 있다면 .well-known 파일 방식을 사용하세요.
inv_ 토큰과 ik_ 토큰의 차이는 무엇인가요?
inv_ 엔드포인트 토큰은 게시된 도구 호출만 허용합니다. ik_ 플랫폼 API 키는 계정과 프로젝트를 관리합니다 — 절대 에이전트에게 넘기지 마세요.
엔드포인트 토큰은 어떻게 교체하나요?
콘솔에서 프로젝트를 열고 '토큰 교체'를 사용하세요. 이전 토큰은 즉시 사용할 수 없게 되므로, 바로 에이전트 설정을 업데이트해 주세요.
호출 토큰을 잃어버렸습니다. 어떻게 되찾나요?
토큰은 다시 표시되지 않습니다. 프로젝트 페이지에서 "토큰 회전"을 사용하면 즉시 새 토큰이 발급되고 기존 토큰은 무효화됩니다. 기존 토큰을 쓰던 모든 클라이언트를 업데이트하세요.
Claude는 연결됐는데 도구가 보이지 않습니다. 왜 그런가요?
보통 세 가지 중 하나입니다: 프로젝트에 활성화된 도구가 없음(콘솔에서 활성화); 설정 변경 후 클라이언트를 완전히 재시작하지 않음(Claude Desktop은 완전히 종료 후 재실행 필요); 엔드포인트 URL이나 토큰 오기입 — 콘솔의 테스트 호출로 서버 쪽 문제를 먼저 배제하세요.