어떤 MCP 서버를 써야 하나요?
두 서버 모두 PDF123의 작업을 제공합니다. 실행되는 위치와 파일이 전달되는 방식이 다릅니다.
| 로컬: @pdf123/mcp | 호스팅: /mcp | |
|---|---|---|
| 실행 위치 | 내 컴퓨터. MCP 클라이언트가 stdio로 시작 | https://pdf123.xyz/mcp의 PDF123 서버 |
| 입력 | 디스크의 파일 경로. 서버가 업로드하고 결과를 입력 파일 옆에 저장 | 업로드 도구로 보낸 파일 |
| 자격 증명 | 익명 사용에는 없음. PDFX_API_KEY는 선택 사항 | 모든 요청에 X-API-KEY 헤더 필요. 없으면 401로 응답 |
| 설치 | npx -y @pdf123/mcp | 없음. 클라이언트에 URL과 헤더만 추가 |
| 도구 | 97개 도구 전체 카탈로그를 다루는 다섯 가지 도구 | 일곱 가지 도구: describe, convert, pages, misc, security, upload, download |
| 이럴 때 사용 | 에이전트가 로컬 폴더의 문서를 다룰 때 | 에이전트나 호스팅 서비스가 이미 API로 업로드를 처리할 때 |
노트북의 코딩 어시스턴트에는 로컬 서버를 쓰세요. 에이전트가 클라우드에서 실행되어 내 디스크를 읽을 수 없다면 호스팅 엔드포인트를 쓰세요.
로컬 MCP 서버는 어떻게 설치하나요?
MCP 클라이언트가 npx로 서버를 시작하므로 따로 설치할 것은 없습니다. Claude Code에서는 명령 하나로 추가합니다.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop은 claude_desktop_config.json을, Cursor는 .cursor/mcp.json을 읽습니다. 다른 클라이언트에도 MCP 설정 페이지나 파일이 있습니다. 모두 같은 mcpServers 항목을 받아들입니다.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}설정을 바꾼 뒤에는 클라이언트를 다시 시작하세요. 경로에 사본을 두려면 npm install -g @pdf123/mcp를 실행하세요. 그러면 pdf123-mcp 명령이 생깁니다. 서버에는 Node 20.3 이상과 접속 가능한 API 기본 주소가 필요합니다. 오프라인 모드는 없습니다.
에이전트에게 처음에 무엇을 요청하나요?
평소 말하듯이 파일을 지정해 요청하세요. 예를 들면 다음과 같습니다.
~/Documents/a.pdf와 ~/Documents/b.pdf를 병합한 다음, 그 결과를 압축해 줘.
에이전트는 pdf123_run_pipeline을 호출하거나 pdf123_run_tool을 두 번 호출해 파일을 PDF123에 업로드하고, 저장된 파일의 경로로 답합니다. 결과는 첫 번째 입력 파일 옆에 저장되며 기존 파일을 교체하지 않습니다. 같은 작업을 웹사이트에서는 병합과 압축으로 사용할 수 있습니다.
로컬 서버는 어떤 도구를 제공하나요?
서버에는 다섯 가지 도구가 있습니다. merge 같은 도구 ID는 일반 문자열 인수이므로 도구 목록이 작게 유지됩니다.
| 도구 | 기능 | 주요 인수 |
|---|---|---|
pdf123_list_tools | 도구를 한 줄씩 나열 | group, query, format |
pdf123_describe_tool | 도구의 필드, 기본값, 허용 값, 일괄 처리로 실행되는지 여부를 보여 줌 | tool |
pdf123_run_tool | 로컬 파일에 도구 하나를 실행하고 저장된 경로 또는 JSON 보고서를 반환 | tool, files, params, output |
pdf123_run_pipeline | 최대 8개의 도구를 한 번의 요청으로 연결 | steps, files, output |
pdf123_call | 임의의 도구 ID, 작업 ID 또는 /api/... 경로에 원시 요청을 보냄 | target, files, fields |
에이전트는 보통 pdf123_list_tools로 도구를 찾고, pdf123_describe_tool로 필드를 읽은 다음 pdf123_run_tool을 호출합니다. ID를 잘못 입력하면 "혹시 이것을 찾으셨나요" 하는 후보가 반환됩니다.
일괄 처리, 비밀번호, 파이프라인은 어떻게 동작하나요?
- 일괄 처리. 단일 파일 도구에 파일 여러 개를 주면 파일마다 결과 하나를 내는 일괄 처리로 실행됩니다. 각 파일은 끝나는 대로 저장됩니다. 응답은 파일별 보고서입니다. 실패한 파일이 하나라도 있으면 보고서가 첨부된 오류로 응답하므로, 에이전트는 실패한 파일만 다시 시도할 수 있습니다.
- 비밀번호.
input_password는 암호화된 모든 입력을 엽니다.passwords는files와 같은 순서로 파일마다 비밀번호 하나를 지정하며, 잠기지 않은 파일에는 빈 문자열을 씁니다. 병합처럼 여러 파일을 받는 도구에서도 동작합니다. - 파이프라인.
pdf123_run_pipeline은 최대 8단계를 받고, 각 단계가 다음 단계로 이어집니다. 같은 비밀번호 인수를 받습니다. - 원시 호출.
pdf123_call로 서버보다 새로운 작업에도 접근할 수 있습니다. 로컬에서는 아무것도 검증하지 않습니다. - 필터 도구. ID가
filter-로 시작하는 도구는 조건이 맞지 않으면{"matched": false}로 응답합니다. 이것은 오류가 아니라 결과입니다. - 재시도.
idempotencyKey는 24시간 동안 첫 번째 결과를 재생합니다.
에이전트가 쓸 수 있는 폴더를 제한하려면?
PDFX_MCP_ROOT를 디렉터리로 설정하세요. 디렉터리가 여러 개이면 콜론으로 구분하고, Windows에서는 세미콜론으로 구분합니다. 그러면 서버는 그 디렉터리 안에서만 입력을 읽고 결과를 씁니다. 그 밖의 경로, ..로 벗어나는 경로, 밖으로 이어지는 심볼릭 링크는 아무것도 업로드하기 전에 Code: path_not_allowed로 거부됩니다. 이 변수가 없으면 서버 프로세스가 접근할 수 있는 모든 경로가 허용됩니다.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }환경 변수는 클라이언트의 env 블록에 설정하거나 claude mcp add -e NAME=value로 설정하세요. PDFX_API_BASE를 쓰면 서버가 대신 내 pdfx-server를 가리키게 할 수 있습니다. 셀프 호스트를 참고하세요.
결과와 오류는 어떤 모습인가요?
단일 결과는 저장된 path, contentType, 크기 bytes를 담은 작은 JSON 객체입니다. 일괄 처리 결과에는 processed, unmatched, failed와 files 목록이 있습니다. 이 형태는 명령줄의 pdfx --json과 같습니다. 문서 정보처럼 보고서를 반환하는 도구는 보고서를 그대로 반환합니다.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}실패한 호출은 도구 오류로 돌아옵니다. 서버가 제공하면 그 텍스트 끝에 Reason:, Code:, Hint: 줄이 붙으므로, 에이전트는 코드로 분기할 수 있습니다.
HTTP 400: This PDF is password-protected. Enter its password.
Reason: password_required
Code: bad_request
Hint: Provide the document password, or unlock the PDF first.도구 ID에 오타가 있으면 오류에 비슷한 ID가 나열되고 끝에 Code: unknown_tool이 붙습니다. 표가 없는 PDF에 pdf-to-csv를 실행하는 경우처럼 반환할 것이 없는 도구는 빈 파일 대신 Code: no_content를 반환합니다. 오류 코드를 참고하세요.
호스팅 MCP 엔드포인트는 어떻게 쓰나요?
API에는 POST https://pdf123.xyz/mcp에 MCP 서버가 내장되어 있습니다. 인증에는 REST API와 같은 X-API-KEY 헤더를 씁니다. 키가 없으면 엔드포인트가 401로 응답합니다. 키는 개발자 페이지에서 만들 수 있습니다.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}호스팅 서버는 일곱 가지 도구를 제공합니다. pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload, pdf_toolbox_download입니다. 카테고리별 도구는 operation 이름과 그 매개변수, 그리고 파일 또는 업로드 도구가 반환한 fileId를 받습니다. 작업 하나의 스키마를 얻으려면 describe 도구를 쓰세요.
관련 페이지
- 에이전트 스킬: Claude Code, Codex, Cursor용. 카탈로그용 하나와 도구마다 하나씩
- /llms.txt: 도구, API, MCP 엔드포인트의 일반 텍스트 색인
- pdfx 명령줄과 TypeScript SDK: 카탈로그를 공유합니다
- 개발자 개요, OpenAPI 문서, Swagger UI
- 도구 페이지: 병합, 압축, OCR, 보호, 복구
- PDF123 블로그의 글 "Built for AI Agents, Not Just Browsers"와 "Same Operation, Four Clients"
FAQ
MCP란 무엇인가요?
MCP(Model Context Protocol)는 AI 클라이언트를 외부 도구에 연결하기 위한 개방형 표준입니다. Claude Code 같은 클라이언트가 MCP 서버를 시작하거나 접속해 도구 목록을 가져오고, 사용자를 대신해 도구를 호출합니다.
로컬 MCP 서버는 오프라인에서 동작하나요?
아니요. 파일을 PDF123 API 또는 PDFX_API_BASE에 지정한 서버에 업로드하고 결과를 로컬에 저장합니다. API 기본 주소에 접속할 수 있어야 합니다.
API 키가 필요한가요?
로컬 서버는 익명 사용에 키가 필요 없습니다. 서버에 키가 필요하면 PDFX_API_KEY를 설정하세요. /mcp의 호스팅 엔드포인트에는 항상 X-API-KEY 헤더가 필요합니다.
에이전트가 내 컴퓨터의 아무 파일이나 읽을 수 있나요?
기본적으로는 서버 프로세스가 접근할 수 있는 모든 경로를 읽을 수 있습니다. 읽기와 쓰기를 선택한 디렉터리로 제한하려면 PDFX_MCP_ROOT를 설정하세요.
내 파일은 어떻게 되나요?
로컬 서버는 처리를 위해 각 입력을 PDF123 API 또는 내 서버에 업로드합니다. 도구 설명에는 처리 후 해당 파일이 삭제된다고 명시되어 있습니다. 결과는 내 컴퓨터에 저장됩니다. 자세한 내용은 파일 개인정보 페이지를 읽어 보세요.
에이전트는 몇 개의 도구를 쓸 수 있나요?
로컬 서버는 다섯 가지 MCP 도구를 통해 카탈로그의 97개 도구 전체에 접근합니다. 호스팅 엔드포인트는 작업을 카테고리(convert, pages, misc, security)별로 묶어 일곱 가지 MCP 도구로 제공합니다.