Qual servidor MCP devo usar?
Os dois servidores expõem operações do PDF123. A diferença está no lugar onde rodam e na forma como os arquivos chegam a eles.
| Local: @pdf123/mcp | Hospedado: /mcp | |
|---|---|---|
| Onde roda | Na sua máquina, iniciado pelo cliente MCP via stdio | Nos servidores do PDF123, em https://pdf123.xyz/mcp |
| Entrada | Caminhos de arquivos no disco. O servidor os envia e salva o resultado ao lado da entrada | Arquivos enviados pela ferramenta de upload |
| Credenciais | Nenhuma no uso anônimo. PDFX_API_KEY é opcional | Cabeçalho X-API-KEY em toda requisição. Sem ele, a resposta é 401 |
| Instalação | npx -y @pdf123/mcp | Nada. Adicione a URL e o cabeçalho ao cliente |
| Ferramentas | Cinco ferramentas para o catálogo completo de 97 ferramentas | Sete ferramentas: describe, convert, pages, misc, security, upload e download |
| Use quando | Um agente trabalha com documentos de uma pasta local | Um agente ou serviço hospedado já cuida dos uploads pela API |
Use o servidor local para assistentes de programação em um notebook. Use o endpoint hospedado quando o agente roda na nuvem e não consegue ler o seu disco.
Como instalo o servidor MCP local?
Não é preciso instalar nada, pois o cliente MCP inicia o servidor com npx. No Claude Code, adicione-o com um comando.
claude mcp add pdf123 -- npx -y @pdf123/mcpO Claude Desktop lê claude_desktop_config.json, e o Cursor lê .cursor/mcp.json. Outros clientes têm uma página ou um arquivo de configurações de MCP. Todos aceitam a mesma entrada mcpServers.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Reinicie o cliente depois de alterar a configuração. Para manter uma cópia no seu PATH, execute npm install -g @pdf123/mcp, que fornece o comando pdf123-mcp. O servidor exige Node 20.3 ou mais recente e uma base de API acessível. Não existe modo offline.
O que peço primeiro ao agente?
Peça em linguagem natural e cite os arquivos. Por exemplo:
Junte ~/Documents/a.pdf e ~/Documents/b.pdf e depois comprima o resultado.
O agente chama pdf123_run_pipeline, ou pdf123_run_tool duas vezes, envia os arquivos ao PDF123 e responde com o caminho do arquivo salvo. O resultado é salvo ao lado da primeira entrada e nunca substitui um arquivo existente. As mesmas operações existem no site como Juntar e Comprimir.
Quais ferramentas o servidor local oferece?
O servidor tem cinco ferramentas. Ids de ferramentas como merge são argumentos de texto simples, então a lista de ferramentas continua curta.
| Ferramenta | O que faz | Argumentos principais |
|---|---|---|
pdf123_list_tools | Lista as ferramentas, uma linha para cada | group, query, format |
pdf123_describe_tool | Mostra os campos de uma ferramenta, os valores padrão, os valores permitidos e se ela roda como lote | tool |
pdf123_run_tool | Executa uma ferramenta em arquivos locais e devolve o caminho salvo ou o relatório JSON | tool, files, params, output |
pdf123_run_pipeline | Encadeia até 8 ferramentas em uma única requisição | steps, files, output |
pdf123_call | Envia uma requisição bruta para qualquer id de ferramenta, id de operação ou caminho /api/... | target, files, fields |
Um agente costuma chamar pdf123_list_tools para encontrar uma ferramenta, pdf123_describe_tool para ler os campos dela e, depois, pdf123_run_tool. Um id digitado errado devolve sugestões de “você quis dizer”.
Como funcionam lotes, senhas e pipelines?
- Lotes. Vários arquivos passados a uma ferramenta de arquivo único rodam como um lote, com um resultado por arquivo. Cada arquivo é salvo assim que termina. A resposta é um relatório por arquivo. Se algum arquivo falhar, a resposta é um erro com o relatório anexado, para que o agente repita apenas os arquivos com falha.
- Senhas.
input_passwordabre todas as entradas criptografadas.passwordsdefine uma senha por arquivo, na mesma ordem defiles, com uma string vazia para um arquivo aberto. Isso também vale para ferramentas de vários arquivos, como Juntar. - Pipelines.
pdf123_run_pipelineaceita até 8 etapas, e cada etapa alimenta a seguinte. Aceita os mesmos argumentos de senha. - Chamadas brutas.
pdf123_callalcança operações mais novas que o servidor. Nada é validado localmente. - Ferramentas de filtro. Uma ferramenta cujo id começa com
filter-responde{"matched": false}quando a condição dela não é atendida. Isso é um resultado, não um erro. - Novas tentativas.
idempotencyKeydevolve o primeiro resultado por 24 horas.
Como limito as pastas que o agente pode usar?
Defina PDFX_MCP_ROOT com um diretório. Separe vários diretórios com dois-pontos, ou com ponto e vírgula no Windows. O servidor passa então a ler entradas e gravar resultados apenas dentro desses diretórios. Caminhos fora deles, escapes com .. e links simbólicos que levam para fora são recusados antes de qualquer envio, com Code: path_not_allowed. Sem essa variável, qualquer caminho que o processo do servidor alcance é permitido.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Defina variáveis de ambiente no bloco env do cliente ou com claude mcp add -e NAME=value. PDFX_API_BASE aponta o servidor para o seu próprio pdfx-server; veja Self-host.
Como são os resultados e os erros?
Um resultado único é um pequeno objeto JSON com o path salvo, o contentType e o tamanho em bytes. O resultado de um lote tem processed, unmatched, failed e uma lista files. Esses formatos correspondem a pdfx --json na linha de comando. Uma ferramenta que devolve um relatório, como Informações do documento, devolve o relatório na própria resposta.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Uma chamada com falha volta como erro da ferramenta. O texto termina com as linhas Reason:, Code: e Hint: quando o servidor as forneceu, para que o agente possa ramificar pelo código.
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.Se um id de ferramenta tem um erro de digitação, o erro lista ids parecidos e termina com Code: unknown_tool. Uma ferramenta que não encontra nada para devolver, como pdf-to-csv em um PDF sem tabelas, devolve Code: no_content em vez de um arquivo vazio. Veja Códigos de erro.
Como uso o endpoint MCP hospedado?
A API incorpora um servidor MCP em POST https://pdf123.xyz/mcp. Autentique-se com o mesmo cabeçalho X-API-KEY que a API REST usa. Sem chave, o endpoint responde 401. Crie uma chave na página para desenvolvedores.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}O servidor hospedado lista sete ferramentas: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload e pdf_toolbox_download. Cada ferramenta de categoria recebe um nome de operation e seus parâmetros, mais um arquivo ou um fileId devolvido pela ferramenta de upload. Use a ferramenta describe para obter o esquema de uma operação.
Páginas relacionadas
- Skills para agentes para Claude Code, Codex e Cursor, uma para o catálogo e uma por ferramenta
- /llms.txt, um índice em texto simples das ferramentas, da API e do endpoint MCP
- Linha de comando pdfx e SDK TypeScript, que compartilham o catálogo
- Visão geral para desenvolvedores, o documento OpenAPI e o Swagger UI
- Páginas de ferramentas: Juntar, Comprimir, OCR, Proteger, Reparar
- Os artigos “Built for AI Agents, Not Just Browsers” e “Same Operation, Four Clients” no blog do PDF123
FAQ
O que é MCP?
MCP, o Model Context Protocol, é um padrão aberto para conectar clientes de IA a ferramentas externas. Um cliente como o Claude Code inicia um servidor MCP ou se conecta a ele, lista as ferramentas e as chama em nome do usuário.
O servidor MCP local funciona offline?
Não. Ele envia os arquivos para a API do PDF123, ou para o servidor indicado em PDFX_API_BASE, e salva o resultado localmente. A base da API precisa estar acessível.
Ele precisa de uma chave de API?
O servidor local não precisa de chave no uso anônimo. Defina PDFX_API_KEY se o seu servidor exigir uma. O endpoint hospedado em /mcp sempre exige o cabeçalho X-API-KEY.
O agente pode ler qualquer arquivo do meu computador?
Por padrão, ele pode ler qualquer caminho que o processo do servidor alcance. Defina PDFX_MCP_ROOT para limitar leitura e gravação aos diretórios que você escolher.
O que acontece com os meus arquivos?
O servidor local envia cada entrada para a API do PDF123, ou para o seu próprio servidor, para processamento. A descrição da ferramenta informa que os arquivos são apagados lá depois do processamento. O resultado é salvo na sua máquina. Para saber mais, leia a página de privacidade de arquivos.
Quantas ferramentas um agente pode usar?
O servidor local alcança todas as 97 ferramentas do catálogo por meio de cinco ferramentas MCP. O endpoint hospedado agrupa suas operações por categoria (convert, pages, misc e security) em sete ferramentas MCP.