에이전트 가이드

ainote 는 MCP (JSON-RPC) 와 OpenAPI 3.1 (REST-style) 두 surface 를 동시에 노출한다. 같은 26개 도구가 두 프로토콜에서 동일하게 동작한다.

어느 가이드를 봐야 하나

진영	추천 protocol	가이드
Claude Code	MCP HTTP	Claude Code
Claude Desktop	MCP stdio (npm)	Claude Desktop
Cursor IDE	MCP stdio 또는 HTTP	Cursor
Windsurf IDE	MCP stdio	Windsurf
ChatGPT (Plus/Team/Enterprise)	OpenAPI Custom GPT Action	OpenAI Custom GPT
LangChain / LangGraph	OpenAPI remote tool	LangChain
AutoGen / CrewAI	OpenAPI remote tool	LangChain

공통 — 한 번만 받으면 되는 것

모든 진영은 MCP key 만 필요하다. 발급 방법:

1. Claude 안에서 (가장 쉬움) — MCP 등록 후 "ainote 가입시켜줘 — 이메일 X / 비번 Y" 한 줄
2. CLI — npx @ainote/mcp signup (브라우저 RFC 8628 device flow)
3. 웹 — app.ainote.dev → Settings → Generate MCP key

발급된 key 는 OS Keychain (Claude Desktop / Code) 또는 환경변수 (LangChain / AutoGen) 또는 Custom GPT Action header value (ChatGPT) 에 넣는다.

두 protocol 비교

항목	MCP JSON-RPC	OpenAPI 3.1
엔드포인트	https://api.ainote.dev/api/mcp	https://api.ainote.dev/api/mcp/openapi.json (spec) + /api/mcp/tools/{name} (호출)
호출 형식	{jsonrpc:"2.0", method:"tools/call", params:{name, arguments}}	POST /api/mcp/tools/{name} body = arguments
인증	Authorization: McpKey <KEY>	동일
도구 발견	tools/list	GET /api/mcp/openapi.json
추천 진영	Anthropic 생태계	OpenAI / LangChain / 기타 HTTP-first
Tool annotations	wire 응답 annotations 필드	x-mcp-annotations extension

같은 26 도구. 같은 백엔드. 같은 결과. 진영만 다르다.

→ Dual-protocol 게이트웨이 코드 상세

Multi-platform — 네이티브 앱들

에이전트가 아닌 네이티브 surface 들도 같은 vault 를 본다:

• iOS / Android — Flutter 앱, App Store / Play Store
• macOS — 네이티브 Swift 앱
• Apple Watch — 빠른 태스크 추가
• Chrome / Safari 확장 — 웹 페이지 클립
• Telegram — 봇 인터페이스

전부 동일한 사용자 계정 + vault 를 공유. 한 디바이스에서 변경하면 다른 디바이스가 본다.