writely.

AI 도구와 앱에서 문서 게시하기.

MCP와 REST API는 같은 게시 기능을 제공합니다. 텍스트 문서부터 게시해보고, 이미지와 문서 관리가 필요하면 다음 단계로 진행하세요.

AI 도구 연결과 프롬프트 안내 →

익명으로 시작하고, 나중에 계정에 연결하기

로그인은 선택입니다. 먼저 POST /api/v1/keys 또는 MCP의 create_identity로 익명 키를 한 번 발급받으세요. 같은 API 키를 재사용하면 문서가 같은 소유자에게 모입니다.

발급받는 값과 역할
값사용하는 곳
ownerId문서 소유자 ID입니다. 키를 교체하거나 계정에 연결해도 유지됩니다.
keyId키를 찾고 관리하기 위한 식별자입니다. 인증 토큰이 아닙니다.
apiKey게시·조회·공유 중단 요청에 쓰는 비밀 토큰입니다.
claimSecret로그인한 계정에 익명 소유권을 연결할 때만 쓰는 별도의 비밀키입니다.

나중에 계정 화면에서 Cognito로 로그인한 뒤 keyId와 claimSecret을 제출하면, 해당 익명 소유자의 기존 문서와 키가 계정에 연결됩니다. 일반 API 요청에는 소유권 비밀키를 보내지 않습니다.

로컬 설정에 보관하는 CLI

저장소를 내려받은 뒤 아래 명령을 실행하세요. 최초 발급 시 API 키는 ~/.config/writely/credentials.json, 소유권 비밀키는 ownership.json에 따로 저장합니다. 두 파일은 소유자만 읽고 쓸 수 있는 0600 권한이며, 터미널에 비밀값을 출력하지 않습니다.

로컬 CLI
node scripts/writely.mjs init
node scripts/writely.mjs config
node scripts/writely.mjs publish ./report.md --title "보고서"

init은 기존 키를 덮어쓰지 않습니다. config는 MCP 주소와 인증 설정 방법을 안내합니다. 클라이언트 설정은 도구가 제공하는 비밀값 저장 기능을 사용하세요.

API 키와 소유권 비밀키의 원문은 최초 발급 때만 반환됩니다. 문서나 공유 링크에 포함하지 말고 각각 보관하세요.

AI 도구에서 사용하기

원격 MCP를 지원하는 클라이언트에 아래 서버를 등록하세요. 최초 연결은 키 없이 할 수 있습니다. create_identity로 발급받은 키는 이후 Authorization: Bearer API_KEY 헤더 또는 도구의 apiKey 인자 중 한 곳에만 넣으세요.

서버 이름
Writely
연결 방식
Streamable HTTP
시작하기
로그인 없이 익명 키 발급
요청 인증
API 키 · Bearer 헤더 또는 도구 인자
MCP 서버 주소
https://writely.ink/api/mcp
AI에게 서버 등록을 요청하려면

MCP 설정을 바꿀 수 있는 AI 도구에서는 아래 요청을 보낼 수 있습니다. 자동 등록 여부는 도구마다 다릅니다. 처음에는 키 없이 연결하고, 발급받은 API 키를 이후 요청에 재사용하세요.

MCP 연결 요청 프롬프트
Writely를 MCP 서버로 추가해줘.
서버 주소: https://writely.ink/api/mcp
연결 방식: Streamable HTTP (HTTP)
먼저 도구 목록을 확인해줘. 저장된 Writely API 키가 없다면 create_identity를 한 번 호출해줘.
apiKey는 클라이언트의 안전한 인증 설정에 저장해서 재사용하고, claimSecret은 계정 연결용으로 따로 보관해줘. 설정 저장에는 내 도구의 권한을 따라줘.
요청 인증에는 Authorization: Bearer API_KEY 또는 apiKey 도구 인자 중 하나만 써줘. 비밀키를 문서나 공유 링크에 넣지 마.
직접 등록하거나 저장할 수 없다면 필요한 설정을 안내해줘.

원격 MCP 서버는 내 컴퓨터의 설정 파일을 직접 저장할 수 없습니다. 계정 연결은 웹사이트에서 로그인한 뒤 소유권 비밀키로 진행합니다.

Claude Code 명령과 Cursor 설정 예제

Claude Code 터미널에서 실행하면 현재 프로젝트에 서버가 등록됩니다.

Claude Code · HTTP 서버 추가
claude mcp add --transport http writely https://writely.ink/api/mcp

Cursor에서는 MCP 설정 파일의 mcpServers에 다음 항목을 추가하세요.

Cursor · mcp.json 설정
{
  "mcpServers": {
    "writely": {
      "url": "https://writely.ink/api/mcp"
    }
  }
}

