AI 에이전트에서 BrewMyPDF 쓰기 (MCP)

BrewMyPDF 는 Model Context Protocol 로 말합니다. 에이전트가 템플릿을 찾고, 각 템플릿이 어떤 데이터를 요구하는지 알아내고, PDF 를 만들 수 있습니다 — 당신의 API 키, 당신의 쿼터, 당신의 감사 기록으로.

무엇인가

BrewMyPDF 는 MCP 서버입니다. AI 에이전트가 접착 코드 없이 템플릿을 목록으로 보고 렌더할 수 있습니다. 계정도 API 키도 쿼터도 감사 기록도 REST API 와 같은 것을 씁니다 — 에이전트는 별도 신원이 아닙니다.

서버는 상태를 갖지 않습니다. HTTP POST 한 번이 JSON-RPC 2.0 메시지 하나입니다. 열어 둘 세션도, 살려 둘 연결도 없으므로 연결이 끊겨도 잃는 것이 없습니다.

붙이기

MCP 클라이언트를 https://brewmypdf.com/mcp 로 연결하고, API 키를 Authorization 헤더에 베어러 토큰으로 보냅니다. 이 헤더는 REST API(x-api-key)와 다릅니다 — 키 자체는 같은 것이고, 콘솔의 API 키에서 발급합니다.

mcp.json

{
  "mcpServers": {
    "brewmypdf": {
      "url": "https://brewmypdf.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

키가 없거나 틀리면 unauthorized 만 돌아옵니다. WWW-Authenticate 챌린지는 보내지 않습니다 — 우리가 운영하지 않는 발견 절차를 광고하면 클라이언트가 막다른 길로 들어가기 때문입니다. unauthorized 를 받으면 헤더 이름부터 확인하십시오.

tools/list

curl -X POST https://brewmypdf.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

API 키는 Professional 플랜부터 발급됩니다. 그 아래 플랜으로는 에이전트를 붙일 수 없습니다.

도구 넷

모든 도구는 이미 저장된 템플릿을 대상으로 합니다. 템플릿을 만들거나 고치는 도구는 없습니다 — 아래 제한을 보십시오.

`list_templates`	List the PDF templates on this account. Returns id, name and last-updated time. Call this first — every other tool needs a template_id from here.
`describe_template_schema`	Describe the JSON data a template expects. Returns a JSON Schema plus the flat list of binding paths found in the template. Types are intentionally left open — the template only says which values it uses, not what they must be. Call this before preview_template or render_pdf.
`preview_template`	Render a template with data to HTML, without producing a PDF. Free and fast — use it to check your data fits before calling render_pdf. Returns the HTML and any binding warnings (a warning is not a failure: it tells you which value was missing or wrong).
`render_pdf`	Render a template with data to a PDF and return a download URL. This consumes one render from the account quota, so preview_template first. If the render takes longer than the wait window you get a job_id with status "queued" instead of a URL.

부르는 순서

list_templates 로 id 를 얻습니다. describe_template_schema 가 그 id 를 템플릿이 요구하는 정확한 JSON 모양으로 바꿔 줍니다 — 바인딩 경로까지 들어 있으므로, 필드 이름을 추측하지 말고 데이터를 보내기 전에 이것부터 부르십시오. preview_template 은 공짜로 HTML 을 그려 데이터가 맞는지 보여 줍니다. 그다음 render_pdf 가 렌더 하나를 쓰고 서명된 다운로드 URL 을 돌려줍니다.

렌더가 대기 창보다 오래 걸리면 URL 대신 job id 와 queued 상태가 옵니다. 실패가 아닙니다 — 작업은 돌고 있고, 그 job id 는 REST API 에서도 그대로 씁니다.

서버는 이 순서를 모델에게도 직접 알려 줍니다 — initialize 응답의 instructions 필드입니다. 클라이언트가 그 글을 시스템 프롬프트에 넣을 수 있으므로, 제대로 만든 에이전트는 아무것도 부르기 전에 순서를 알고 있습니다.

할 수 없는 것

템플릿을 만들거나 고칠 수 없습니다. 템플릿은 웹 편집기나 REST API(POST /v1/templates, PUT /v1/templates/{id})로 만듭니다. 에이전트가 쓸 템플릿이 없다면 사람이 먼저 만들어야 합니다.

PDF 만 만듭니다. PNG·JPEG, 그리고 웹훅·배치·PDF 조작 등 나머지는 REST API 를 쓰십시오.

도구는 언어 모델을 부르지 않습니다. 설명으로 템플릿을 만드는 것은 콘솔의 별도 기능이고 크레딧으로 계량합니다.

실패는 두 종류다

돌다가 실패한 도구는 isError 와 메시지로 답합니다 — 없는 템플릿, 잘못된 값, 소진된 쿼터. 읽고 입력을 고쳐 다시 부르면 됩니다.

JSON-RPC 오류는 호출이 아예 시작되지 않았다는 뜻입니다. 없는 도구 이름이거나 필수 인자를 빠뜨린 경우입니다. 값을 바꿔 가며 다시 불러도 소용없습니다 — 도구 목록을 다시 읽으십시오.