Servidor MCP em Python

O SDK Python do NextPDF inclui um servidor Model Context Protocol (MCP) que expõe operações de extração de PDF como ferramentas nativas para agentes. Um agente compatível com MCP, como o Claude Code, registra o servidor uma única vez e depois chama as ferramentas do NextPDF da mesma forma que chamaria qualquer outra ferramenta.

O servidor é um adaptador leve. Cada ferramenta lê um PDF do disco local, usa o cliente assíncrono para chamar o endpoint do NextPDF Connect e retorna o resultado como uma string JSON. O servidor não contém lógica de negócio e não armazena dados entre chamadas.

Instale o SDK com o extra MCP:

pip install nextpdf[mcp]

O extra mcp instala o pacote upstream mcp (com a restrição mcp>=1.0,<2.0). O servidor exige Python 3.10 ou mais recente.

Execute o módulo do servidor pela configuração do cliente MCP. O exemplo abaixo lê os dois valores de conexão do ambiente do host, em vez de embutir um segredo no arquivo de configuração (consulte Segurança):

{
  "mcpServers": {
    "nextpdf": {
      "command": "python",
      "args": ["-m", "nextpdf.mcp"],
      "env": {
        "NEXTPDF_BASE_URL": "https://connect.example.com",
        "NEXTPDF_API_KEY": "${NEXTPDF_API_KEY}"
      }
    }
  }
}

O ponto de entrada python -m nextpdf.mcp executa main(), que inicia o servidor por meio da entrada/saída padrão (stdio) com asyncio.run(serve()). Não o confunda com python -m nextpdf, que executa a interface de linha de comando (CLI), não o servidor MCP.

NEXTPDF_BASE_URL e NEXTPDF_API_KEY são obrigatórios. O servidor cria o cliente sob demanda na primeira chamada de ferramenta. Se alguma das variáveis estiver vazia, ele lança um RuntimeError e o devolve ao agente como erro de ferramenta, em vez de encerrar o processo.

Catálogo de ferramentas e mapeamento para o SDK

O servidor registra oito ferramentas. Todo nome de ferramenta usa o prefixo nextpdf_. Cada ferramenta é mapeada para um método no namespace ast do cliente assíncrono (AsyncNextPDF.ast), exceto as duas ferramentas compostas indicadas abaixo. O servidor as compõe a partir de chamadas de nível mais baixo.

Ferramenta MCP	Chamada do SDK	Observações
`nextpdf_extract_text`	`ast.extract_cited_text(pdf_data, page_index=..., headings_only=...)`	Retorna uma lista de `CitedTextBlock`.
`nextpdf_extract_tables`	`ast.extract_cited_tables(pdf_data, page_range=...)`	Retorna `ExtractCitedTablesResponse`.
`nextpdf_get_ast`	`ast.get_document_ast(pdf_data, page_range_start=0, page_range_end=..., token_budget=...)`	Retorna `AstDocument`.
`nextpdf_info`	`ast.get_document_ast(pdf_data)`	O servidor deriva um resumo de metadados; não há endpoint dedicado.
`nextpdf_health`	nenhuma	Inspeciona somente variáveis de ambiente; não faz chamada de rede.
`nextpdf_search`	`ast.search_ast_nodes(pdf_data, node_type=..., page_index=..., text_query=..., max_results=...)`	Retorna `SearchAstNodesResponse`.
`nextpdf_get_outline`	`ast.search_ast_nodes(pdf_data, node_type="heading", max_results=500)`	O servidor transforma os nós de cabeçalho em um sumário.
`nextpdf_diff`	`ast.get_ast_diff(original_pdf_data, modified_pdf_data)`	Retorna `GetAstDiffResponse`.

Considere estes detalhes de entrada das ferramentas antes de conectar um agente:

