MCP 서버 레퍼런스

EmDash는 /_emdash/api/mcp에 내장 Model Context Protocol(MCP) 서버를 포함하여 콘텐츠 관리 작업을 AI 어시스턴트의 도구로 노출합니다.

이 페이지는 프로토콜 세부사항을 다룹니다: 인증, 전송, 도구 사양, OAuth 디스커버리, 오류 처리.

인증

MCP 서버는 세 가지 인증 방법을 지원합니다:

방법	작동 방식
OAuth 2.1 Authorization Code + PKCE	MCP 클라이언트를 위한 표준 플로우. 사용자가 브라우저에서 스코프를 승인합니다.
Personal Access Token (PAT)	관리 패널에서 생성된 장기 유효 `ec_pat_*` 토큰.
Device Flow	브라우저에서 코드를 승인하는 CLI 스타일 플로우. `emdash login`에서 사용됩니다.

스코프

스코프	접근 권한
`content:read`	콘텐츠 목록, 조회, 비교, 검색. 택소노미, 용어 및 메뉴 목록.
`content:write`	콘텐츠 생성, 수정, 삭제, 발행, 발행 취소, 예약, 예약 해제, 복제, 복원. `taxonomies:manage`와 `menus:manage`를 암묵적으로 부여.
`media:read`	미디어 항목 목록 및 조회.
`media:write`	미디어 메타데이터 등록(생성), 수정, 삭제.
`schema:read`	컬렉션 목록 및 스키마 조회.
`schema:write`	컬렉션 및 필드 생성/삭제.
`taxonomies:manage`	택소노미 용어 생성, 수정, 삭제.
`menus:manage`	내비게이션 메뉴 및 항목 생성, 수정, 삭제.
`settings:read`	사이트 설정 읽기.
`settings:manage`	사이트 설정 업데이트.
`mcp:tools`	모든 플러그인의 명시적으로 활성화된 MCP 도구 호출.
`mcp:tools:<pluginId>`	특정 플러그인의 명시적으로 활성화된 MCP 도구 호출.
`admin`	모든 작업에 대한 전체 접근.

역할 요구사항

작업	최소 역할
콘텐츠 읽기	Subscriber(10) 발행된 항목; Contributor(20) 초안, 예약, 휴지통, 리비전
콘텐츠 생성	Contributor(20)
자신의 편집/삭제	Author(30)
콘텐츠 발행	Author(30) 자신의 것; Editor(40) 타인의 것
스키마 읽기	Editor(40)
스키마 쓰기	Admin(50)
택소노미 관리	Editor(40)
메뉴 관리	Editor(40)
설정 읽기	Editor(40)
설정 관리	Admin(50)
미디어 업로드(`media_upload`)	Contributor(20)
미디어 등록(`media_create`)	Author(30)
미디어 사용 복구	Admin(50)

인증 가이드에서 역할 정의를 참조하세요.

전송

서버는 무상태 모드로 Streamable HTTP 전송을 사용합니다. 각 요청은 독립적입니다.

POST /_emdash/api/mcp — JSON-RPC 도구 호출 전송
GET /_emdash/api/mcp — 405 반환
DELETE /_emdash/api/mcp — 405 반환

도구

서버는 8개 도메인에 걸쳐 도구를 노출합니다: 콘텐츠, 스키마, 미디어, 검색, 택소노미, 메뉴, 리비전, 설정.

콘텐츠 도구

`content_list`

컬렉션의 콘텐츠 항목을 필터링 및 페이지네이션과 함께 목록 표시.

파라미터	타입	필수	설명
`collection`	`string`	예	컬렉션 슬러그
`status`	`string`	아니오	필터: `draft`, `published`, `scheduled`
`limit`	`integer`	아니오	최대 항목 수(1-100, 기본 50)
`cursor`	`string`	아니오	페이지네이션 커서
`orderBy`	`string`	아니오	정렬 필드
`order`	`string`	아니오	정렬 방향: `asc` 또는 `desc`
`locale`	`string`	아니오	로케일로 필터

스코프: content:read | 읽기 전용: 예

`content_get`

ID 또는 슬러그로 단일 콘텐츠 항목을 조회.

스코프: content:read | 읽기 전용: 예

`content_create`

새 콘텐츠 항목을 생성.

스코프: content:write

`content_update`

기존 콘텐츠 항목을 업데이트. 변경할 필드만 포함합니다.

스코프: content:write

`content_delete`

콘텐츠 항목을 휴지통으로 이동하여 소프트 삭제.

스코프: content:write | 파괴적: 예

`content_restore`

휴지통에서 콘텐츠 항목을 복원.

스코프: content:write

`content_permanent_delete`

휴지통의 항목을 영구적이고 되돌릴 수 없게 삭제.

스코프: content:write | 파괴적: 예

`content_publish`

콘텐츠 항목을 발행하여 사이트에서 라이브로 만듭니다.

스코프: content:write

`content_unpublish`

발행된 항목을 초안 상태로 되돌립니다.

스코프: content:write

`content_schedule`

향후 발행을 위해 콘텐츠 항목을 예약.

스코프: content:write

`content_unschedule`

예약된 발행을 취소.

스코프: content:write

`content_compare`

발행된 버전과 현재 초안을 비교.

스코프: content:read | 읽기 전용: 예

`content_discard_draft`

현재 초안을 폐기하고 마지막 발행 버전으로 되돌림.

스코프: content:write | 파괴적: 예

`content_list_trashed`

컬렉션 휴지통의 항목을 목록 표시.

스코프: content:read | 읽기 전용: 예

`content_duplicate`

기존 콘텐츠 항목의 사본을 생성.

스코프: content:write

`content_translations`

