ainote

테마

OpenAI Custom GPT — OpenAPI 3.1 Actions ​

ainote 는 MCP tool 정의를 OpenAPI 3.1 spec 으로 mirror 한다. ChatGPT Plus / Team / Enterprise 의 Custom GPT Actions 가 이걸 그대로 import 한다 — hand-written translation 0줄.

5분 설정 ​

1. Custom GPT 생성 ​

ChatGPT → 좌상단 ⊕ New chat 옆 메뉴 → Explore GPTs → + Create

또는 직접: https://chat.openai.com/gpts/editor

2. Configure 탭 → Actions 섹션 → "Create new action" ​

3. Schema → "Import from URL" ​

URL 입력:

https://api.ainote.dev/api/mcp/openapi.json

ChatGPT 가 spec 을 파싱하고 26개 도구를 자동으로 인식한다. paths 마다 하나의 action operation 으로 등록됨.

4. Authentication 설정 ​

  • Auth Type: API Key
  • Auth Type (sub): Custom
  • Custom Header Name: Authorization
  • API Key value: McpKey <YOUR_MCP_KEY>

⚠️ McpKey 접두사 + 공백 포함. Bearer 아님.

5. Privacy Policy URL ​

https://docs.ainote.dev/legal/privacy

Verified Domain

공개 GPT Store 등록 시 OpenAI 는 api.ainote.dev hostname 의 root domain (ainote.dev) 인증 요구. 좌측 Settings → Verify your domain → DNS TXT 인증 진행. 비공개 / 개인 사용은 인증 불필요.

6. GPT 기본 정보 ​

  • Name: ainote — Multi-device Notes & Handoffs
  • Description: Agent-native notes & tasks with multi-device sync. 26 MCP-grade tools.
  • Instructions:
    You are an assistant connected to the user's ainote account. Use the ainote
Actions for tasks, dev-docs, handoffs, vault sync, and file management. Each
action's annotations (x-mcp-annotations) tell you whether the operation is
read-only, destructive, idempotent, or open-world — gate destructive calls
with explicit user confirmation.
  • Conversation starters:
    • "Save a handoff for the work I just finished"
    • "What tasks are due today?"
    • "Pull my dev-docs to this machine"
    • "List my recent handoffs"

7. Save → Publish ​

  • Only me: 즉시 사용 가능 (verified domain 불필요)
  • Anyone with a link: 링크 공유. verified domain 권장
  • Public (GPT Store): verified domain 필수

사용 시 주의 — 공유 시 키 정책 ​

Custom GPT 는 사용자별 자체 인증 모드를 지원한다. 다른 사용자가 너의 GPT 를 쓰려면 본인 ainote MCP key 입력 필요. Auth 설정 시 User-provided API key 옵션을 선택하면 사용자가 처음 호출 시 키를 직접 입력하는 UI 가 나온다.

Tool annotations 활용 ​

OpenAPI mirror 는 MCP annotations 를 x-mcp-annotations extension 으로 노출:

json
{
  "paths": {
    "/api/mcp/tools/delete_task": {
      "post": {
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": true,
          "idempotentHint": true,
          "openWorldHint": false
        }
      }
    }
  }
}

ChatGPT 가 이 extension 을 직접 읽지는 않지만 (현재 OpenAI spec 기준), Instructions 에서 ChatGPT 에게 "destructive 도구는 사용자 동의 후 호출" 라고 명시하면 GPT 가 spec 의 description 과 함께 판단 가능.

자주 묻는 문제 ​

"Import 시 'Could not parse OpenAPI'" — https://api.ainote.dev/api/mcp/openapi.json 가 200 OK 인지 먼저 확인. cold start 시 timeout 가능 — 한 번 새로고침.

"401 Unauthorized" — Authentication 의 McpKey 접두사 + 공백 확인. 또는 key 만료 / revoke 됐는지 app.ainote.dev → Settings → MCP keys 확인.

"Action returned empty result" — 실제 도구 호출 결과는 200 응답 본문. ChatGPT 가 응답을 어떻게 인용할지는 spec 의 response schema 와 GPT instructions 에 달림.

OpenAI 외 다른 OpenAPI 진영 ​

같은 spec 으로 동작:

→ 전체 도구 매트릭스