Todas as entradas de caminho (pdf_path, original_pdf_path, modified_pdf_path) devem ser caminhos absolutos para arquivos na máquina que executa o servidor. O agente passa o caminho, e o servidor lê os bytes localmente. Não há ferramenta de upload.
nextpdf_extract_text declara um campo max_pages no esquema de entrada, mas o manipulador de texto não o encaminha ao SDK. A seleção de páginas para texto ocorre por meio de page_index (uma única página, com índice baseado em 0). Use nextpdf_get_ast com max_pages quando precisar limitar uma varredura no documento inteiro.
nextpdf_get_ast converte max_pages em um intervalo de páginas inclusivo de [0, max_pages - 1] (o padrão de max_pages é 50). Passe token_budget para limitar o tamanho da árvore retornada.
nextpdf_info retorna schema_version, source_hash, page_count, estimated_tokens, root_node_type e root_children_count. Esses valores vêm do modelo AstDocument, em que estimated_tokens é uma propriedade calculada (aproximadamente quatro caracteres por token).
nextpdf_get_outline retorna uma entrada por cabeçalho com id, page_index, text e depth (lido de attributes["level"] do nó, com valor padrão 1), além de heading_count, total_matches e truncated.

As ferramentas de extração com citações anexam um CitationAnchor a cada resultado. Cada âncora inclui node_id, page_index, um bbox normalizado (coordenadas no intervalo de 0.0 a 1.0) e uma pontuação de confidence (de 0.0 a 1.0). Agentes que precisam de proveniência devem exibir esses campos, e não apenas o texto bruto.

Tratamento de erros, timeouts e cota

O servidor nunca deixa uma exceção escapar para o transporte do agente. O dispatcher call_tool captura todo erro e o retorna como TextContent JSON, de modo que uma chamada de ferramenta com falha produz uma carga útil estruturada que o agente pode ler, em vez de interromper a conexão. Os formatos de carga útil são:

Condição	JSON retornado
Nome de ferramenta desconhecido	`{"error": "Unknown tool: <name>"}`
Arquivo de entrada ausente	`{"error": "PDF file not found: <path>"}`
Qualquer subclasse de `NextPDFError` lançada	`{"error": "<message>", "error_type": "<class>", "status_code": <int?>}`
Qualquer outra exceção	`{"error": "Unexpected error: <message>"}`

status_code aparece apenas quando o erro subjacente carrega um. O SDK mapeia respostas HTTP para uma hierarquia de exceções tipadas, todas com raiz em NextPDFError:

Exceção	Status HTTP	`error_code`	Quando
`NextPDFLicenseError`	402	`license/tier-required`	O endpoint exige, no lado do servidor, um nível de licença mais alto para a operação.
`AstNoStructTreeError`	422	`ast/no-struct-tree`	O PDF não está marcado e o fallback heurístico não está habilitado no servidor.
`QuotaExceededError`	429	`quota/exceeded`	Um limite de taxa ou cota foi atingido. Carrega `retry_after` (segundos) quando o servidor envia um cabeçalho `Retry-After`.
`AstBuildTimeoutError`	504	`ast/build-timeout`	A construção da AST excedeu o orçamento de tempo do servidor. Reduza o intervalo de páginas.
`NextPDFAPIError`	outros 4xx/5xx	fornecido pelo servidor	Qualquer outra falha no nível da API.

Siga estas orientações para integrações de agentes:

Timeouts. O cliente HTTP usa um timeout padrão fixo: 60 segundos no total, com timeout de conexão de 10 segundos. Um documento lento ou grande se manifesta como um AstBuildTimeoutError (o servidor desistiu de construir a AST) ou, se o timeout do próprio cliente expirar, como uma carga útil de Unexpected error da camada de transporte. Quando você vir ast/build-timeout, oriente o agente a restringir o escopo: reduza max_pages em nextpdf_get_ast ou defina page_index / page_start e page_end nas ferramentas de extração.
Cota e backoff. Em caso de 429, a ferramenta retorna o error_type igual a QuotaExceededError, com status_code 429. O valor de retry_after fica no objeto da exceção. Como o servidor serializa apenas error, error_type e status_code, o agente deve tratar o 429 como um sinal para pausar e tentar novamente mais tarde, em vez de analisar um cabeçalho de retry na saída da ferramenta. Aplique cotas no endpoint do Connect, não no agente.
PDFs não marcados. Um 422 ast/no-struct-tree significa que o PDF de origem não tem árvore de estrutura. Habilite o modo heurístico no servidor para esses documentos ou encaminhe-os para uma etapa de marcação antes da extração.

