Backwork

Políticas de cobertura de pagadores Medicare e comerciais, consulta de códigos médicos, pesquisa de autorização prévia e validação de sinistros com fontes citadas.

GitHub

Experimente este MCPPatrocinado

Servidor MCP hospedado

npx add-mcp 'https://backworkhealth.com/mcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

Servidor MCP Backwork

Servidor oficial do Model Context Protocol (MCP) para a API Backwork. Ele dá a assistentes de IA acesso controlado a políticas médicas do Medicare e de planos de saúde, inteligência de códigos médicos, verificações de autorização prévia, validação de sinistros, revisão de conformidade, evidências de formulários de medicamentos e operações de webhook.

Existem duas formas de conectar:

	Remoto hospedado	Stdio local
Endpoint	`https://backworkhealth.com/mcp` (HTTP Streamable)	`npx -y @backwork/mcp`
Autenticação	OAuth no navegador, sem chave para copiar	`BACKWORK_API_KEY=bwk_live_...`
Use quando	Seu cliente suporta MCP remoto com OAuth	Seu cliente só executa comandos locais, ou você quer o servidor na sua máquina

O endpoint hospedado só aceita OAuth. Não envie uma chave de API Backwork como token de portador para https://backworkhealth.com/mcp. A concessão OAuth é somente leitura (backwork:mcp read), então o servidor hospedado oferece apenas ações de leitura: sem gerenciamento de webhooks e sem confirmações de conformidade. Use stdio local com uma chave ativa com escopo de escrita para essas ações.

As chamadas consomem os créditos de solicitação da sua organização, como qualquer outra chamada /api/v1. Uma chave bwk_test_ funciona apenas no sandbox (https://backworkhealth.com/api/sandbox/v1), que cobre busca de políticas, consulta de códigos, verificação de autorização prévia e avaliação de cobertura; para usá-la, defina BACKWORK_API_BASE para essa URL.

Claude Code

claude mcp add backwork --transport http https://backworkhealth.com/mcp

Adicione --scope user para disponibilizá-lo em todos os projetos. Em seguida, execute claude, abra /mcp, selecione backwork e conclua o login no navegador e a tela de consentimento da Backwork. Verifique com claude mcp get backwork.

Se a descoberta OAuth precisar ser fixada explicitamente, adicione o mesmo servidor como JSON:

claude mcp add-json backwork '{
  "type": "http",
  "url": "https://backworkhealth.com/mcp",
  "oauth": {
    "scopes": "backwork:mcp read"
  }
}'

Stdio local:

claude mcp add backwork -e BACKWORK_API_KEY=bwk_live_YOUR_API_KEY -- npx -y @backwork/mcp

Claude Desktop

Remoto hospedado: abra Configurações > Conectores > Adicionar conector personalizado, nomeie-o como Backwork e insira https://backworkhealth.com/mcp. O Claude Desktop executa o login OAuth quando você conecta.

Stdio local: adicione isto a claude_desktop_config.json (Configurações > Desenvolvedor > Editar Config) e reinicie o Claude Desktop:

{
  "mcpServers": {
    "backwork": {
      "command": "npx",
      "args": ["-y", "@backwork/mcp"],
      "env": {
        "BACKWORK_API_KEY": "bwk_live_YOUR_API_KEY"
      }
    }
  }
}

Cursor

Adicione a ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (um projeto). O Cursor abre o login OAuth na primeira vez que conecta:

{
  "mcpServers": {
    "backwork": {
      "url": "https://backworkhealth.com/mcp"
    }
  }
}

Stdio local:

{
  "mcpServers": {
    "backwork": {
      "command": "npx",
      "args": ["-y", "@backwork/mcp"],
      "env": {
        "BACKWORK_API_KEY": "bwk_live_YOUR_API_KEY"
      }
    }
  }
}

VS Code

code --add-mcp '{"name":"backwork","type":"http","url":"https://backworkhealth.com/mcp"}'

Ou adicione a .vscode/mcp.json em um workspace. O VS Code pede que você faça login quando o servidor inicia:

{
  "servers": {
    "backwork": {
      "type": "http",
      "url": "https://backworkhealth.com/mcp"
    }
  }
}

Stdio local, com a chave solicitada uma vez e armazenada pelo VS Code:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "backwork-api-key",
      "description": "Backwork API key",
      "password": true
    }
  ],
  "servers": {
    "backwork": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@backwork/mcp"],
      "env": {
        "BACKWORK_API_KEY": "${input:backwork-api-key}"
      }
    }
  }
}

Codex

codex mcp add backwork --env BACKWORK_API_KEY=bwk_live_YOUR_API_KEY -- npx -y @backwork/mcp

