MCP 서버

Setherion에는 MCP 서버가 있어요. AI 어시스턴트가 다른 서비스를 쓰는 표준 방식이에요. Claude, ChatGPT, Cursor, VS Code에서만 쓰고 싶다면 MCP: AI 어시스턴트 연결하기를 따라 하세요. 이 페이지는 나만의 클라이언트를 만들 때 보는 페이지예요.

이 서버는 같은 API를 다른 모습으로 내놓은 것이에요. 각 도구는 이 레퍼런스에 있는 같은 이름의 엔드포인트를 호출하는 것이고, 호출한 사람 본인의 자격 증명으로 실행되기 때문에 이 서버가 API보다 더 많은 일을 할 수는 없어요.

전송 방식

• Streamable HTTP, 무상태. 모든 메시지를 JSON-RPC 2.0 메시지 하나로 POST의 본문에 담아 보내세요. 세션이 없고 이어서 재개할 것도 없어요.
• 프로토콜 버전은 2025-06-18과 2025-03-26이에요. initialize는 요청한 버전이 이 둘 중 하나이면 그 버전으로, 아니면 2025-06-18로 응답해요. initialize 뒤에는 MCP-Protocol-Version 헤더에 버전을 담아 보내세요. 다른 값은 400으로 거부돼요.
• 도구만 제공해요. 이 서버는 리소스나 프롬프트를 제공하지 않고, 자체적으로 메시지를 보내지도 않아요.
• 요청마다 메시지 하나예요. 배치 요청은 400으로 거부돼요.
• GET과 DELETE 요청에는 405로 응답하고, Allow: POST를 함께 보내요.
• Origin. 브라우저 페이지에서 보내는 요청은 https://www.setherion.com에서 와야 해요. 그 밖의 Origin은 403으로 응답해요. 프로그램이 보내는 요청에는 그 값이 없고, 허용돼요.

주소에 www를 그대로 두세요. 이것이 없는 주소는 리다이렉트되고, 리다이렉트되면 자격 증명이 사라져요.

인증

Authorization 헤더에 자격 증명을 담아 보내세요. 둘 중 어느 것이든 돼요:

• API 키: Authorization: Bearer sth_.... 인증을 참고하세요.
• sto_로 시작하는 OAuth 액세스 토큰으로, 이 엔드포인트용으로만 발급돼요. 이 레퍼런스의 OAuth 로그인 페이지를 참고하세요.

자격 증명이 없거나, 틀렸거나 만료되었거나 취소된 자격 증명을 보내면 401로 응답하며 로그인할 곳을 알려 줘요:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Setherion", resource_metadata="https://www.setherion.com/.well-known/oauth-protected-resource/api/mcp"

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Sign in to Setherion to use this server, or send an API key from your account page as \"Authorization: Bearer sth_...\"."
  }
}

자격 증명이 없는 클라이언트는 resource_metadata를 따라가 로그인할 곳을 찾아요. 이 토큰은 이 엔드포인트에서만 작동해요. 이 레퍼런스의 REST 엔드포인트는 API 키를 받아요.

메서드

curl -X POST https://www.setherion.com/api/mcp \
  -H "Authorization: Bearer $SETHERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

도구

instruction은 수정의 prompt로 전송되고, 최대 4,000자까지 가능해요. way는 easy 또는 native예요. offset은 0 이상의 정수이고, 텍스트로 보내도 돼요. edit_project는 모델을 받지 않고 auto로 실행돼요.

tools/list는 각 도구의 title, description, inputSchema, annotations를 알려 줘요. 읽기 도구에는 readOnlyHint: true가 표시되고, publish_project에는 멱등성이 표시돼요.

curl -X POST https://www.setherion.com/api/mcp \
  -H "Authorization: Bearer $SETHERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
        "params": { "name": "list_projects", "arguments": { "query": "coffee" } } }'

도구의 결과

도구는 엔드포인트의 JSON으로 응답하고, 모든 종류의 클라이언트를 위해 두 가지 형태로 담아요:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "{ \"ok\": true, \"total\": 1, ... }" }],
    "structuredContent": { "ok": true, "total": 1, "truncated": false, "offset": 0, "nextOffset": null, "projects": [] },
    "isError": false
  }
}

(여기서는 projects를 줄여서 보여 줘요. 실제로는 내 앱 목록 조회에 설명된 항목들이 들어 있어요.)

엔드포인트가 거부하면 isError는 true가 되고, structuredContent는 빠지고, content에는 모델이 읽을 수 있도록 엔드포인트의 error 문장만 담겨요. ok: false로 끝나는 수정도 이런 의미에서는 오류예요.

긴 수정

수정에는 몇 분이 걸려요. 요청을 Accept: text/event-stream과 함께 보내면 응답이 스트리밍돼요:

• 10초마다 서버가 notifications/progress 이벤트를 보내요. progress에는 지금까지 걸린 초가 들어가고 메시지는 Still editing, 30s so far예요. 단, progressToken을 params._meta에 넣은 경우에만 그래요. 토큰이 없으면 주석 줄 : still editing을 보내요. 어느 쪽이든 연결을 유지해 주고, 클라이언트가 타임아웃을 초기화할 수 있게 해 줘요.
• 마지막 이벤트는 도구 결과예요. event: message로 오고, JSON-RPC 응답이 data에 담겨요.

event: message
data: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"t1","progress":10,"message":"Still editing, 10s so far"}}

event: message
data: {"jsonrpc":"2.0","id":3,"result":{"content":[...],"structuredContent":{"ok":true,"runId":"..."},"isError":false}}

Accept 헤더가 없으면 요청이 열린 채로 있다가 JSON 객체 하나로 응답해요.

4분이 지나도 계속 실행되는 수정

edit_project는 최대 4분쯤 기다려요. 일부 어시스턴트는 5분 동안 조용한 도구를 포기하기 때문이에요. 그때까지도 작업 중인 수정은 ok: true, status: "running", 그리고 runId와 함께 응답해요:

{
  "ok": true,
  "status": "running",
  "runId": "b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61",
  "projectId": "7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14",
  "message": "Still editing. It carries on in Setherion without you: do not send it again. Call edit_status with this runId in a minute or so, until it says \"done\"."
}

수정은 Setherion에서 계속 진행돼요. edit_status를 project_id, run_id와 함께 1분쯤마다 호출하세요. 응답은 수정 진행 상황 확인과 같고, status가 done이 될 때까지 이어져요.

오류

찾을 수 없는 앱이나 도달한 한도처럼 도구 자체가 거부한 경우는 isError: true인 도구 결과예요. 그 문장은 오류와 제한에 나열된 것과 같아요.