이 예제는 최초 연결용입니다. 발급받은 키는 해당 클라이언트의 인증 헤더 설정에 추가하거나 도구 인자로 전달하세요. 서버 주소만 대화에 적었을 때 등록되는지, 비밀값을 저장할 수 있는지는 클라이언트의 기능과 권한에 따라 다릅니다. 모든 MCP 도구에서 자동 OAuth 연결이 되는 것은 아닙니다.

참고: Claude Code 공식 연결 안내 · Cursor 공식 MCP 설정

HTTP와 SSE 중 무엇을 선택하나요?

Writely는 Streamable HTTP를 사용합니다. 클라이언트에서 HTTP를 선택하세요. 요청은 HTTP POST로 처리하며 영구 SSE 구독이나 별도 /sse 주소는 제공하지 않습니다.

브라우저에서 MCP 주소를 직접 열면 GET 요청에 405가 반환됩니다. MCP 연결은 POST의 초기화 요청과 도구 호출로 확인하세요.

인증을 설정한 뒤 텍스트만 게시할 때는 publish_document에 title과 markdown을 전달하면 됩니다.

MCP에서 사용할 수 있는 도구
도구하는 일
create_identity로그인 없이 재사용할 API 키와 별도의 소유권 비밀키를 한 번 발급합니다.
publish_document제목과 마크다운을 게시합니다. 이미지가 있으면 세션 정보도 전달합니다.
create_publishing_session이미지 게시에 사용할 문서 ID·이미지 ID·세션 토큰을 발급합니다.
prepare_image_upload세션의 이미지 ID에 사용할 presigned PUT URL을 발급합니다.
list_documents인증된 소유자의 문서 목록을 조회합니다.
get_document문서 ID와 API 키로 내 원본 마크다운을 조회합니다.
revoke_document내 문서의 공유를 중단하고 CDN 캐시 삭제 상태를 확인합니다.

원격 서버는 로컬 파일이나 설정에 직접 접근할 수 없습니다. 로컬 파일을 업로드하고 키를 저장하는 일은 권한이 있는 클라이언트 또는 CLI가 맡습니다.

텍스트 문서 게시하기

발급받은 API 키를 WRITELY_API_KEY 환경 변수에 설정한 뒤 제목과 마크다운을 JSON으로 보내세요. 성공 응답은 HTTP 201입니다.

텍스트 게시 · curl
curl -X POST https://writely.ink/api/v1/documents \
  -H "Authorization: Bearer $WRITELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"title":"회의 요약","markdown":"# 오늘 결정한 것"}'

공유할 값은 url입니다. 문서 ID는 고정되고, 조회·공유 중단에는 기존 API 키를 계속 사용합니다.

게시 응답
필드용도
id바뀌지 않는 랜덤 문서 ID
url읽기 전용 공유 링크
createdAt게시 시각
키 없이 문서나 세션을 처음 만들면 응답의 credentials에 새 익명 키와 소유권 비밀키가 함께 반환됩니다. 이를 저장하고 다음 요청부터 API 키를 재사용하세요. 매번 키 없이 요청하면 서로 다른 소유자가 만들어집니다.

이미지를 업로드한 뒤 게시하기

파일은 presigned URL로 저장소에 직접 업로드합니다. 문서는 업로드된 이미지를 ID로 참조합니다. REST와 MCP 모두 다음 순서로 진행합니다.

이미지 포함 게시 순서
단계RESTMCP전달할 정보
1. 세션 발급POST /api/v1/sessionscreate_publishing_sessionAPI 키로 요청하고 id, assetIds, sessionToken을 보관합니다.
2. 업로드 준비POST /api/assets/uploadprepare_image_uploadsessionToken, assetId, contentType, size(바이트)를 전달합니다.
3. 파일 전송반환된 uploadUrl에 PUT클라이언트에서 HTTP PUT반환된 method와 headers를 사용해 실제 파일을 전송합니다.
4. 문서 게시POST /api/v1/documentspublish_document같은 API 키로 본문의 이미지 참조와 sessionToken을 전달합니다.

3단계 PUT 요청이 성공하면 본문에 ![설명](writely-asset:이미지ID)를 넣어 게시하세요. 업로드 응답의 markdownReference를 이미지 주소로 사용하면 됩니다. 세션 발급부터 게시까지 같은 API 키를 사용하고, S3 PUT 요청에는 API 키를 보내지 마세요.

전체 Node.js 예제 보기 · 이미지 업로드부터 게시까지

같은 디렉터리에 chart.png를 두고 Node.js에서 실행하세요. 별도 SDK가 필요하지 않습니다.