Uso no ChatGPT

O ChatGPT conecta-se ao servidor hospedado como uma conexão MCP personalizada no modo desenvolvedor. Três ferramentas retornam um pequeno cartão que o ChatGPT renderiza inline acima da resposta.

No ChatGPT, abra Configurações → Segurança e login e ative o Modo desenvolvedor. Seu plano ou administrador do workspace pode precisar permitir.
Vá para chatgpt.com/plugins e selecione o botão +.
Nomeie-o como Backwork, adicione uma descrição curta e, em Conexão, insira https://backworkhealth.com/mcp. Escolha OAuth para autenticação.
Selecione Criar. O ChatGPT abre a página de login da Backwork; aprove a concessão somente leitura backwork:mcp read.
Verifique as ferramentas descobertas, inicie um novo chat, adicione Backwork no menu de ferramentas e pergunte algo como "O CPT 76942 é coberto no Texas e precisa de autorização prévia?"

Após uma atualização do servidor, abra a conexão em chatgpt.com/plugins e selecione Atualizar para que o ChatGPT capture novos metadados de ferramentas e componentes.

Ferramenta	Cartão	O que mostra
`backwork_coverage_lookup`	Resultado de cobertura	Cada política que lista os códigos: pagador (`CMS` para políticas do Medicare), título e número, data de vigência, uma linha por código com seu selo de disposição e rótulo de fonte, e um link Abrir política para a página Backwork da política (LCDs, Artigos e NCDs do Medicare) ou, para outras políticas, seu documento de origem
`backwork_prior_auth_research`	Checklist de autorização prévia	A determinação e confiança, códigos que exigem autorização prévia, documentação a reunir, lacunas conhecidas e citações numeradas. Uma tarefa de pesquisa iniciada mostra como pendente até você perguntar novamente
`backwork_policy_research`	Pesquisa de políticas	Por ação: `compare` mostra os códigos lado a lado entre os contratantes do Medicare (MACs), uma coluna por jurisdição, com a disposição e política de cada célula e uma contagem de cobertura por coluna; `search` lista as políticas correspondentes com pagador, número, data de vigência, um resumo curto e um link; `get` mostra o resumo de uma política, um trecho de critérios por seção e seus códigos; `criteria` lista os trechos de critérios correspondentes com suas políticas; `changes` lista alterações recentes; `jurisdictions` lista cada MAC e seus estados

O ChatGPT carrega o cartão de uma ferramenta a cada chamada dessa ferramenta. Um resultado sem nada para mostrar, como uma busca sem correspondências ou um erro, recolhe o cartão para altura zero e pede ao ChatGPT para fechá-lo, para que nenhum cartão vazio fique na conversa.

Um código que uma política lista apenas porque seu título nomeia o medicamento é rotulado como Inferido do título da política, no cartão e no texto. Confirme-o contra o documento antes de confiar nele.

Os cartões seguem o tema claro ou escuro do ChatGPT, não carregam nada da rede (sua CSP não permite domínios) e abrem links pelo host. Eles são recursos de MCP Apps (text/html;profile=mcp-app), então outros hosts de MCP Apps também podem renderizá-los. Clientes sem suporte a UI ignoram as chaves _meta que vinculam ferramentas a cartões e obtêm o mesmo texto markdown de antes; structuredContent.widget carrega os dados do cartão.

Outros Clientes MCP

Clientes que executam comandos locais podem usar a configuração stdio mostrada para Claude Desktop. Clientes que suportam URLs remotas com OAuth podem usar https://backworkhealth.com/mcp diretamente.

Para clientes que suportam apenas URLs remotas com cabeçalhos estáticos, implante um servidor privado auto-hospedado no modo chave de API ou autenticação dupla (veja Auto-Hospedagem) e envie a chave como cabeçalho de portador:

{
  "mcpServers": {
    "backwork": {
      "url": "https://your-private-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer bwk_live_YOUR_API_KEY"
      }
    }
  }
}

Auto-Hospedagem

Execute um servidor HTTP Streamable:

git clone https://github.com/tylergibbs1/backwork-mcp.git
cd backwork-mcp
npm install
npm run build
npm run start:http

Padrões:

Configuração	Padrão	Substituição
Transporte	`stdio`	`--http` ou `BACKWORK_MCP_TRANSPORT=http`
Host	`127.0.0.1`	`--host` ou `BACKWORK_MCP_HOST`
Porta	`3000`	`--port` ou `BACKWORK_MCP_PORT` ou `PORT`
Caminho MCP	`/mcp`	`--path` ou `BACKWORK_MCP_PATH`
Hosts permitidos	loopback/hosts privados, `VERCEL_URL`, ou host público configurado	`BACKWORK_MCP_ALLOWED_HOSTS` ou `BACKWORK_MCP_PUBLIC_HOST`

