MCP

같은 API를 시나리오가 아니라 어시스턴트에게 건넨 것입니다. MCP 클라이언트는 실행 중에 도구 설명을 보고 무엇을 호출할지 고르므로, 닿는 범위는 그 뒤의 자격 증명이 닿는 범위와 정확히 같고, 모든 도구 아래에는 공개 API 호출이 있습니다.

엔드포인트는 하나

모두 POST /v1/mcp 로 갑니다. 열 세션도, 붙잡을 스트림도 없습니다. GET 과 DELETE 는 405 를 돌려주고, 각 메시지가 곧 하나의 요청입니다.

POST https://api.mosaqo.app/v1/mcp
Authorization: Bearer $MOSAQO_KEY
MCP-Protocol-Version: 2026-07-28

2025-03-26 부터 2026-07-28 까지의 프로토콜 개정을 모두 처리합니다. initialize 로 시작하는 클라이언트는 기대하는 핸드셰이크를 받고, 요청마다 버전을 밝히는 클라이언트는 그 방식으로 처리됩니다.

API 키로 연결하기

가장 빠른 길이며, 직접 운영하는 도구에는 이 방법이 맞습니다. 어떤 키든 bearer 토큰으로 작동하고, 제시되는 도구는 그 키의 스코프로 잘립니다.

대부분의 클라이언트는 이런 블록을 받습니다:

{
  "mcpServers": {
    "mosaqo": {
      "type": "http",
      "url": "https://api.mosaqo.app/v1/mcp",
      "headers": { "Authorization": "Bearer $MOSAQO_KEY" }
    }
  }
}

curl -X POST https://api.mosaqo.app/v1/mcp \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

OAuth 로 연결하기

사람이 키를 전혀 만지지 않는, 남의 디렉터리에 있는 커넥터를 위한 방식입니다. 디스커버리는 RFC 9728 와 RFC 8414 를 따르고, 클라이언트는 RFC 7591 로 스스로 등록하며, 모든 인가는 S256 의 PKCE 를 씁니다.

curl https://api.mosaqo.app/.well-known/oauth-protected-resource
curl https://api.mosaqo.app/.well-known/oauth-authorization-server

인가되지 않은 호출은 어디로 가서 무엇을 요청할지 스스로 알려줍니다:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Mosaqo MCP",
  resource_metadata="https://api.mosaqo.app/.well-known/oauth-protected-resource",
  scope="qr:read analytics:read reviews:read exports:read"

승인하는 사람은 Mosaqo 에 로그인한 상태로, 어느 워크스페이스에 적용할지 고르며, 자신이 소유자나 관리자인 곳에서만 그렇게 할 수 있습니다 — API 키를 발급할 수 있는 사람을 정하는 것과 같은 선입니다. 이후 Bulk & API 에서 연결을 해제할 수 있습니다.

어시스턴트가 할 수 있는 일

이미 아는 스코프 그대로입니다. 자격 증명이 허용하지 않는 도구는 tools/list 에 실리지 않고 이름을 대도 호출되지 않습니다 — 어떤 연결이든 살아 있는 답은 tools/list 그 자체입니다.

스코프	허용되는 작업
`qr:read`	QR 코드, 폴더, 템플릿 목록 조회 및 읽기
`qr:write`	생성, 수정, 연결 대상 변경, 게시, 보관, 삭제
`exports:read`	렌더링된 카드 다운로드
`analytics:read`	집계 분석과 개별 스캔
`bulk:write`	일괄 작업 생성 및 조회
`webhooks:write`	웹훅 구독 관리
`reviews:read`	장소, 설문과 진행 상황 — 답변 자체는 제외

결코 닿지 못하는 것

사람들이 설문에 쓴 내용. reviews:read 는 장소, 설문과 진행 상황을 엽니다 — 건수, 점수, 문항별 분포입니다. 방문자가 입력한 문장은 여기서도, 자격 증명이 닿는 어디에서도 반환되지 않습니다. feedback.* 이벤트가 점수는 실어도 말은 결코 싣지 않는 것과 같은 이유입니다.

코드 삭제. REST 경로는 입력된 확인을 요구합니다. 인쇄된 코드 뒤의 리디렉션을 없애는 것은 되돌릴 수 없고, 그것은 어시스턴트가 누군가를 대신해 주는 확인이 아니기 때문입니다. 대신 보관이 제공되며, 보관은 되돌릴 수 있습니다.

쓰기는 쓰기로 표시됩니다. 무언가를 바꾸는 도구는 readOnlyHint: false 를, 보관은 destructiveHint: true 를 지닙니다 — 클라이언트가 실행 전에 멈춰 사람에게 묻게 만드는 것이 바로 이것입니다.