이미지 포함 게시 · Node.js
import { readFile } from 'node:fs/promises';

const origin = 'https://writely.ink';
const apiKey = process.env.WRITELY_API_KEY;
if (!apiKey) throw new Error('Set WRITELY_API_KEY first');

async function post(path, body = {}) {
  const response = await fetch(origin + path, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + apiKey },
    body: JSON.stringify(body),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error);
  return result;
}

// 1. 같은 API 키로 세션과 이미지 ID를 발급받습니다.
const session = await post('/api/v1/sessions');
const image = await readFile('./chart.png');

// 2. 실제 파일의 형식과 정확한 바이트 수로 업로드를 준비합니다.
const upload = await post('/api/assets/upload', {
  sessionToken: session.sessionToken,
  assetId: session.assetIds[0],
  contentType: 'image/png',
  size: image.length,
});

// 3. S3로 직접 전송합니다. API 키는 이 요청에 보내지 않습니다.
const sent = await fetch(upload.uploadUrl, {
  method: upload.method,
  headers: upload.headers,
  body: image,
});
if (!sent.ok) throw new Error('Image upload failed');

// 4. 업로드한 이미지 ID를 본문에서 참조해 게시합니다.
const document = await post('/api/v1/documents', {
  title: '이미지가 있는 보고서',
  markdown: '# 보고서\n\n![차트](' + upload.markdownReference + ')',
  sessionToken: session.sessionToken,
});
console.log(document.url);
// 이후 조회·공유 중단에도 같은 API 키를 사용합니다.
업로드 URL의 유효기간과 응답 필드

게시 세션은 24시간, 업로드 URL은 최대 5분 동안 유효합니다. URL이 만료되면 유효한 세션과 같은 이미지 ID로 다시 발급받으세요. 같은 파일 경로의 덮어쓰기는 허용하지 않습니다.

업로드 준비 응답: assetId, uploadUrl, method, headers, contentLength, expiresAt(Unix 밀리초), maximumSizeInBytes, markdownReference. 반환된 헤더와 선언한 바이트 수를 그대로 사용하세요.

로컬 CLI로 이미지와 함께 게시하기

본문에 ![차트](writely-upload:chart)를 넣고 실제 파일을 명시적으로 연결하세요. CLI가 세션 발급, S3 업로드, 이미지 참조 교체와 게시를 진행합니다.

CLI 이미지 게시
node scripts/writely.mjs publish ./report.md --image chart=./chart.png
MCP 클라이언트도 파일 접근과 HTTP PUT 기능이 있어야 이미지를 전송할 수 있습니다. 지원하지 않는 클라이언트에서는 직접 게시하기를 이용하세요.

원본을 조회하거나 공유 중단하기

REST 요청에는 Authorization: Bearer API_KEY 헤더를 사용하세요. MCP도 같은 인증을 사용하며, 문서 ID는 도구의 id 인자로 전달합니다. 신규 문서는 문서별 관리 키를 발급하지 않습니다.

문서 관리 요청
할 일RESTMCP
원본 조회GET /api/v1/documents/문서IDget_document
공유 중단POST /api/v1/documents/문서ID/revokerevoke_document

공유 페이지는 게시할 때 만든 HTML과 이미지를 CDN에서 제공합니다. 공유 중단 요청에 HTTP 202와 status: revocationPending이 반환되면 캐시 삭제가 진행 중입니다. 같은 요청을 다시 보내 status: revoked가 된 뒤 페이지와 이미지의 404를 확인하세요. 이미 내려받은 사본까지 지울 수는 없습니다.

게시한 문서는 고정된 사본이므로 수정한 내용은 새 문서로 게시하세요.

계정의 키 관리 API

아래 작업은 로그인한 계정의 세션 또는 계정 JWT가 필요합니다. 일반 API 키만으로 다른 키를 발급하거나 익명 소유권을 연결할 수는 없습니다.

계정 키 관리
요청역할
GET /api/v1/keys계정 키 목록
POST /api/v1/keys로그인 상태에서 새 키 발급
POST /api/v1/keys/claim{ keyId, claimSecret }으로 익명 소유권 연결
POST /api/v1/keys/키ID/rotate기존 키를 폐기하고 새 API 키 발급
POST /api/v1/keys/키ID/revoke키 폐기

계정 연결과 키 교체는 기존 문서 ID나 공유 URL을 바꾸지 않습니다.

문서와 이미지 제한

제목
200자
마크다운 본문
UTF-8 기준 256 KiB
이미지
JPEG·PNG·WebP, 파일당 5 MiB, 문서당 10개
지원하는 마크다운 문법 전체 보기 →