Ir para o conteúdo principal
PPDF123

Servidores MCP do PDF123 para agentes de IA

MCP, o Model Context Protocol, é um padrão aberto que permite a clientes de IA como Claude Code, Claude Desktop e Cursor chamar ferramentas externas. O PDF123 oferece um servidor MCP local, @pdf123/mcp, para arquivos da sua máquina e um endpoint hospedado que usa chave de API.

@pdf123/mcpNode 20.3 ou mais recente

Instalação

npx -y @pdf123/mcp
Nesta página

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/mcpHospedado: /mcp
Onde rodaNa sua máquina, iniciado pelo cliente MCP via stdioNos servidores do PDF123, em https://pdf123.xyz/mcp
EntradaCaminhos de arquivos no disco. O servidor os envia e salva o resultado ao lado da entradaArquivos enviados pela ferramenta de upload
CredenciaisNenhuma no uso anônimo. PDFX_API_KEY é opcionalCabeçalho X-API-KEY em toda requisição. Sem ele, a resposta é 401
Instalaçãonpx -y @pdf123/mcpNada. Adicione a URL e o cabeçalho ao cliente
FerramentasCinco ferramentas para o catálogo completo de 97 ferramentasSete ferramentas: describe, convert, pages, misc, security, upload e download
Use quandoUm agente trabalha com documentos de uma pasta localUm 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 Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

O 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.

Configuração do cliente MCPjson
{
  "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.

FerramentaO que fazArgumentos principais
pdf123_list_toolsLista as ferramentas, uma linha para cadagroup, query, format
pdf123_describe_toolMostra os campos de uma ferramenta, os valores padrão, os valores permitidos e se ela roda como lotetool
pdf123_run_toolExecuta uma ferramenta em arquivos locais e devolve o caminho salvo ou o relatório JSONtool, files, params, output
pdf123_run_pipelineEncadeia até 8 ferramentas em uma única requisiçãosteps, files, output
pdf123_callEnvia 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_password abre todas as entradas criptografadas. passwords define uma senha por arquivo, na mesma ordem de files, com uma string vazia para um arquivo aberto. Isso também vale para ferramentas de vários arquivos, como Juntar.
  • Pipelines. pdf123_run_pipeline aceita até 8 etapas, e cada etapa alimenta a seguinte. Aceita os mesmos argumentos de senha.
  • Chamadas brutas. pdf123_call alcanç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. idempotencyKey devolve 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.

Restringir o acesso a arquivosjson
"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.

Resultado únicojson
{
  "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.

Texto do errotext
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.

Configuração do endpoint hospedadojson
{
  "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.

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.