Backwork

Políticas de cobertura de Medicare y aseguradoras comerciales, consulta de códigos médicos, investigación de autorización previa y validación de reclamaciones con fuentes citadas.

GitHub

Prueba este MCPPatrocinado

Servidor MCP alojado

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

Se instala en Claude Code, Codex, Cursor y más

Documentación

Servidor MCP de Backwork

Servidor oficial del Protocolo de Contexto de Modelos (MCP) para la API de Backwork. Proporciona a los asistentes de IA acceso controlado a políticas médicas de Medicare y pagadores, inteligencia de códigos médicos, verificaciones de autorización previa, validación de reclamaciones, revisión de cumplimiento, evidencia de formularios de medicamentos y operaciones de webhooks.

Hay dos formas de conectarse:

	Alojado remoto	Stdio local
Endpoint	`https://backworkhealth.com/mcp` (HTTP Streamable)	`npx -y @backwork/mcp`
Autenticación	OAuth en el navegador, sin clave que copiar	`BACKWORK_API_KEY=bwk_live_...`
Úsalo cuando	Tu cliente soporta MCP remoto con OAuth	Tu cliente solo ejecuta comandos locales, o quieres el servidor en tu máquina

El endpoint alojado solo acepta OAuth. No envíes una clave de API de Backwork como token de portador a https://backworkhealth.com/mcp. La concesión OAuth es de solo lectura (backwork:mcp read), por lo que el servidor alojado ofrece solo acciones de lectura: sin gestión de webhooks y sin confirmaciones de cumplimiento. Usa stdio local con una clave en vivo con alcance de escritura para esas funciones.