O modo HTTP exige Authorization: Bearer por solicitação. Por padrão, este portador é uma chave de API Backwork. Para implantações MCP remotas hospedadas, habilite a descoberta de recursos protegidos OAuth para que clientes compatíveis com Claude possam autenticar usuários através do seu servidor de autorização:

BACKWORK_MCP_AUTH_MODE=oauth \
BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS=https://backworkhealth.com \
BACKWORK_MCP_OAUTH_SCOPES="backwork:mcp read" \
npm run start:http

O servidor publica Metadados de Recursos Protegidos OAuth em /.well-known/oauth-protected-resource e inclui essa URL em desafios WWW-Authenticate. Se sua API Backwork aceita tokens de acesso OAuth diretamente, nenhum mapeamento extra é necessário; o servidor MCP encaminha o portador OAuth downstream. Se seu servidor de autorização expõe uma chave de API Backwork na introspecção de token, defina BACKWORK_MCP_OAUTH_INTROSPECTION_URL e BACKWORK_MCP_OAUTH_API_KEY_CLAIM para validar o token de acesso e mapeá-lo para a credencial Backwork downstream.

Para uma implantação privada de locatário único onde o ambiente do servidor fornece a chave, defina:

BACKWORK_MCP_ALLOW_ENV_KEY=true BACKWORK_API_KEY=bwk_live_YOUR_API_KEY npm run start:http

Use BACKWORK_MCP_ALLOW_ENV_KEY=true apenas em implantações de loopback ou rede privada protegidas por controle de acesso de rede. Implantações públicas devem exigir um token de portador por solicitação, definir BACKWORK_MCP_ALLOWED_HOSTS/BACKWORK_MCP_PUBLIC_HOST e definir BACKWORK_MCP_ALLOWED_ORIGINS apenas para origens exatas de navegador que possam conectar.

Hospedagem Vercel

Este repositório pode ser implantado como um projeto Vercel somente API. O projeto de produção usa:

BACKWORK_MCP_AUTH_MODE=oauth
BACKWORK_MCP_PUBLIC_HOST=backworkhealth.com
BACKWORK_MCP_PUBLIC_URL=https://backworkhealth.com
BACKWORK_MCP_ALLOWED_HOSTS=backworkhealth.com,mcp.backworkhealth.com,backwork-mcp.vercel.app
BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS=https://backworkhealth.com
BACKWORK_MCP_OAUTH_RESOURCE=https://backworkhealth.com/mcp
BACKWORK_MCP_OAUTH_SCOPES="backwork:mcp read"
BACKWORK_MCP_OAUTH_REQUIRED_SCOPES=backwork:mcp
BACKWORK_MCP_OAUTH_INTROSPECTION_URL=https://backworkhealth.com/api/oauth/introspect
BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE=https://backworkhealth.com/mcp

As funções Vercel expõem:

Caminho	Finalidade
`/mcp`	Endpoint MCP HTTP Streamable
`/health`	Verificação de saúde leve do servidor MCP
`/.well-known/oauth-protected-resource`	Metadados de recursos protegidos OAuth quando OAuth está configurado
`/`	Metadados básicos do endpoint

O aplicativo web Backwork que emite tokens OAuth também deve ser configurado:

BACKWORK_OAUTH_ISSUER=https://backworkhealth.com
BACKWORK_OAUTH_SIGNING_SECRET=<generate with: openssl rand -base64 48>
BACKWORK_MCP_RESOURCE=https://backworkhealth.com/mcp

A descoberta OAuth de produção falha fechada a menos que BACKWORK_OAUTH_SIGNING_SECRET tenha pelo menos 32 caracteres e Redis ou Vercel KV esteja configurado para armazenamento de consentimento único e código de autorização.

Verificação de saúde:

curl http://localhost:3000/health

Desenvolvimento Local

npm install
npm run build
BACKWORK_API_KEY=bwk_live_YOUR_API_KEY npm start

Comandos úteis:

npm run start:http
node build/src/index.js --help

Requer Node.js 18.14.1 ou mais recente.

Ferramentas Disponíveis

Os nomes das ferramentas usam o prefixo backwork_ para descoberta quando este servidor está instalado junto com outros servidores MCP. A superfície padrão é intencionalmente em nível de fluxo de trabalho, em vez de um wrapper de API 1:1, para que os agentes vejam menos opções e tarefas comuns exijam menos chamadas de ferramenta.