Segurança: escopo da chave de API e privilégio mínimo

Trate a chave de API como um segredo, com o mesmo cuidado que você dedica a uma senha de banco de dados.

Nunca embuta a chave no arquivo de configuração do MCP. O exemplo JSON acima referencia ${NEXTPDF_API_KEY} para que o valor seja resolvido a partir do ambiente do host ou de um gerenciador de segredos no momento da inicialização. Um arquivo de configuração pode ser versionado no controle de versão; um segredo não pode.
Restrinja a chave à extração somente leitura. O servidor MCP chama apenas a interface de extração da AST (extract_cited_text, extract_cited_tables, get_document_ast, search_ast_nodes, get_ast_diff). Ele não renderiza, assina, redige nem altera documentos. Emita uma chave para o agente com escopo do lado do servidor limitado a esses caminhos de leitura, para que um agente comprometido não consiga alcançar operações de escrita ou de nível superior.
Use uma chave dedicada por agente. Uma chave por agente permite revogar ou rotacionar uma integração sem afetar as demais, e torna os logs do endpoint atribuíveis a um agente específico.
Restrinja o sistema de arquivos. Como toda ferramenta lê um caminho absoluto do disco local, o servidor pode ler qualquer arquivo que o processo do host consiga ler. Execute-o como um usuário sem privilégios, restrinja o diretório de trabalho a uma pasta de documentos e nunca o execute com uma conta privilegiada.
Prefira Transport Layer Security (TLS). Aponte NEXTPDF_BASE_URL para um endpoint https:// em qualquer implantação não local. O SDK envia a chave como um token Bearer no cabeçalho Authorization, de modo que o transporte em texto claro a exporia na rede.

Consulte Segurança e operações do Connect para conhecer os controles do lado do endpoint que dão suporte a essas práticas no lado do cliente.

Testar o servidor localmente antes de conectar um agente

Valide o servidor isoladamente antes de conectar um agente. A verificação mais rápida não exige PDF nem rede:

python -c "from nextpdf.mcp import _tool_definitions; print(len(_tool_definitions()))"

Uma instalação correta imprime 8. Se você vir um ImportError mencionando o extra mcp, a dependência opcional está ausente. Reinstale com pip install nextpdf[mcp].

Em seguida, valide as mesmas chamadas do SDK que as ferramentas usam, por meio da CLI. A CLI se comunica com o endpoint usando as mesmas duas variáveis de ambiente. Defina-as uma vez:

export NEXTPDF_BASE_URL="https://connect.example.com"
export NEXTPDF_API_KEY="$(cat /run/secrets/nextpdf_api_key)"

Depois, confirme a versão, a conectividade e uma extração real:

nextpdf version
nextpdf info /path/to/sample.pdf
nextpdf extract text /path/to/sample.pdf --headings-only

nextpdf version é executado sem credenciais e confirma que o pacote é importado. nextpdf info aciona get_document_ast, a mesma chamada usada por nextpdf_get_ast e nextpdf_info. Se ambos forem bem-sucedidos, as credenciais e o endpoint estão corretos e as ferramentas MCP correspondentes funcionarão.

Para acionar o protocolo MCP diretamente, use o MCP Inspector do upstream (incluído no pacote mcp). Aponte-o para o mesmo comando e ambiente que o agente vai usar e, em seguida, liste e invoque as ferramentas manualmente. Verifique se nextpdf_health relata status: "ok". Ele retorna misconfigured sempre que NEXTPDF_BASE_URL ou NEXTPDF_API_KEY não estiver definida, o que é a forma mais rápida de detectar um valor de ambiente ausente antes que um agente chame uma ferramenta real.

Monitorar e depurar chamadas de ferramentas