Las llamadas consumen los créditos de solicitud de tu organización, como cualquier otra llamada a /api/v1. Una clave bwk_test_ funciona solo en el sandbox (https://backworkhealth.com/api/sandbox/v1), que cubre búsqueda de políticas, consulta de códigos, verificación de autorización previa y evaluación de cobertura; para usarla, establece BACKWORK_API_BASE a esa URL.

Claude Code

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

Agrega --scope user para que esté disponible en todos los proyectos. Luego ejecuta claude, abre /mcp, selecciona backwork y completa el inicio de sesión en el navegador y la pantalla de consentimiento de Backwork. Verifícalo con claude mcp get backwork.

Si el descubrimiento OAuth necesita fijarse explícitamente, agrega el mismo 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 alojado: abre Configuración > Conectores > Agregar conector personalizado, nómbralo Backwork e ingresa https://backworkhealth.com/mcp. Claude Desktop ejecuta el inicio de sesión OAuth cuando te conectas.

Stdio local: agrega esto a claude_desktop_config.json (Configuración > Desarrollador > Editar configuración) y reinicia Claude Desktop:

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

Cursor

Agrega a ~/.cursor/mcp.json (todos los proyectos) o .cursor/mcp.json (un proyecto). Cursor abre el inicio de sesión OAuth la primera vez que se 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"}'

O agrégalo a .vscode/mcp.json en un espacio de trabajo. VS Code te pide que inicies sesión cuando el servidor se inicia:

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

Stdio local, con la clave solicitada una vez y almacenada por 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 en ChatGPT

ChatGPT se conecta al servidor alojado como una conexión MCP personalizada en modo desarrollador. Tres herramientas devuelven una tarjeta pequeña que ChatGPT renderiza en línea encima de su respuesta.

En ChatGPT, abre Configuración → Seguridad e inicio de sesión y activa Modo desarrollador. Tu plan o administrador del espacio de trabajo puede necesitar permitirlo.
Ve a chatgpt.com/plugins y selecciona el botón +.
Nómbralo Backwork, agrega una descripción breve y, en Conexión, ingresa https://backworkhealth.com/mcp. Elige OAuth para la autenticación.
Selecciona Crear. ChatGPT abre la página de inicio de sesión de Backwork; aprueba la concesión de solo lectura backwork:mcp read.
Verifica las herramientas descubiertas, luego inicia un nuevo chat, agrega Backwork desde el menú de herramientas y pregunta algo como "¿Está cubierto el CPT 76942 en Texas y requiere autorización previa?"

Después de una actualización del servidor, abre la conexión en chatgpt.com/plugins y selecciona Actualizar para que ChatGPT recopile los nuevos metadatos de herramientas y componentes.

Herramienta	Tarjeta	Qué muestra
`backwork_coverage_lookup`	Resultado de cobertura	Cada política que lista los códigos: pagador (`CMS` para políticas de Medicare), título y número, fecha de vigencia, una fila por código con su insignia de disposición y etiqueta de fuente, y un enlace Abrir política a la página de Backwork de la política (LCD de Medicare, Artículos y NCD) o, para otras políticas, su documento fuente
`backwork_prior_auth_research`	Lista de verificación de autorización previa	La determinación y confianza, códigos que requieren autorización previa, documentación a recopilar, brechas conocidas y citas numeradas. Una tarea de investigación iniciada se muestra como pendiente hasta que preguntes de nuevo
`backwork_policy_research`	Investigación de políticas	Por acción: `compare` muestra los códigos lado a lado entre contratistas de Medicare (MAC), una columna por jurisdicción, con la disposición y política de cada celda, y un conteo de cobertura por columna; `search` lista las políticas coincidentes con pagador, número, fecha de vigencia, un resumen breve y un enlace; `get` muestra el resumen de una política, un extracto de criterios por sección y sus códigos; `criteria` lista los extractos de criterios coincidentes con sus políticas; `changes` lista cambios recientes; `jurisdictions` lista cada MAC y sus estados

ChatGPT carga la tarjeta de una herramienta en cada llamada de esa herramienta. Un resultado sin nada que mostrar, como una búsqueda sin coincidencias o un error, colapsa la tarjeta a altura cero y le pide a ChatGPT que la cierre, por lo que no queda ninguna tarjeta vacía en la conversación.

Un código que una política lista solo porque su título nombra el medicamento se etiqueta como Inferido del título de la política, en la tarjeta y en el texto. Confírmalo contra el documento antes de confiar en él.

Las tarjetas siguen el tema claro u oscuro de ChatGPT, no cargan nada de la red (su CSP no permite dominios) y abren enlaces a través del host. Son recursos de MCP Apps (text/html;profile=mcp-app), por lo que otros hosts de MCP Apps también pueden renderizarlas. Los clientes sin soporte de UI ignoran las claves _meta que vinculan herramientas a tarjetas y obtienen el mismo texto de markdown que antes; structuredContent.widget lleva los datos de la tarjeta.

Otros clientes MCP

Los clientes que ejecutan comandos locales pueden usar la configuración stdio que se muestra para Claude Desktop. Los clientes que soportan URLs remotas con OAuth pueden usar https://backworkhealth.com/mcp directamente.

Para clientes que solo soportan URLs remotas con encabezados estáticos, implementa un servidor autohospedado privado en modo de clave de API o autenticación dual (ver Autohospedaje) y envía la clave como encabezado de portador:

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

Autohospedaje

Ejecuta un servidor HTTP Streamable:

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

Valores predeterminados:

Configuración	Predeterminado	Anulación
Transporte	`stdio`	`--http` o `BACKWORK_MCP_TRANSPORT=http`
Host	`127.0.0.1`	`--host` o `BACKWORK_MCP_HOST`
Puerto	`3000`	`--port` o `BACKWORK_MCP_PORT` o `PORT`
Ruta MCP	`/mcp`	`--path` o `BACKWORK_MCP_PATH`
Hosts permitidos	hosts de loopback/privados, `VERCEL_URL`, o host público configurado	`BACKWORK_MCP_ALLOWED_HOSTS` o `BACKWORK_MCP_PUBLIC_HOST`

El modo HTTP requiere Authorization: Bearer por solicitud. Por defecto, este portador es una clave de API de Backwork. Para implementaciones MCP remotas alojadas, habilita el descubrimiento de recursos protegidos OAuth para que los clientes compatibles con Claude puedan autenticar usuarios a través de tu servidor de autorización:

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

El servidor publica Metadatos de Recursos Protegidos OAuth en /.well-known/oauth-protected-resource e incluye esa URL en los desafíos WWW-Authenticate. Si tu API de Backwork acepta tokens de acceso OAuth directamente, no se necesita mapeo adicional; el servidor MCP reenvía el portador OAuth aguas abajo. Si tu servidor de autorización expone una clave de API de Backwork en la introspección de tokens, establece BACKWORK_MCP_OAUTH_INTROSPECTION_URL y BACKWORK_MCP_OAUTH_API_KEY_CLAIM para validar el token de acceso y mapearlo a la credencial de Backwork aguas abajo.

Para una implementación privada de un solo inquilino donde el entorno del servidor proporciona la clave, establece:

BACKWORK_MCP_ALLOW_ENV_KEY=true BACKWORK_API_KEY=bwk_live_YOUR_API_KEY npm run start:http

Solo usa BACKWORK_MCP_ALLOW_ENV_KEY=true en implementaciones de loopback o redes privadas protegidas por control de acceso de red. Las implementaciones públicas deben requerir un token de portador por solicitud, establecer BACKWORK_MCP_ALLOWED_HOSTS/BACKWORK_MCP_PUBLIC_HOST y establecer BACKWORK_MCP_ALLOWED_ORIGINS solo a orígenes de navegador exactos que puedan conectarse.

Alojamiento en Vercel

Este repositorio puede implementarse como un proyecto de Vercel solo de API. El proyecto de producción 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

Las funciones de Vercel exponen:

Ruta	Propósito
`/mcp`	Endpoint MCP HTTP Streamable
`/health`	Verificación de salud del servidor MCP ligero
`/.well-known/oauth-protected-resource`	Metadatos de recursos protegidos OAuth cuando OAuth está configurado
`/`	Metadatos básicos del endpoint

La aplicación web de Backwork que emite tokens OAuth también debe configurarse:

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

El descubrimiento OAuth de producción falla de forma cerrada a menos que BACKWORK_OAUTH_SIGNING_SECRET tenga al menos 32 caracteres y Redis o Vercel KV esté configurado para almacenamiento de consentimiento de un solo uso y código de autorización.

Verificación de salud:

curl http://localhost:3000/health

Desarrollo local

npm install
npm run build
BACKWORK_API_KEY=bwk_live_YOUR_API_KEY npm start

Comandos útiles:

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

Requiere Node.js 18.14.1 o más reciente.

Herramientas disponibles

Los nombres de las herramientas usan el prefijo backwork_ para facilitar el descubrimiento cuando este servidor se instala junto a otros servidores MCP. La superficie predeterminada es intencionalmente a nivel de flujo de trabajo en lugar de un envoltorio de API 1:1, para que los agentes vean menos opciones y las tareas comunes requieran menos llamadas a herramientas.

Todas las herramientas incluyen title, description, inputSchema, outputSchema y anotaciones MCP. Cada herramienta declara sus propias anotaciones; el servidor se niega a iniciar si una herramienta marcada como de solo lectura ofrece una operación de alcance de escritura, o una marcada como no destructiva ofrece un DELETE. Las llamadas exitosas devuelven texto legible más structuredContent con message y, cuando está disponible, data y meta de la API de Backwork.

data y meta son proyecciones: solo llevan los campos de respuesta que src/api-operations.ts lista para la operación (reads y metaReads). Los IDs de solicitud, marcas de tiempo de respuesta, marcas de tiempo de registros, costo de trabajos de investigación y URLs de sondeo, claves de idempotencia y nombres de modelos se eliminan. Las fechas de vigencia y última revisión de políticas, tiempos de obtención de fuentes y tiempos de muestra de auditoría de fuentes se conservan. El servidor registra el ID de solicitud de una llamada API fallida.

Los fallos a nivel de herramienta devuelven isError: true. Los fallos de facturación y límite de velocidad se informan en términos simples y nunca repiten la sugerencia de la API, nombres de planes o enlaces de precios: una característica fuera del plan de la organización, sin créditos de solicitud restantes, o un límite de velocidad con cuándo reintentar. test/output-guard.test.mjs ejecuta cada acción de herramienta contra respuestas de fixture y esos errores, y falla en redacción de venta adicional, IDs de rastreo, marcas de tiempo, costo o campos de modelo.

Fuentes y actualidad

Cuando la respuesta de la API de Backwork cita documentos de políticas, structuredContent.provenance lleva lo que un agente necesita para citarlos, y la salida de texto termina con un bloque corto --- Sources ---:

Campo	Significado
`source_urls`	URLs de documentos fuente distintos
`authorities`	Autoridades emisoras, por ejemplo `CMS` o un nombre de pagador
`retrieved_at`	Hora de obtención más antigua cuando cada fuente citada tiene una hora conocida; de lo contrario, `null`
`as_of`	Fecha de vigencia más reciente entre las fuentes citadas
`sources[]`	`policy_id`, `source_url`, `authority`, `retrieved_at`, `as_of` por fuente

Los valores provienen de la respuesta de la API. source_check.source_url y source_check.last_fetched_at tienen prioridad sobre los metadatos de fuente heredados. Una hora de obtención desconocida explícita permanece null; los retrieved_at, last_verified_at o crawled_at heredados son valores de respaldo solo cuando el bloque de verificación de fuente está ausente. Las horas de obtención conocidas permanecen disponibles en sources[] cuando otra fuente citada tiene una hora desconocida. La forma coincide con el bloque provenance en los resultados de herramientas de agente de Backwork.

La evidencia de políticas también conserva el source_check de la API: URL de fuente, hora de última obtención, SHA-256 del contenido obtenido y muestras de auditoría source_accuracy. Cada auditoría informa el campo medido, fecha y tamaño de muestra, proporción de registros muestreados que coincidieron, intervalo de Wilson del 95% y método. Estas muestras miden registros de una fuente; no miden certeza para la política individual o una decisión de cobertura. Las auditorías faltantes permanecen null. Las tarjetas muestran fechas de obtención y muestras de auditoría de fuente expandibles. Las políticas con aplicabilidad explícita también conservan los campos opcionales applicability_scope, applicability_markets, applicability_evidence y applicability_note. Los documentos de mercado compartido y los documentos singleton indexados aparecen en los índices de estado del publicador; esa evidencia de descubrimiento no establece la cobertura del plan o producto del miembro. Una política document_scoped sin estado, línea de negocio o mercados indexados tiene aplicabilidad desconocida. Las tarjetas y el texto muestran la nota de la API, y las tarjetas proporcionan enlaces al índice del publicador y citas textuales exactas con números de página. Las respuestas heredadas sin estos campos conservan su forma existente.

La evidencia de aplicabilidad se limita a un SHA-256 del documento, hasta 16 listados de índice HTTPS del publicador y hasta 16 declaraciones de los tres tipos admitidos (non_medicare_disclaimer, commercial_policy_header, member_type_branch). Las citas están limitadas a 4.000 caracteres, las URL de índice a 2.048 caracteres y las páginas deben ser enteros positivos. Los campos desconocidos se descartan; la evidencia malformada se convierte en null. Los códigos de mercado y las notas también están limitados. El MCP conserva la confianza de la API y los resultados de revisión manual; los listados de índice no aumentan la confianza ni resuelven la autorización.

Las coincidencias de código conservan grounding por separado de su source de extracción:

`grounding`	Significado
`grounded`	Encontrado en el texto fuente retenido de Backwork
`not_grounded`	Leído por el pipeline de documentos, pero no encontrado en el texto fuente retenido
`no_source_text`	No había texto retenido disponible para verificar
`not_checked`	La fundamentación no se verificó, incluidos los códigos inferidos de un título de póliza

El texto y las tarjetas etiquetan estas verificaciones sin tratar un código fundamentado como garantía de cobertura. Una respuesta más antigua que omite la fundamentación permanece desconocida, y un valor futuro no reconocido se conserva y etiqueta.

Disponibilidad de producción

Qué acciones ofrece un servidor depende de dos cosas:

Disponibilidad. El documento OpenAPI de Backwork puede marcar una operación como x-backwork-availability: unavailable-in-production. Contra la API de producción (https://backworkhealth.com), el servidor retiene esas acciones. Hoy ninguna está marcada: producción sirve cada operación /api/v1 que estas herramientas llaman con la clave activa de una organización.
Acceso. Las operaciones que necesitan el alcance write (x-backwork-required-scopes) se retienen en una concesión OAuth de solo lectura. En el servidor alojado esto oculta backwork_webhook_management y las acciones acknowledge y bulk_acknowledge de backwork_compliance_review. Una conexión de solo lectura tampoco recibe diagnósticos backwork_system_health, ni entrada idempotency_key en backwork_claim_validation, y un backwork_compliance_review sin entradas de reconocimiento (diff_id, diff_ids, notes) ni IDs de diff en sus resultados. Una clave de API de Backwork (stdio, o HTTP con un portador bwk_) recibe todas las herramientas y acciones, y la API aplica los propios alcances de la clave. Una concesión OAuth cuenta como de solo lectura a menos que sus alcances incluyan write.

Una herramienta sin acción ofrecida está oculta. Una herramienta parcialmente ofrecida elimina las acciones retenidas de su entrada action; las acciones retenidas como no disponibles en producción también se nombran en su descripción. Un servidor apuntado a otro despliegue de Backwork con BACKWORK_API_BASE ignora los marcadores de disponibilidad, y BACKWORK_MCP_EXPOSE_UNAVAILABLE_TOOLS=true hace lo mismo contra producción. Ninguno levanta la regla de alcance de escritura.

Herramienta principal	Propósito
`backwork_coverage_lookup`	Buscar códigos de procedimiento y combinar detalles de código, evidencia de póliza, autorización previa, riesgo de reclamación, comparación de jurisdicción y evidencia de gasto. Con `payer`, los detalles de código listan solo las pólizas de ese pagador y dicen cuántas pólizas de otros pagadores se omitieron
`backwork_policy_research`	Buscar pólizas, obtener una póliza, buscar criterios extraídos, revisar cambios de póliza, mapear jurisdicciones MAC o comparar cómo los MAC cubren los mismos códigos
`backwork_claim_validation`	Validar cobertura de reclamación, requisitos de documentación, riesgo de denegación y criterios opcionales específicos de póliza
`backwork_prior_auth_research`	Verificar autorización previa de las pólizas de Backwork (Medicare o un pagador nombrado), o iniciar y sondear un trabajo en segundo plano que busca en sitios web públicos de pagadores
`backwork_drug_formulary_research`	Buscar evidencia de beneficios farmacéuticos comerciales de CVS Caremark, Express Scripts y UnitedHealthcare / Optum Rx
`backwork_compliance_review`	Revisar estadísticas de cumplimiento y listar cambios de póliza no revisados; con una clave de API, también reconocer cambios
`backwork_webhook_management`	Listar, crear, actualizar, eliminar o probar endpoints de webhook. Backwork envía un evento, `compliance.acknowledged`; los webhooks de cambio de póliza no se envían. Requiere una clave de API con alcance de escritura
`backwork_system_health`	Verificar la salud de la API de Backwork y el estado de dependencias. Solo conexiones con clave de API

Formato de respuesta

Cada herramienta acepta:

{
  "response_format": "markdown"
}

Use "markdown" para salida legible o "json" para que el contenido de texto refleje el structuredContent devuelto.

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

Pruebas y Evaluaciones

Ejecute la compilación y la prueba de humo de metadatos MCP:

npm test

La prueba de humo inicia el servidor stdio compilado con una clave ficticia, verifica las 8 herramientas de flujo de trabajo, comprueba títulos, esquemas, anotaciones, esquemas de salida, response_format y verifica que los fallos de validación local se informen con isError: true. La prueba de humo HTTP también completa la inicialización MCP autenticada, lista las herramientas de concesión de lectura y llama a una herramienta con argumentos inválidos. La suite test/ cubre la disponibilidad de producción, el conjunto de herramientas de solo lectura y solo OAuth del servidor alojado, la procedencia, la calidad de descripción y una verificación léxica de selección de herramientas (sin llamadas de modelo), el manifiesto del registro y las tarjetas de ChatGPT: sus plantillas en la lista de herramientas, los recursos y el tipo MIME, el structuredContent de cada tarjeta contra su esquema, markdown para clientes sin interfaz de usuario y una representación de cada página de tarjeta en un navegador simulado para cada acción de cada herramienta con tarjeta, que debe mostrar una tarjeta o colapsar a altura cero.

Antes de publicar, ejecute npm run verify:package. Instala el tarball empaquetado en un consumidor temporal sin anulaciones de repositorio ni archivo de bloqueo, luego ejecuta ambos transportes en el runtime actual y Node 18.20.8. CI ejecuta la misma verificación. Se pueden pasar versiones exactas adicionales de Node después de --.

Contrato de API

Cada endpoint de Backwork que este servidor llama está listado en src/api-operations.ts, con los campos de solicitud que envía y los campos de respuesta que lee. Las herramientas solo pueden llamar a la API a través de ese catálogo. Cada entrada también refleja el marcador de disponibilidad de la operación y el alcance requerido. npm test verifica el catálogo contra el openapi/backwork-openapi.json incluido, y pregunta a la propia regla de exposición del servidor qué acciones de herramienta ofrecería en producción, para una concesión OAuth de solo lectura y para una clave de API. Una acción ofrecida para una operación que producción no sirve, marca como no disponible o (para la concesión OAuth) protege con alcance write falla.

CI ejecuta npm run contract:live, que ejecuta las mismas verificaciones contra https://backworkhealth.com/openapi.json y falla cuando la copia incluida difiere de ella en cualquier lugar excepto descripciones, resúmenes y ejemplos.

Cuando la API de Backwork cambia, actualice la copia incluida y revise el diff:

npm run openapi:update
npm run contract:check

El directorio evals/ incluye una evaluación de descubrimiento de herramientas y una evaluación de datos de solo lectura construidas a partir de registros fijos de póliza/código respaldados por fuentes. Actualice las respuestas de solo lectura intencionalmente cuando se actualicen los datos fuente de Backwork.

Seguimiento de migración del SDK

La versión 2.1.4 incluye el SDK v1 1.32.1, Zod y sus dependencias de producción del archivo de bloqueo confirmado. Esto lleva el adaptador Node de Hono parcheado 1.19.15 a las instalaciones del consumidor y preserva el soporte de Node 18 (mínimo 18.14.1). npm solo honra las anulaciones en el paquete raíz del consumidor, por lo que una anulación en este paquete no puede proporcionar esa garantía. Use npm ci para reproducir el árbol de lanzamiento y volver a ejecutar la verificación del paquete después de actualizar el archivo de bloqueo. La guía oficial de migración v2 requiere un cambio de compatibilidad separado:

Elevar el runtime de Node.js compatible de 18 a al menos 20, incluido el despliegue alojado y el flujo de trabajo de lanzamiento.
Reemplazar las importaciones monolíticas del SDK con @modelcontextprotocol/server, @modelcontextprotocol/node para el transporte HTTP de Node y @modelcontextprotocol/client para clientes y pruebas; use @modelcontextprotocol/core para esquemas de protocolo públicos donde sea necesario.
Actualizar el rango declarado de Zod a al menos 4.2 y envolver los esquemas de entrada/salida de herramientas como objetos Standard Schema, preservando las descripciones de campo y la validación de salida estructurada.
Verificar el descubrimiento de herramientas, stdio, el ciclo de vida HTTP sin estado, el descubrimiento y alcances de OAuth, widgets, minimización de salida y el contrato OpenAPI en vivo antes de publicar esa migración.

Registro MCP

server.json describe este servidor para el registro oficial de MCP como io.github.tylergibbs1/backwork-mcp: el remoto HTTP Streamable alojado en https://backworkhealth.com/mcp (OAuth, descubierto desde los metadatos del recurso protegido) y el paquete npm @backwork/mcp sobre stdio. package.json lleva el mcpName correspondiente que el registro usa para verificar la propiedad de npm. npm test valida server.json contra el esquema del registro y verifica que sus versiones coincidan con package.json.

Lanzamiento

Los lanzamientos publican @backwork/mcp en npm con Trusted Publishing (GitHub OIDC, sin token npm) y luego publican server.json en el registro MCP.

npm version minor (o patch/major). El script version copia la nueva versión en server.json y SERVER_VERSION en src/index.ts.
Fusionar ese cambio en main.
Empujar una etiqueta coincidente desde main, por ejemplo git tag v2.1.0 && git push origin v2.1.0.

El flujo de trabajo Release entonces:

Falla a menos que la etiqueta sea igual a v + la versión package.json.
Ejecuta npm ci, npm test (compilación, pruebas de humo, pruebas unitarias, contrato OpenAPI), npm run verify:package (consumidor limpio y transportes Node 18) y npm pack --dry-run.
Publica en npm con procedencia, en el entorno npm. Una versión ya en npm se omite, por lo que una ejecución fallida se puede volver a ejecutar.
Espera a que la versión aparezca en npm, luego ejecuta mcp-publisher login github-oidc y mcp-publisher publish.

Configuración única de npm: en npmjs.com, abra @backwork/mcp > Settings > Trusted publishing, elija GitHub Actions e ingrese el usuario tylergibbs1, el repositorio backwork-mcp, el flujo de trabajo release.yml y el entorno npm.

Variables de Entorno

Variable	Obligatorio	Descripción
`BACKWORK_API_KEY`	Stdio sí; HTTP no	Clave de API de Backwork. En modo HTTP, prefiere `Authorization: Bearer` por solicitud.
`BACKWORK_API_BASE`	No	Sobrescribe la URL base de la API.
`BACKWORK_MCP_TRANSPORT`	No	`stdio` o `http`.
`BACKWORK_MCP_HOST`	No	Host de enlace HTTP. Por defecto es `127.0.0.1`.
`BACKWORK_MCP_PORT`	No	Puerto de enlace HTTP.
`BACKWORK_MCP_PATH`	No	Ruta MCP HTTP.
`BACKWORK_MCP_ALLOWED_ORIGINS`	No	Orígenes HTTP permitidos separados por comas. Los orígenes de bucle local están permitidos para solicitudes de bucle local.
`BACKWORK_MCP_ALLOW_ORIGIN`	No	Alias compatible con versiones anteriores para `BACKWORK_MCP_ALLOWED_ORIGINS`.
`BACKWORK_MCP_ALLOWED_HOSTS`	No	Encabezados Host HTTP permitidos separados por comas para implementaciones públicas.
`BACKWORK_MCP_ALLOW_HOST`	No	Alias compatible con versiones anteriores para `BACKWORK_MCP_ALLOWED_HOSTS`.
`BACKWORK_MCP_PUBLIC_HOST`	No	Host público principal permitido para solicitudes HTTP.
`BACKWORK_MCP_PUBLIC_URL`	No	Origen público canónico para metadatos OAuth, p. ej. `https://backworkhealth.com`.
`BACKWORK_MCP_ALLOW_ENV_KEY`	No	Permitir solicitudes HTTP privadas sin autenticación de portador para usar `BACKWORK_API_KEY`.
`BACKWORK_MCP_AUTH_MODE`	No	Modo de portador HTTP: `api-key`, `oauth` o `dual`. Por defecto es `dual` cuando hay servidores de autorización OAuth configurados; de lo contrario, `api-key`.
`BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS`	OAuth	URLs de emisor / servidor de autorización OAuth separadas por comas anunciadas en metadatos de recursos protegidos.
`BACKWORK_MCP_OAUTH_RESOURCE`	No	Sobrescribe el identificador de recurso RFC 8707. Por defecto es la URL pública de MCP.
`BACKWORK_MCP_OAUTH_SCOPES`	No	Ámbitos anunciados a los clientes separados por espacios o comas. Por defecto es `backwork:mcp`.
`BACKWORK_MCP_OAUTH_REQUIRED_SCOPES`	No	Ámbitos requeridos después de la introspección de tokens, separados por espacios o comas.
`BACKWORK_MCP_OAUTH_INTROSPECTION_URL`	No	Punto final de introspección de tokens RFC 7662 utilizado para validar tokens de acceso OAuth.
`BACKWORK_MCP_OAUTH_INTROSPECTION_CLIENT_ID`	No	ID de cliente para autenticación básica de introspección.
`BACKWORK_MCP_OAUTH_INTROSPECTION_CLIENT_SECRET`	No	Secreto de cliente para autenticación básica de introspección.
`BACKWORK_MCP_OAUTH_INTROSPECTION_TOKEN`	No	Token de portador para introspección cuando no se usa autenticación básica.
`BACKWORK_MCP_OAUTH_API_KEY_CLAIM`	No	Reclamación de ruta de puntos de la respuesta de introspección para usar como credencial Backwork descendente. Si se omite, el token de acceso OAuth se reenvía.
`BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE`	No	Valores `aud` permitidos separados por comas cuando las respuestas de introspección incluyen una audiencia.
`BACKWORK_MCP_EXPOSE_UNAVAILABLE_TOOLS`	No	`true` ofrece herramientas y acciones que la API de producción marca como no disponibles. Las acciones de ámbito de escritura permanecen ocultas para las concesiones OAuth de solo lectura.

Solución de problemas

Clave de API faltante

Para stdio, establece BACKWORK_API_KEY en la configuración del cliente MCP. Para el modo de clave de API HTTP, envía Authorization: Bearer <key>. Para el modo OAuth HTTP, configura BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS y envía Authorization: Bearer <access_token>.

401 desde MCP HTTP

El servidor remoto no recibió un token de portador. Configura tu cliente MCP para autenticarse con OAuth o envía un encabezado Authorization. Las implementaciones habilitadas para OAuth incluyen resource_metadata en el encabezado WWW-Authenticate para apuntar a los clientes a /.well-known/oauth-protected-resource.

OAuth de Claude Code

Si Claude Code no abre el navegador, ejecuta /mcp, selecciona backwork y elige la acción de autenticación. Si te da una URL en lugar de abrir un navegador, copia esa URL en tu navegador.

Si el redireccionamiento del navegador de vuelta a Claude Code falla después del consentimiento, copia la URL de devolución de llamada completa desde la barra de direcciones del navegador y pégala en el mensaje de Claude Code.

Este servidor no guarda tokens OAuth. Valida el token de acceso de cada solicitud mediante introspección y lo reenvía (o la clave de API mapeada) a la API de Backwork. Refrescar un token de acceso caducado es trabajo del cliente MCP: cuando la introspección informa que un token está inactivo, el servidor responde 401 con error="invalid_token", y el cliente puede usar su token de refresco con el servidor de autorización de Backwork.

Si Claude Code sigue usando un token antiguo, abre /mcp, selecciona backwork, borra la autenticación y luego autentícate de nuevo. También puedes eliminar y volver a agregar el servidor con:

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

Si el descubrimiento devuelve 503, la aplicación web de Backwork se niega intencionalmente a anunciar OAuth porque falta el firmado de producción o el almacenamiento de estado Redis/KV.

Si las llamadas a herramientas se autentican pero fallan con invalid_token o invalid_target, verifica que BACKWORK_MCP_RESOURCE, BACKWORK_MCP_OAUTH_RESOURCE y BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE usen todos:

https://backworkhealth.com/mcp

Límites de velocidad

Espera a que se restablezca la ventana o usa un plan de API de mayor capacidad.

Soporte

Documentación: https://backworkhealth.com/docs
Problemas: https://github.com/tylergibbs1/backwork-mcp/issues
Correo electrónico: support@backworkhealth.com

Licencia

MIT. Consulta LICENSE.

Plugin de Claude Code

El plugin backwork incluye el servidor MCP alojado con cuatro habilidades de investigación: autorización previa, verificación de cobertura, cambios de políticas y preparación de apelaciones de denegación. Instálalo desde el mercado de plugins de este repositorio:

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

Luego ejecuta /mcp, selecciona plugin:backwork:backwork y completa el inicio de sesión OAuth. Las cuentas nuevas comienzan con 100 créditos gratuitos. Consulta plugins/backwork/README.md para las habilidades y los comandos /backwork:pa y /backwork:coverage.

El manifiesto del mercado es .claude-plugin/marketplace.json. npm test verifica los manifiestos y cada SKILL.md. CI también ejecuta claude plugin validate --strict en el mercado y el plugin.

Habilidades de Claude.ai

Las mismas cuatro habilidades funcionan en claude.ai. Necesitan el conector de Backwork para llamar a las herramientas.

Agrega el conector: Configuración > Conectores > Agregar conector personalizado, nómbralo Backwork e ingresa https://backworkhealth.com/mcp. Completa el inicio de sesión OAuth.
Crea un zip por habilidad. Los zips van a dist/claude-skills/, que git ignora:
```
node scripts/build-claude-skills.mjs
```
Cada zip contiene la carpeta de la habilidad en su raíz, por ejemplo, coverage-check.zip contiene coverage-check/SKILL.md. La compilación falla si un SKILL.md rompe las reglas de claude.ai (el nombre coincide con su carpeta, descripción de 200 caracteres o menos).
Sube cada zip: abre Personalizar > Habilidades (en versiones anteriores, Configuración > Capacidades > Habilidades), haz clic en Agregar y selecciona el zip. Las habilidades personalizadas necesitan un plan Pro, Max, Team o Enterprise con ejecución de código activada. Cada usuario sube su propia copia.