Какой MCP-сервер выбрать?
Оба сервера предоставляют операции PDF123. Они различаются тем, где работают и как к ним попадают файлы.
| Локальный: @pdf123/mcp | Размещённый: /mcp | |
|---|---|---|
| Где работает | На вашем компьютере; MCP-клиент запускает его по stdio | На серверах PDF123 по адресу https://pdf123.xyz/mcp |
| Входные данные | Пути к файлам на диске. Сервер загружает их и сохраняет результат рядом с исходным файлом | Файлы, отправленные через инструмент загрузки |
| Учётные данные | Для анонимного использования не нужны. 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 — обычные строковые аргументы, поэтому список инструментов остаётся коротким.
| Инструмент | Что делает | Основные аргументы |
|---|---|---|
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 | Отправляет «сырой» запрос по любому идентификатору инструмента, идентификатору операции или пути /api/... | target, files, fields |
Обычно агент вызывает pdf123_list_tools, чтобы найти инструмент, pdf123_describe_tool, чтобы прочитать его поля, а затем pdf123_run_tool. При опечатке в идентификаторе возвращаются подсказки «возможно, вы имели в виду».
Как работают пакеты, пароли и конвейеры?
- Пакеты. Несколько файлов, переданных инструменту для одного файла, обрабатываются как пакет: по одному результату на файл. Каждый файл сохраняется сразу после завершения. Ответ — отчёт по каждому файлу. Если какой-то файл не обработан, ответом будет ошибка с приложенным отчётом, так что агент может повторить только неудавшиеся файлы.
- Пароли.
input_passwordоткрывает все зашифрованные входные файлы.passwordsзадаёт по одному паролю на файл в том же порядке, что иfiles; для файла без защиты указывается пустая строка. Это работает и для инструментов с несколькими файлами, например Объединить. - Конвейеры.
pdf123_run_pipelineпринимает до 8 шагов, и каждый шаг передаёт результат следующему. Он принимает те же аргументы паролей. - Сырые вызовы.
pdf123_callобращается к операциям, которые новее сервера. Локально ничего не проверяется. - Инструменты-фильтры. Инструмент, идентификатор которого начинается с
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; см. Self-host.
Как выглядят результаты и ошибки?
Одиночный результат — небольшой объект JSON с path сохранённого файла, contentType и размером в bytes. Результат пакета содержит 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.Если в идентификаторе инструмента опечатка, ошибка перечисляет близкие идентификаторы и заканчивается Code: unknown_tool. Инструмент, которому нечего вернуть, например pdf-to-csv для PDF без таблиц, возвращает Code: no_content, а не пустой файл. См. Коды ошибок.
Как использовать размещённую конечную точку MCP?
API встраивает MCP-сервер по адресу POST https://pdf123.xyz/mcp. Для аутентификации используется тот же заголовок X-API-KEY, что и в REST API. Без ключа конечная точка отвечает 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 и SDK для TypeScript, использующие тот же каталог
- Обзор для разработчиков, документ OpenAPI и Swagger UI
- Страницы инструментов: Объединить, Сжать, OCR, Задать пароль, Исправить
- Записи «Создан для AI-агентов, а не только для браузеров» и «Одна операция, четыре клиента» в блоге PDF123
Вопросы и ответы
Что такое MCP?
MCP, Model Context Protocol, — открытый стандарт подключения ИИ-клиентов к внешним инструментам. Клиент, например Claude Code, запускает MCP-сервер или обращается к нему, получает список его инструментов и вызывает их от имени пользователя.
Работает ли локальный MCP-сервер без сети?
Нет. Он загружает файлы в API PDF123 или на сервер, указанный в PDFX_API_BASE, и сохраняет результат локально. Базовый адрес API должен быть доступен.
Нужен ли ему ключ API?
Локальному серверу для анонимного использования ключ не нужен. Задайте PDFX_API_KEY, если ваш сервер его требует. Размещённой конечной точке /mcp всегда нужен заголовок X-API-KEY.
Может ли агент прочитать любой файл на моём компьютере?
По умолчанию он может прочитать любой путь, до которого дотягивается процесс сервера. Задайте PDFX_MCP_ROOT, чтобы ограничить чтение и запись выбранными вами каталогами.
Что происходит с моими файлами?
Локальный сервер загружает каждый входной файл в API PDF123 или на ваш собственный сервер для обработки. В описании инструмента указано, что после обработки файлы там удаляются. Результат сохраняется на вашем компьютере. Подробности — на странице о конфиденциальности файлов.
Сколько инструментов может использовать агент?
Локальный сервер даёт доступ ко всем 97 инструментам каталога через пять инструментов MCP. Размещённая конечная точка группирует операции по категориям (convert, pages, misc и security) за семью инструментами MCP.