Todas as ferramentas incluem title, description, inputSchema, outputSchema e anotações MCP. Cada ferramenta declara suas próprias anotações; o servidor se recusa a iniciar se uma ferramenta marcada como somente leitura oferecer uma operação de escopo de escrita, ou uma marcada como não destrutiva oferecer um DELETE. Chamadas bem-sucedidas retornam texto legível mais structuredContent com message e, quando disponível, data e meta da API Backwork.

data e meta são projeções: carregam apenas os campos de resposta que src/api-operations.ts lista para a operação (reads e metaReads). IDs de solicitação, carimbos de tempo de resposta, carimbos de tempo de registro, custo de trabalho de pesquisa e URLs de polling, chaves de idempotência e nomes de modelo são descartados. Datas de vigência e última revisão da política, tempos de busca de fonte e tempos de amostra de auditoria de fonte são mantidos. O servidor registra o ID de solicitação de uma chamada de API com falha.

Falhas em nível de ferramenta retornam isError: true. Falhas de cobrança e limite de taxa são relatadas em termos simples e nunca repetem a dica da API, nomes de planos ou links de preços: um recurso fora do plano da organização, sem créditos de solicitação restantes ou um limite de taxa com quando tentar novamente. test/output-guard.test.mjs executa cada ação de ferramenta contra respostas de fixture e esses erros, e falha em texto de upsell, IDs de rastreamento, carimbos de tempo, custo ou campos de modelo.

Fontes e atualidade

Quando a resposta da API Backwork cita documentos de política, structuredContent.provenance carrega o que um agente precisa para citá-los, e a saída de texto termina com um bloco curto --- Sources ---:

Campo	Significado
`source_urls`	URLs distintas de documentos de origem
`authorities`	Autoridades emissoras, por exemplo `CMS` ou um nome de pagador
`retrieved_at`	Tempo de busca mais antigo quando cada fonte citada tem um tempo conhecido; caso contrário, `null`
`as_of`	Data de vigência mais recente entre as fontes citadas
`sources[]`	`policy_id`, `source_url`, `authority`, `retrieved_at`, `as_of` por fonte

Os valores vêm da resposta da API. source_check.source_url e source_check.last_fetched_at têm precedência sobre metadados de fonte legados. Um tempo de busca desconhecido explícito permanece null; retrieved_at legado, last_verified_at ou crawled_at são valores de fallback apenas quando o bloco de verificação de fonte está ausente. Tempos de busca conhecidos permanecem disponíveis em sources[] quando outra fonte citada tem um tempo desconhecido. A forma corresponde ao bloco provenance nos resultados de ferramenta do agente Backwork.

A evidência de política também retém o source_check da API: URL da fonte, último tempo de busca, SHA-256 do conteúdo buscado e amostras de auditoria source_accuracy. Cada auditoria relata o campo medido, data e tamanho da amostra, proporção de registros amostrados que corresponderam, intervalo Wilson de 95% e método. Estas amostras medem registros de uma fonte; elas não medem certeza para a política individual ou uma decisão de cobertura. Auditorias ausentes permanecem null. Os cartões mostram datas de busca e amostras de auditoria de fonte expansíveis. Políticas com aplicabilidade explícita também mantêm os campos opcionais applicability_scope, applicability_markets, applicability_evidence e applicability_note. Documentos de mercado compartilhado e documentos singleton indexados são listados nos índices de estado do editor; essa evidência de descoberta não estabelece a cobertura do plano ou produto do membro. Uma política document_scoped sem estado, linha de negócio ou mercados indexados tem aplicabilidade desconhecida. Os cartões e textos mostram a nota da API, e os cartões fornecem links de índice do editor e citações exatas da fonte com números de página. Respostas legadas sem esses campos mantêm sua forma existente.

A evidência de aplicabilidade é limitada a um SHA-256 do documento, até 16 listagens de índice HTTPS do editor e até 16 declarações dos três tipos suportados (non_medicare_disclaimer, commercial_policy_header, member_type_branch). As citações são limitadas a 4.000 caracteres, URLs de índice a 2.048 caracteres, e as páginas devem ser inteiros positivos. Campos desconhecidos são descartados; evidências malformadas tornam-se null. Códigos de mercado e notas também são limitados. O MCP preserva a confiança da API e as saídas de revisão manual; listagens de índice não aumentam a confiança nem resolvem autorização.

Correspondências de código mantêm grounding separadamente de sua extração source:

`grounding`	Significado
`grounded`	Encontrado no texto-fonte retido da Backwork
`not_grounded`	Lido pelo pipeline de documentos, mas não encontrado no texto-fonte retido
`no_source_text`	Nenhum texto retido estava disponível para verificação
`not_checked`	A fundamentação não foi verificada, incluindo códigos inferidos de um título de política

Textos e cartões rotulam essas verificações sem tratar um código fundamentado como garantia de cobertura. Uma resposta mais antiga que omite a fundamentação permanece desconhecida, e um valor futuro não reconhecido é preservado e rotulado.

Disponibilidade de produção

Quais ações um servidor oferece depende de duas coisas:

Disponibilidade. O documento OpenAPI da Backwork pode marcar uma operação como x-backwork-availability: unavailable-in-production. Contra a API de produção (https://backworkhealth.com), o servidor retém essas ações. Nenhuma está marcada hoje: a produção atende a todas as operações /api/v1 que essas ferramentas chamam com a chave ativa de uma organização.
Acesso. Operações que precisam do escopo write (x-backwork-required-scopes) são retidas de uma concessão OAuth somente leitura. No servidor hospedado, isso oculta backwork_webhook_management e as ações acknowledge e bulk_acknowledge de backwork_compliance_review. Uma conexão somente leitura também não recebe diagnósticos backwork_system_health, nenhuma entrada idempotency_key em backwork_claim_validation, e um backwork_compliance_review sem entradas de confirmação (diff_id, diff_ids, notes) e sem IDs de diff em seus resultados. Uma chave de API da Backwork (stdio, ou HTTP com um bearer bwk_) recebe todas as ferramentas e ações, e a API aplica os próprios escopos da chave. Uma concessão OAuth conta como somente leitura, a menos que seus escopos incluam write.

Uma ferramenta sem ação oferecida fica oculta. Uma ferramenta parcialmente oferecida remove as ações retidas de sua entrada action; ações retidas como indisponíveis em produção também são nomeadas em sua descrição. Um servidor apontado para outra implantação da Backwork com BACKWORK_API_BASE ignora marcadores de disponibilidade, e BACKWORK_MCP_EXPOSE_UNAVAILABLE_TOOLS=true faz o mesmo contra produção. Nenhum dos dois remove a regra de escopo de escrita.

Ferramenta primária	Finalidade
`backwork_coverage_lookup`	Consultar códigos de procedimento e combinar detalhes de código, evidência de política, autorização prévia, risco de sinistro, comparação de jurisdição e evidência de gastos. Com `payer`, os detalhes de código listam apenas as políticas desse pagador e informam quantas políticas de outros pagadores foram omitidas
`backwork_policy_research`	Pesquisar políticas, buscar uma política, pesquisar critérios extraídos, revisar mudanças de política, mapear jurisdições MAC ou comparar como os MACs cobrem os mesmos códigos
`backwork_claim_validation`	Validar cobertura de sinistro, requisitos de documentação, risco de negação e critérios opcionais específicos de política
`backwork_prior_auth_research`	Verificar autorização prévia nas políticas da Backwork (Medicare ou de um pagador nomeado), ou iniciar e consultar um trabalho em segundo plano que pesquisa sites públicos de pagadores
`backwork_drug_formulary_research`	Pesquisar evidências comerciais de benefícios de farmácia da CVS Caremark, Express Scripts e UnitedHealthcare / Optum Rx
`backwork_compliance_review`	Revisar estatísticas de conformidade e listar mudanças de política não revisadas; com uma chave de API, também confirmar mudanças
`backwork_webhook_management`	Listar, criar, atualizar, excluir ou testar endpoints de webhook. A Backwork envia um evento, `compliance.acknowledged`; webhooks de mudança de política não são enviados. Requer uma chave de API com escopo de escrita
`backwork_system_health`	Verificar a saúde da API da Backwork e o status de dependências. Somente conexões com chave de API

Formato de Resposta

Toda ferramenta aceita:

{
  "response_format": "markdown"
}

Use "markdown" para saída legível ou "json" para fazer o conteúdo de texto espelhar o structuredContent retornado.

Exemplos de Prompts

Is CPT 76942 covered in Texas, and does it require prior authorization?

Compare coverage for J0585 across JM and JH.

Validate denial risk for 99213 with diagnosis E11.9 for Medicare in Texas.

Search formulary evidence for Ozempic across commercial PBMs.

Testes e Avaliações

Execute o build e o teste de fumaça de metadados MCP:

npm test

O teste de fumaça inicia o servidor stdio construído com uma chave fictícia, verifica as 8 ferramentas de fluxo de trabalho, confere títulos, esquemas, anotações, esquemas de saída, response_format e verifica se falhas locais de validação são relatadas com isError: true. O teste de fumaça HTTP também conclui a inicialização MCP autenticada, lista as ferramentas da concessão de leitura e chama uma ferramenta com argumentos inválidos. A suíte test/ cobre disponibilidade de produção, o conjunto de ferramentas somente leitura e somente OAuth do servidor hospedado, proveniência, qualidade de descrição e uma verificação lexical de seleção de ferramentas (sem chamadas de modelo), o manifesto do registro e os cartões do ChatGPT: seus modelos na lista de ferramentas, os recursos e o tipo MIME, o structuredContent de cada cartão contra seu esquema, markdown para clientes sem UI e uma renderização de cada página de cartão em um navegador simulado para cada ação de cada ferramenta com cartão, que deve mostrar um cartão ou colapsar para altura zero.

Antes de publicar, execute npm run verify:package. Ele instala o tarball empacotado em um consumidor temporário sem substituições de repositório ou lockfile, e então executa ambos os transportes no runtime atual e no Node 18.20.8. O CI executa a mesma verificação. Versões exatas adicionais do Node podem ser passadas após --.

Contrato da API

Todo endpoint da Backwork que este servidor chama está listado em src/api-operations.ts, com os campos de requisição que envia e os campos de resposta que lê. As ferramentas só podem chamar a API por meio desse catálogo. Cada entrada também espelha o marcador de disponibilidade da operação e o escopo exigido. npm test verifica o catálogo contra o openapi/backwork-openapi.json fornecido, e pergunta à própria regra de exposição do servidor quais ações de ferramenta ele ofereceria em produção, para uma concessão OAuth somente leitura e para uma chave de API. Uma ação oferecida para uma operação que a produção não atende, marca como indisponível ou (para a concessão OAuth) protege com escopo write falha.

O CI executa npm run contract:live, que executa as mesmas verificações contra https://backworkhealth.com/openapi.json e falha quando a cópia fornecida difere dela em qualquer lugar, exceto descrições, resumos e exemplos.

Quando a API da Backwork muda, atualize a cópia fornecida e revise o diff:

npm run openapi:update
npm run contract:check

O diretório evals/ inclui uma avaliação de descobribilidade de ferramentas e uma avaliação de dados somente leitura construída a partir de registros fixos de política/código com suporte de fonte. Atualize as respostas somente leitura intencionalmente quando os dados de fonte da Backwork forem atualizados.

Acompanhamento da migração do SDK

A versão 2.1.4 inclui o SDK v1 1.32.1, Zod e suas dependências de produção a partir do lockfile confirmado. Isso leva o adaptador Node Hono corrigido 1.19.15 para instalações de consumidores e preserva o suporte ao Node 18 (mínimo 18.14.1). O npm só honra substituições no pacote raiz do consumidor, então uma substituição neste pacote não pode fornecer essa garantia. Use npm ci para reproduzir a árvore de lançamento e reexecutar a verificação de pacotes após atualizar o lockfile. O guia oficial de migração v2 requer uma mudança de compatibilidade separada:

Elevar o runtime Node.js suportado de 18 para pelo menos 20, incluindo a implantação hospedada e o fluxo de trabalho de lançamento.
Substituir importações monolíticas do SDK por @modelcontextprotocol/server, @modelcontextprotocol/node para transporte HTTP Node e @modelcontextprotocol/client para clientes e testes; use @modelcontextprotocol/core para esquemas de protocolo público quando necessário.
Atualizar o intervalo declarado do Zod para pelo menos 4.2 e envolver esquemas de entrada/saída de ferramentas como objetos Standard Schema, preservando descrições de campos e validação de saída estruturada.
Verificar descoberta de ferramentas, stdio, ciclo de vida HTTP sem estado, descoberta e escopos OAuth, widgets, minimização de saída e o contrato OpenAPI ao vivo antes de publicar essa migração.

Registro MCP

server.json descreve este servidor para o registro oficial MCP como io.github.tylergibbs1/backwork-mcp: o remoto Streamable HTTP hospedado em https://backworkhealth.com/mcp (OAuth, descoberto a partir dos metadados do recurso protegido) e o pacote npm @backwork/mcp via stdio. package.json carrega o mcpName correspondente que o registro usa para verificar a propriedade do npm. npm test valida server.json contra o esquema do registro e verifica se suas versões correspondem a package.json.

Lançamento

Os lançamentos publicam @backwork/mcp no npm com Publicação Confiável (GitHub OIDC, sem token npm) e depois publicam server.json no registro MCP.

npm version minor (ou patch/major). O script version copia a nova versão para server.json e SERVER_VERSION em src/index.ts.
Mesclar essa mudança em main.
Enviar uma tag correspondente de main, por exemplo git tag v2.1.0 && git push origin v2.1.0.

O fluxo de trabalho Release então:

Falha a menos que a tag seja igual a v + a versão package.json.
Executa npm ci, npm test (build, testes de fumaça, testes unitários, contrato OpenAPI), npm run verify:package (consumidor limpo e transportes Node 18) e npm pack --dry-run.
Publica no npm com proveniência, no ambiente npm. Uma versão já existente no npm é ignorada, então uma execução com falha pode ser reexecutada.
Aguarda a versão aparecer no npm e então executa mcp-publisher login github-oidc e mcp-publisher publish.

Configuração única do npm: em npmjs.com, abra @backwork/mcp > Configurações > Publicação confiável, escolha GitHub Actions e insira o usuário tylergibbs1, repositório backwork-mcp, fluxo de trabalho release.yml, ambiente npm.

Variáveis de Ambiente

Variável	Obrigatória	Descrição
`BACKWORK_API_KEY`	Stdio sim; HTTP não	Chave da API Backwork. No modo HTTP, prefira `Authorization: Bearer` por requisição.
`BACKWORK_API_BASE`	Não	Substitui a URL base da API.
`BACKWORK_MCP_TRANSPORT`	Não	`stdio` ou `http`.
`BACKWORK_MCP_HOST`	Não	Host de bind HTTP. O padrão é `127.0.0.1`.
`BACKWORK_MCP_PORT`	Não	Porta de bind HTTP.
`BACKWORK_MCP_PATH`	Não	Caminho MCP HTTP.
`BACKWORK_MCP_ALLOWED_ORIGINS`	Não	Origens HTTP permitidas separadas por vírgula. Origens de loopback são permitidas para requisições de loopback.
`BACKWORK_MCP_ALLOW_ORIGIN`	Não	Alias compatível com versões anteriores para `BACKWORK_MCP_ALLOWED_ORIGINS`.
`BACKWORK_MCP_ALLOWED_HOSTS`	Não	Cabeçalhos Host HTTP permitidos separados por vírgula para implantações públicas.
`BACKWORK_MCP_ALLOW_HOST`	Não	Alias compatível com versões anteriores para `BACKWORK_MCP_ALLOWED_HOSTS`.
`BACKWORK_MCP_PUBLIC_HOST`	Não	Host público principal permitido para requisições HTTP.
`BACKWORK_MCP_PUBLIC_URL`	Não	Origem pública canônica para metadados OAuth, ex.: `https://backworkhealth.com`.
`BACKWORK_MCP_ALLOW_ENV_KEY`	Não	Permite requisições HTTP privadas sem autenticação bearer para usar `BACKWORK_API_KEY`.
`BACKWORK_MCP_AUTH_MODE`	Não	Modo bearer HTTP: `api-key`, `oauth` ou `dual`. O padrão é `dual` quando servidores de autorização OAuth estão configurados, caso contrário `api-key`.
`BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS`	OAuth	URLs de emissor / servidor de autorização OAuth separadas por vírgula, anunciadas nos metadados de recurso protegido.
`BACKWORK_MCP_OAUTH_RESOURCE`	Não	Substitui o identificador de recurso RFC 8707. O padrão é a URL pública do MCP.
`BACKWORK_MCP_OAUTH_SCOPES`	Não	Escopos anunciados aos clientes, separados por espaço ou vírgula. O padrão é `backwork:mcp`.
`BACKWORK_MCP_OAUTH_REQUIRED_SCOPES`	Não	Escopos exigidos após introspecção de token, separados por espaço ou vírgula.
`BACKWORK_MCP_OAUTH_INTROSPECTION_URL`	Não	Endpoint de introspecção de token RFC 7662 usado para validar tokens de acesso OAuth.
`BACKWORK_MCP_OAUTH_INTROSPECTION_CLIENT_ID`	Não	ID do cliente para autenticação básica de introspecção.
`BACKWORK_MCP_OAUTH_INTROSPECTION_CLIENT_SECRET`	Não	Segredo do cliente para autenticação básica de introspecção.
`BACKWORK_MCP_OAUTH_INTROSPECTION_TOKEN`	Não	Token bearer para introspecção quando a autenticação básica não é usada.
`BACKWORK_MCP_OAUTH_API_KEY_CLAIM`	Não	Claim de caminho com pontos da resposta de introspecção a ser usado como credencial Backwork downstream. Se omitido, o token de acesso OAuth é encaminhado.
`BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE`	Não	Valores `aud` permitidos separados por vírgula quando as respostas de introspecção incluem um público.
`BACKWORK_MCP_EXPOSE_UNAVAILABLE_TOOLS`	Não	`true` oferece ferramentas e ações que a API de produção marca como indisponíveis. Ações de escopo de escrita permanecem ocultas para concessões OAuth somente leitura.

Solução de problemas

Chave de API ausente

Para stdio, defina BACKWORK_API_KEY na configuração do cliente MCP. Para o modo de chave de API HTTP, envie Authorization: Bearer <key>. Para o modo OAuth HTTP, configure BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS e envie Authorization: Bearer <access_token>.

401 do MCP HTTP

O servidor remoto não recebeu um token bearer. Configure seu cliente MCP para autenticar com OAuth ou envie um cabeçalho Authorization. Implantações habilitadas para OAuth incluem resource_metadata no cabeçalho WWW-Authenticate para apontar os clientes para /.well-known/oauth-protected-resource.

OAuth do Claude Code

Se o Claude Code não abrir o navegador, execute /mcp, selecione backwork e escolha a ação de autenticação. Se ele fornecer uma URL em vez de abrir o navegador, copie essa URL para o seu navegador.

Se o redirecionamento do navegador de volta para o Claude Code falhar após o consentimento, copie a URL completa de retorno da barra de endereço do navegador e cole-a no prompt do Claude Code.

Este servidor não armazena tokens OAuth. Ele valida o token de acesso de cada requisição por introspecção e o encaminha (ou a chave de API mapeada) para a API Backwork. Atualizar um token de acesso expirado é responsabilidade do cliente MCP: quando a introspecção relata um token inativo, o servidor responde 401 com error="invalid_token", e o cliente pode usar seu token de atualização com o servidor de autorização Backwork.

Se o Claude Code continuar usando um token antigo, abra /mcp, selecione backwork, limpe a autenticação e autentique novamente. Você também pode remover e re-adicionar o servidor com:

claude mcp remove backwork
claude mcp add --transport http --scope user backwork https://backworkhealth.com/mcp

Se a descoberta retornar 503, o aplicativo web Backwork está recusando intencionalmente anunciar OAuth porque a assinatura de produção ou o armazenamento de estado Redis/KV está ausente.

Se as chamadas de ferramenta autenticarem mas falharem com invalid_token ou invalid_target, verifique se BACKWORK_MCP_RESOURCE, BACKWORK_MCP_OAUTH_RESOURCE e BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE usam todos:

https://backworkhealth.com/mcp

Limites de taxa

Aguarde a janela de redefinição ou use um plano de API com maior capacidade.

Suporte

Documentação: https://backworkhealth.com/docs
Problemas: https://github.com/tylergibbs1/backwork-mcp/issues
E-mail: support@backworkhealth.com

Licença

MIT. Veja LICENSE.

Plugin do Claude Code

O plugin backwork agrupa o servidor MCP hospedado com quatro habilidades de pesquisa: autorização prévia, verificação de cobertura, mudanças de políticas e preparação de apelação de negação. Instale-o a partir do marketplace de plugins deste repositório:

/plugin marketplace add tylergibbs1/backwork-mcp
/plugin install backwork@backwork

Em seguida, execute /mcp, selecione plugin:backwork:backwork e conclua o login OAuth. Novas contas começam com 100 créditos gratuitos. Veja plugins/backwork/README.md para as habilidades e os comandos /backwork:pa e /backwork:coverage.

O manifesto do marketplace é .claude-plugin/marketplace.json. npm test verifica os manifestos e cada SKILL.md. O CI também executa claude plugin validate --strict no marketplace e no plugin.

Habilidades do Claude.ai

As mesmas quatro habilidades funcionam no claude.ai. Elas precisam do conector Backwork para chamar ferramentas.

Adicione o conector: Configurações > Conectores > Adicionar conector personalizado, nomeie-o como Backwork e insira https://backworkhealth.com/mcp. Conclua o login OAuth.
Crie um zip por habilidade. Os zips vão para dist/claude-skills/, que o git ignora:
```
node scripts/build-claude-skills.mjs
```
Cada zip contém a pasta da habilidade em sua raiz, por exemplo, coverage-check.zip contém coverage-check/SKILL.md. A compilação falha se um SKILL.md quebrar as regras do claude.ai (nome corresponde à sua pasta, descrição com 200 caracteres ou menos).
Envie cada zip: abra Personalizar > Habilidades (em versões mais antigas, Configurações > Capacidades > Habilidades), clique em Adicionar e selecione o zip. Habilidades personalizadas exigem um plano Pro, Max, Team ou Enterprise com execução de código ativada. Cada usuário envia sua própria cópia.