O servidor MCP se comunica pela entrada/saída padrão (stdio), portanto a saída padrão carrega o fluxo do protocolo e deve permanecer limpa. O servidor não configura logging próprio da aplicação. Os principais canais de observabilidade são as cargas úteis estruturadas de erro de ferramenta, a CLI e os logs do próprio endpoint.

As cargas úteis de erro de ferramenta são o principal sinal. Toda chamada com falha retorna um objeto JSON com error e, para erros do SDK, error_type e status_code (consulte Tratamento de erros). Configure o host do agente para registrar essas cargas úteis. Elas identificam a ferramenta que falhou e a causa exata, sem instrumentação adicional no servidor.
Reproduza por meio da CLI com log de depuração. O próprio servidor MCP não emite logs, mas a CLI exercita as mesmas chamadas do SDK e gera logs. Reproduza uma ferramenta com falha por meio do comando da CLI correspondente com --log-level debug. A CLI grava logs em stderr com carimbos de data/hora e registra tracebacks completos para erros inesperados, o que é a forma mais direta de ver o que um manipulador está fazendo sem conectar um depurador.
Use health como sonda. Chame nextpdf_health para confirmar que o servidor consegue ler uma URL base e uma chave de API. O resultado informa sdk_version, server_url, api_key_configured (um booleano, nunca a própria chave) e status.
Observabilidade do lado do endpoint. Como cada ferramenta mapeia para uma requisição do Connect, correlacione a atividade das ferramentas com os logs de acesso do endpoint por chave de API e carimbo de data/hora. Execute o endpoint atrás dos mesmos controles de autenticação, cota e observabilidade que você usa para outros clientes de serviço.

Solução de problemas comuns de integração de agentes

Sintoma	Causa provável	Solução
O servidor não inicia e mostra um `ImportError` sobre o extra `mcp` opcional	A dependência opcional `mcp` não está instalada	Instale com `pip install nextpdf[mcp]`.
A primeira chamada de ferramenta retorna `{"error": "NEXTPDF_BASE_URL environment variable is required..."}`	O bloco `env` do MCP não forneceu a URL base, ou o shell não expandiu `${NEXTPDF_BASE_URL}`	Defina a variável no ambiente do host do agente e confirme que o iniciador a expande.
`nextpdf_health` reporta `"status": "misconfigured"`	Uma das duas variáveis obrigatórias está vazia	Forneça tanto `NEXTPDF_BASE_URL` quanto `NEXTPDF_API_KEY`.
Toda ferramenta baseada em caminho retorna `{"error": "PDF file not found: <path>"}`	O agente passou um caminho relativo ou de um host que o processo do servidor não consegue ver	Passe um caminho absoluto legível pelo usuário do servidor; confirme com `nextpdf info <path>`.
A ferramenta retorna `error_typeNextPDFLicenseError` (status 402)	A operação precisa de um nível de licença mais alto do lado do servidor	Use um endpoint e uma chave com autorização para a operação.
A ferramenta retorna `error_typeAstNoStructTreeError` (status 422)	O PDF não está marcado e o fallback heurístico está desativado	Habilite o modo heurístico no endpoint ou marque o PDF primeiro.
A ferramenta retorna `error_typeQuotaExceededError` (status 429)	Um limite de taxa ou cota foi atingido	Pause e tente novamente; aumente a cota do endpoint se o limite for muito baixo.
A ferramenta retorna `error_typeAstBuildTimeoutError` (status 504), ou um timeout de transporte	O documento é grande demais para o orçamento de tempo	Restrinja o escopo com `max_pages`, `page_index` ou `page_start`/`page_end`.
O agente não registra nenhuma ferramenta do NextPDF	O agente invocou `python -m nextpdf` (a CLI) em vez de `python -m nextpdf.mcp`	Use `python -m nextpdf.mcp` como o `command`/`args`.

Para falhas no nível do endpoint e verificações de implantação, consulte Solução de problemas do Connect. Para as operações do SDK encapsuladas por essas ferramentas, consulte a referência da CLI e a visão geral do SDK.