콘텐츠 항목의 모든 로케일 변형을 조회.

스코프: content:read | 읽기 전용: 예

스키마 도구

`schema_list_collections` / `schema_get_collection` / `schema_create_collection` / `schema_delete_collection` / `schema_create_field` / `schema_delete_field`

컬렉션과 필드를 목록 표시, 조회, 생성, 삭제하는 도구입니다.

필드 타입: string, text, number, integer, boolean, datetime, select, multiSelect, portableText, image, file, reference, json, slug.

미디어 도구

`media_list` / `media_upload` / `media_create` / `media_get` / `media_update` / `media_delete` / `media_usage_repair`

미디어 파일을 목록 표시, 업로드, 등록, 조회, 업데이트, 삭제 및 사용 인덱스 복구하는 도구입니다.

검색 도구

`search`

콘텐츠 컬렉션 전체의 전문 검색.

파라미터	타입	필수	설명
`query`	`string`	예	검색 쿼리 텍스트
`collections`	`string[]`	아니오	특정 컬렉션으로 제한
`locale`	`string`	아니오	로케일로 필터
`limit`	`integer`	아니오	최대 결과 수(1-50, 기본 20)

스코프: content:read | 읽기 전용: 예

택소노미 도구

`taxonomy_list` / `taxonomy_list_terms` / `taxonomy_create_term` / `taxonomy_update_term` / `taxonomy_delete_term`

택소노미 정의와 용어를 목록 표시, 생성, 업데이트, 삭제하는 도구입니다.

메뉴 도구

`menu_list` / `menu_get` / `menu_create` / `menu_update` / `menu_delete` / `menu_set_items`

내비게이션 메뉴를 목록 표시, 조회, 생성, 업데이트, 삭제하고 메뉴 항목을 설정하는 도구입니다.

리비전 도구

`revision_list` / `revision_restore`

콘텐츠 항목의 리비전 기록을 목록 표시하고 이전 리비전으로 복원하는 도구입니다.

설정 도구

`settings_get` / `settings_update`

사이트 설정을 조회하고 업데이트하는 도구입니다.

OAuth 디스커버리

보호된 리소스 메타데이터

GET /.well-known/oauth-protected-resource

{
  "resource": "https://example.com/_emdash/api/mcp",
  "authorization_servers": ["https://example.com/_emdash"],
  "scopes_supported": [
    "content:read", "content:write",
    "media:read", "media:write",
    "schema:read", "schema:write",
    "taxonomies:manage", "menus:manage",
    "settings:read", "settings:manage",
    "admin"
  ],
  "bearer_methods_supported": ["header"]
}

인증 서버 메타데이터

GET /.well-known/oauth-authorization-server/_emdash

{
  "issuer": "https://example.com/_emdash",
  "authorization_endpoint": "https://example.com/_emdash/oauth/authorize",
  "token_endpoint": "https://example.com/_emdash/api/oauth/token",
  "scopes_supported": ["content:read", "content:write", "..."],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "device_authorization_endpoint": "https://example.com/_emdash/api/oauth/device/code"
}

오류 처리

도구 오류는 isError: true가 포함된 텍스트 콘텐츠로 반환됩니다:

{
  "content": [{ "type": "text", "text": "[NOT_FOUND] Collection 'nonexistent' not found" }],
  "isError": true,
  "_meta": { "code": "NOT_FOUND" }
}

{
  "content": [
    { "type": "text", "text": "[INSUFFICIENT_SCOPE] Insufficient scope: requires content:write" }
  ],
  "isError": true,
  "_meta": { "code": "INSUFFICIENT_SCOPE" }
}

전송 수준 오류는 구현 세부사항을 노출하지 않고 JSON-RPC 오류 코드 -32603(내부 오류)을 반환합니다.

인증

스코프

역할 요구사항

전송

도구

콘텐츠 도구

content_list

content_get

content_create

content_update

content_delete

content_restore

content_permanent_delete

content_publish

content_unpublish

content_schedule

content_unschedule

content_compare

content_discard_draft

content_list_trashed

content_duplicate

content_translations

스키마 도구

schema_list_collections / schema_get_collection / schema_create_collection / schema_delete_collection / schema_create_field / schema_delete_field

미디어 도구

media_list / media_upload / media_create / media_get / media_update / media_delete / media_usage_repair

검색 도구

search

택소노미 도구

taxonomy_list / taxonomy_list_terms / taxonomy_create_term / taxonomy_update_term / taxonomy_delete_term

메뉴 도구

menu_list / menu_get / menu_create / menu_update / menu_delete / menu_set_items

리비전 도구

revision_list / revision_restore

설정 도구

settings_get / settings_update

OAuth 디스커버리

보호된 리소스 메타데이터

인증 서버 메타데이터

오류 처리

`content_list`

`content_get`

`content_create`

`content_update`

`content_delete`

`content_restore`

`content_permanent_delete`

`content_publish`

`content_unpublish`

`content_schedule`

`content_unschedule`

`content_compare`

`content_discard_draft`

`content_list_trashed`

`content_duplicate`

`content_translations`

`schema_list_collections` / `schema_get_collection` / `schema_create_collection` / `schema_delete_collection` / `schema_create_field` / `schema_delete_field`

`media_list` / `media_upload` / `media_create` / `media_get` / `media_update` / `media_delete` / `media_usage_repair`

`search`

`taxonomy_list` / `taxonomy_list_terms` / `taxonomy_create_term` / `taxonomy_update_term` / `taxonomy_delete_term`

`menu_list` / `menu_get` / `menu_create` / `menu_update` / `menu_delete` / `menu_set_items`

`revision_list` / `revision_restore`

`settings_get` / `settings_update`