health.voaPublished by voa.healthOfficial publisherv0.3.0Updated Oct 29, 2026
Ferramentas para validar documentos TISS e consultar TUSS, operadoras e dados da ANS.
Remote MCP server for Brazilian TISS healthcare billing: validate, fix and build TISS batches, look up TUSS codes, operators and ANS data.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/health.voa%2Ftiss/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"voa-tiss": {
"type": "http",
"url": "https://tiss-api.voa.health/mcp"
}
}
}Valide, corrija e gere lotes TISS, entenda glosas e concilie demonstrativos, tudo em código aberto: uma biblioteca Python que roda offline, uma API HTTP e um MCP remoto para o seu agente de IA.
tiss valida o lote, consulta o procedimento cobrado e explica a glosa que voltou no demonstrativo, tudo offline. Para ver um agente fechando o ciclo, veja o agente faturista.
[!TIP] Usa Claude Code, Codex ou Cursor? Conecte o MCP e peça em português, por exemplo "valide este lote e corrija o que der". Veja Conectar agentes.
Cada achado traz um código estável, a localização e, quando possível, a correção pronta. Requer Python 3.10+.
Prefere testar no navegador? Abra o playground.
Instale a CLI com pip install tiss ou execute sem instalar com
uvx tiss validate lote.xml.
Os códigos de saída são 0 para sucesso, 1 para achados ou itens não
encontrados e 2 para uso inválido ou entrada ilegível. Para integração com
GitHub Actions, use tiss validate --format github lote.xml.
Você não precisa escrever XML TISS à mão. O ciclo é sempre o mesmo:
check ou validate.apply_fixes: as correções são determinísticas, em JSON Patch.needs diz exatamente
qual perguntar.build_lote e calcule o hash do epílogo com hash_epilogo.Depois do envio, parse_demonstrativo lê o retorno da operadora, glosa explica
cada código da Tabela 38 e plan_reconciliation concilia o que foi pago com o
que foi cobrado. Para testar sem operadora real, use a
operadora simulada.
https://tiss-api.voa.health, com OpenAPI.O MCP local roda offline e mantém as guias na máquina:
Para usar o serviço remoto:
Agentes encontram instruções em AGENTS.md e na skill tiss.
No Codex, adicione a ~/.codex/config.toml para o MCP local:
Para usar o serviço remoto:
No Cursor, adicione ao mcp.json para o MCP local:
Para usar o serviço remoto:
CLI, MCP local, Action e hook rodam na sua máquina ou runner, sem chave, registro
de uso ou telemetria. As chamadas de rede do pacote são feitas apenas por
ferramentas rede/D-TISS, que baixam dados públicos, e sandbox_*, que usam a
operadora simulada.
Use a Action para validar lotes no GitHub Actions:
O input opcional operadora aplica as regras locais dessa operadora. Para
instalar o hook, adicione ao .pre-commit-config.yaml:
A Action e o hook instalam apenas tiss (com lxml) e validam com os XSD 4.02.00
e 4.03.00 incluídos no pacote. Não instalam pdf nem baixam dados de rede/D-TISS;
fora o download do pacote, nada vai à rede. operadora aplica apenas regras
incluídas no pacote. O hook seleciona arquivos .xml; limite-o com files: se
o repositório tiver outros XML.
Instale o extra do servidor e inicie a API local:
Valide XML como JSON ou como corpo XML:
Consulte o OpenAPI e o catálogo de operações.
Sem chave, só as operações do sandbox respondem. Para as demais, crie a chave
sk_voa_ da organização, que vale para os produtos da Voa, no
painel da organização e envie-a em
Authorization: Bearer. Não há limite diário.
Chave inválida ou revogada retorna 401, e a revogação vale em até 60 segundos.
Chave sem o escopo da operação (tiss:validate, tiss:build, tiss:sandbox,
tiss:accounts, tiss:authorization ou tiss:rules) retorna 403. Cada
chamada com chave entra no uso da organização, por operação e por chave.
Auto-hospedado, sem TISS_BACKEND_URL e TISS_SERVICE_SECRET, o
servidor não exige chave.
O serviço não armazena nem registra payloads e não os usa para treinar modelos.
Quando ativada por POSTHOG_KEY, a telemetria agregada contém operação,
códigos de achados, registro ANS, versão TISS e data, sem e-mail. Envie
X-Voa-Telemetry: off para desativá-la. A biblioteca local permanece offline e
nunca envia telemetria. TISS_API_KEY é a variável que clientes HTTP locais
podem ler para enviar uma chave de acesso.
O mapa de rejeição hospedado é uma coleta separada, opt-in e desligada por padrão.
Quando habilitado no /org, envia somente agregados por prestador, código, regra e mês.
O payload do mapa usa a versão "2" e chaves em inglês; aceite apenas version: "2".
Essa quebra evita compatibilidade ambígua entre os contratos antigos e novos.
O payload contém version, lotes, guias, ignored, providers e rows;
as linhas usam provider, month, code, glosa, rule_id, guias e
affected_amount. Os resumos usam guias_with_finding e total_amount.
O CPF é pseudonimizado com HMAC e segredo próprio da organização antes de sair do cliente;
o CNPJ permanece em claro, e o código do prestador na operadora tem preferência.
A retenção é de 24 meses, e a organização pode desligar a coleta e apagar tudo no /org.
A telemetria anônima permanece independente e não muda com esse aceite.
Na CLI, mapa --enviar usa TISS_KEY e envia ao servidor público.
TISS_MAPA_URL substitui a URL de envio (padrão:
https://tiss-api.voa.health/v1/rejection-map/submit). Sem
TISS_SEGREDO_PSEUDONIMO, a CLI busca o segredo antes de agregar, via
GET /v1/rejection-map/config, no mesmo servidor e com Bearer sk_voa_.
O envio usa POST /v1/rejection-map/submit, com o mapa agregado como corpo JSON.
Para renderizar a guia SP/SADT em PDF, instale pip install "tiss[pdf]".
tiss.rede baixa e verifica os dados na primeira consulta. Defina
TISS_REDE com o caminho de um SQLite local para usar uma cópia própria.
tiss.referencia consulta valores unitários de referência da ANS por TUSS, UF e
semestre; o valor pago é somente o pago diretamente ao fornecedor, não o total
pago pela operadora. Defina TISS_REFERENCIA para usar um SQLite local.
Source: README.md at commit 76db67c
Valida XML TISS ou lote em JSON. Quando usar: antes de gerar ou enviar um lote. Quando não usar: para corrigir achados sem aplicar o ciclo validar → tiss_apply_fixes → validar de novo.
xmldatalotecontextooperadoraLê decisões de um demonstrativo. Quando usar: para identificar pagamentos e glosas. Quando não usar: para validar lotes.
xmlrequiredPropõe vínculos entre decisões e guias. Quando usar: após ler um demonstrativo. Quando não usar: para alterar guias.
guiasrequiredid_keydecisoesrequiredstatus_keyoperadora_keyprestador_keyBusca um código TUSS exato. Quando usar: para consultar código ou vigência. Quando não usar: para buscar por descrição.
coderequireddatatabelainclude_expiredBusca códigos TUSS por texto. Quando usar: para localizar procedimentos por descrição. Quando não usar: para validar XML.
datatextrequiredlimitetabelainclude_expiredIdentifica campos obrigatórios SP/SADT ausentes. Quando usar: antes de renderizar uma guia. Quando não usar: para validar um lote.
valuesrequiredRetorna o catálogo SP/SADT. Quando usar: para conhecer campos e domínios. Quando não usar: para preencher uma guia sem dados.
Takes no parameters.
Consulta as operadoras vinculadas a um CNPJ ou CNES. Quando usar: para identificar vínculos de um estabelecimento. Quando não usar: para buscar o cadastro geral; use operadora_lookup.
cnescnpjlimiteConsulta os estabelecimentos vinculados a uma operadora. Quando usar: para identificar unidades da rede por UF. Quando não usar: para buscar o cadastro geral; use operadora_lookup.
uflimiteregistrorequiredConsulta o cadastro e a série semestral de glosa e pagamento de uma operadora na ANS. Quando usar: para conhecer uma operadora pelo registro ANS. Quando não usar: para buscar operadoras por nome.
registro_ansrequiredEnvia um lote à operadora simulada. Quando usar: para testar integração local. Quando não usar: para transmitir dados reais.
xmlrequiredcenariotentativaregistro_ansGera o demonstrativo de um protocolo simulado. Quando usar: após enviar um lote. Quando não usar: com protocolo de outra operadora.
protocolorequiredGera o XML TISS 4.03.00 de um lote em JSON, com hash do epílogo. Consulte tiss://schemas/lote para o esquema estrutural. Quando usar: depois de validar o lote em JSON sem erros. Quando não usar: para corrigir achados; use tiss_apply_fixes.
loterequiredCalcula o hash do epílogo de um XML TISS. Quando usar: para conferir a integridade do XML. Quando não usar: para validar o conteúdo; use tiss_validate.
xmlrequiredAudita um lote JSON com regras locais e contexto da operadora. Quando usar: para identificar inconsistências administrativas. Quando não usar: para aplicar correções; use tiss_apply_fixes.
dataloterequiredcontextooperadoraAgrega achados por prestador e mês, sem expor dados das guias; CPF é pseudonimizado. Quando usar: para analisar rejeições por prestador. Quando não usar: para consultar guias individuais ou corrigir lotes.
datalotesrequiredregrascontextooperadorasegredo_pseudonimoAplica correções JSON Patch de um relatório ao lote. Quando usar: depois de tiss_validate ou tiss_audit com achados corrigíveis. Quando não usar: para inventar dados ausentes; peça-os ao usuário.
loterequiredreportrequiredExplica um código da Tabela 38 da ANS. Quando usar: ao interpretar uma glosa recebida. Quando não usar: para validar ou corrigir o lote.
codigorequiredConsulta tabelas e códigos de domínio TISS. Quando usar: para localizar um código ou termo de domínio. Quando não usar: para buscar procedimentos TUSS; use tuss_search.
datatextocodigolimitetabelainclude_expiredBusca operadoras ativas pelo nome, registro, CNPJ ou localidade. Quando usar: para localizar uma operadora na base pública. Quando não usar: para consultar vínculos hospitalares; use tiss_rede.
textorequiredlimiteConsulta valores unitários de referência D-TISS da ANS por procedimento TUSS. Quando usar: para comparar valores informados por UF, modalidade, porte e semestre. Quando não usar: para glosa ou preço contratado de uma operadora; use as ferramentas de operadoras.
ufrequiredportecodigorequiredtabelasemestremodalidadeGera XML TISS 4.03.00 para solicitação ou resposta de autorização SP/SADT.
mensagemrequiredInterpreta solicitações e respostas de autorização SP/SADT.
xmlrequiredValida uma solicitação SP/SADT e retorna uma decisão explicável.
xmlcontextosolicitacaoGera uma resposta SP/SADT sintética nos cenários disponíveis.
xmlcenariosolicitacaoBusca trechos da documentação local da biblioteca. Quando usar: para encontrar instruções e referências da API. Quando não usar: para consultar dados clínicos ou códigos específicos.
textorequiredlimite100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
pip install tissfrom tiss import examples, validate
report = validate(examples.load("lote-com-erros"))[(finding.code, finding.severity) for finding in report.findings]claude mcp add tiss -- uvx --from "tiss[mcp]" tiss mcpclaude mcp add --transport http tiss https://tiss-api.voa.health/mcpnpx skills add Voa-Health/tissclaude plugin marketplace add Voa-Health/tiss && claude plugin install tiss@tisscodex plugin marketplace add Voa-Health/tiss[mcp_servers.tiss]command = "uvx"args = ["--from", "tiss[mcp]", "tiss", "mcp"][mcp_servers.tiss]url = "https://tiss-api.voa.health/mcp"{ "mcpServers": { "tiss": { "command": "uvx", "args": ["--from", "tiss[mcp]", "tiss", "mcp"] } }}{ "mcpServers": { "tiss": { "url": "https://tiss-api.voa.health/mcp" } }}- uses: Voa-Health/tiss@v0 with: paths: lotes/repos: - repo: https://github.com/Voa-Health/tiss rev: v0.5.0 hooks: - id: tiss-validatepip install "tiss[server]"tiss serve --host 127.0.0.1 --port 8000python -c 'import json, pathlib; print(json.dumps({"xml": pathlib.Path("lote.xml").read_text()}))' \ | curl https://tiss-api.voa.health/v1/validate \ -H 'Content-Type: application/json' \ --data-binary @-curl https://tiss-api.voa.health/v1/validate \ -H 'Content-Type: application/xml' \ --data-binary @lote.xmlcurl https://tiss-api.voa.health/v1/validate \ -H "Authorization: Bearer $TISS_API_KEY" \ -H 'Content-Type: application/xml' \ --data-binary @lote.xml