snowstorm-mcp-server

Un servidor MCP para consultar la terminología clínica SNOMED CT a través de los backends Snowstorm y Snowstorm Lite.

SNOMED CT es la terminología clínica más completa del mundo, utilizada en historias clínicas electrónicas en más de 80 países. Este servidor expone la consulta, búsqueda, validación, navegación jerárquica y expansión de conjuntos de valores de SNOMED CT a través del Model Context Protocol (MCP), lo que permite a los asistentes de IA trabajar directamente con terminología clínica.

Admite todas las ediciones de SNOMED CT disponibles en el backend conectado (Internacional, EE. UU., Reino Unido, Australia, etc.). No se requiere ninguna cuenta de usuario cuando se conecta a una instancia pública de Snowstorm.

Este repositorio admite dos modos de uso relacionados pero distintos:

1. Conector remoto alojado: ejecuta un endpoint MCP HTTPS público y conecta Claude a él mediante el flujo de conector personalizado / Connector Directory.

2. Uso autohospedado o local: ejecuta el servidor tú mismo contra tu propio despliegue de Snowstorm o Snowstorm Lite, incluidos Claude Desktop y futuros escenarios de empaquetado MCPB.

Si estás preparando un conector alojado para Claude web/escritorio/móvil, empieza por Conector remoto alojado. Si quieres ejecutar el servidor tú mismo contra tu propio backend de terminología, empieza por Uso autohospedado y local.

Conector remoto alojado

Usa este modo cuando estés operando un endpoint MCP público, por ejemplo https://your-domain.example/mcp, y quieras que Claude se conecte a él desde la infraestructura de Anthropic.

Despliegue alojado (Docker)

Construye y ejecuta el contenedor:

docker build -t snowstorm-mcp-server .
docker run -p 8000:8000 --memory=512m --restart=unless-stopped snowstorm-mcp-server

Establece --memory. Sin un límite de cgroup, el contenedor puede crecer hasta que se active el OOM killer global del kernel, y este elige el proceso más grande del host; por lo tanto, un fallo en este servidor derriba la máquina en lugar de solo el contenedor. Con un límite, el contenedor se elimina solo y --restart lo recupera de inmediato.

El servidor se inicia en modo Streamable HTTP en el puerto 8000 usando el config.docker-snowstorm.yaml incluido (espera un Snowstorm local en http://localhost:8080). Monta tu propia configuración en tiempo de ejecución:

docker run -p 8000:8000 \
  -v /path/to/your/config.yaml:/app/config.yaml \
  snowstorm-mcp-server

Para producción, despliega detrás de un proxy inverso HTTPS o en una plataforma con TLS automático (Cloud Run, Fly.io, Railway, etc.). Para despliegues orientados al público, configura la limitación de velocidad por cliente en el proxy inverso (basada en IP). MCP 2026-07-28 eliminó las sesiones a nivel de protocolo, por lo que el límite por sesión a nivel de aplicación ya no se aplica a los clientes HTTP; el límite global sigue limitando la carga total del backend; consulta Protecciones de rendimiento a continuación.

Para despliegues de conectores MCP remotos destinados a Claude web/escritorio, el servidor habilita CORS para https://claude.ai y https://claude.com en el endpoint Streamable HTTP de forma predeterminada. Si es necesario, anula la lista de orígenes permitidos con la variable de entorno SNOWSTORM_MCP_CORS_ALLOW_ORIGINS usando una lista separada por comas.

La validación de Origin está activada por defecto. Una solicitud al endpoint MCP cuyo encabezado Origin esté presente pero no esté en la lista de permitidos se rechaza con HTTP 403. Esto es lo que evita el DNS rebinding: el POST de una página reencuadrada sigue llevando su origen real, porque los navegadores adjuntan Origin a cada POST — incluidos los del mismo origen — según el Fetch Standard. Las solicitudes sin Origin en absoluto, que son todos los clientes MCP que no son navegadores, no se ven afectadas.

Eso se aplica a todos los motores de navegador actuales. Firefox anterior a 103 (julio de 2022) podía omitir Origin por completo en lugar de enviar null, especialmente cuando la preferencia network.http.sendOriginHeader estaba deshabilitada; establece también SNOWSTORM_MCP_ALLOWED_HOSTS si estos clientes están dentro del alcance.

La lista de permitidos tiene como valor predeterminado los orígenes CORS anteriores. Anúlala de forma independiente con SNOWSTORM_MCP_ALLOWED_ORIGINS (separada por comas) para despliegues del mismo origen detrás de un proxy inverso, donde CORS está desactivado pero los POST de los navegadores siguen llevando un Origin. Reemplaza la lista en lugar de añadir a ella, así que incluye cada origen de navegador que sirvas — si la estableces solo a tu propio dominio, bloquearás https://claude.ai. Si la estableces a *, se desactiva la comprobación a nivel de aplicación; ten en cuenta que si SNOWSTORM_MCP_ALLOWED_HOSTS también está establecido, la capa del SDK sigue validando Origin contra la lista CORS.

Actualización: los clientes de navegador cuyo origen de página no esté en la lista de permitidos ahora reciben 403 donde antes tenían éxito — independientemente de la configuración de CORS. CORS nunca rechazó estas solicitudes; solo retuvo los encabezados de respuesta, y las lecturas del mismo origen nunca estuvieron sujetas a CORS. Un despliegue autohospedado que sirva su propia interfaz web debe establecer SNOWSTORM_MCP_ALLOWED_ORIGINS a ese origen, o a * para restaurar el comportamiento anterior. Los clientes que no son navegadores no envían Origin y no se ven afectados.

Establece SNOWSTORM_MCP_ALLOWED_HOSTS a los nombres de host en los que se accede al servidor (separados por comas, p. ej. mcp.example.org,mcp.example.org:443) para rechazar además un Host no reconocido con HTTP 421. Esto permanece desactivado por defecto porque una lista de hosts incompleta rechaza todo el tráfico; se activa automáticamente al vincularse a localhost. Es defensa en profundidad: la validación de Origin anterior ya cierra el vector de rebinding en este endpoint solo POST.

Versiones del protocolo MCP

El servidor es de doble era: sirve la revisión sin estado MCP 2026-07-28 y las revisiones anteriores basadas en handshake (2025-11-25 y anteriores) desde el mismo endpoint, por lo que los clientes existentes siguen funcionando. Se ejecuta sin estado en ambos casos y nunca genera un Mcp-Session-Id, lo que significa que se puede escalar horizontalmente sin afinidad de sesión.

Notas sobre el conector remoto

• Anthropic se conecta a tu endpoint MCP alojado desde su infraestructura en la nube.

• Anthropic no configura los ajustes internos de tu backend de Snowstorm, como base_url, user_agent o la autenticación de destino. Esos permanecen en la configuración de tu servidor.

• manifest.json en este repositorio es para escenarios de empaquetado local, no para el flujo de conector remoto alojado.

Related MCP server: Smart EHR MCP Server

Uso autohospedado y local

Usa este modo cuando quieras ejecutar el servidor MCP tú mismo contra tu propio backend de Snowstorm o Snowstorm Lite, ya sea localmente, en infraestructura privada, o para empaquetado estilo Claude Desktop / MCPB.

Inicio rápido de desarrollo

uv venv
uv pip install -e ".[dev]"
uv run pytest -q
./scripts/check.sh

Para los flujos de trabajo de pruebas unitarias frente a las de integración (incluida la configuración del stack de Docker y la importación de RF2), consulta docs/testing.md.

Stack de integración Docker (Snowstorm + Lite)

Inicia los contenedores locales para las pruebas de integración:

docker compose -f docker-compose.integration.yml up -d

Importa un archivo RF2 local tanto en Snowstorm como en Snowstorm Lite:

dev/integration/import_snomed.sh \
  --rf2-zip ../SnomedCT_InternationalRF2_PRODUCTION_20251101T120000Z.zip

Ejecuta las pruebas de integración contra cada backend. Establece SNOWSTORM_MCP_TEST_CONFIG en tu .env para que apunte a la configuración correspondiente y, a continuación:

uv run pytest -q tests/integration

Ejecutar el servidor localmente

El servidor lee su configuración de un archivo YAML (consulta example-configs/config.local.yaml). Crea un archivo .env en la raíz del proyecto para establecer la ruta de configuración y cualquier secreto (consulta .env.example):

cp .env.example .env
# edit .env to point at your config file

El servidor carga automáticamente .env desde el directorio de trabajo actual al iniciarse. Las variables de entorno del shell existentes tienen prioridad sobre los valores de .env.

stdio (para Claude Desktop y la mayoría de los clientes MCP):

uv run snowstorm-mcp-server --transport stdio

Usa --log-level DEBUG|INFO|WARNING|ERROR para controlar la verbosidad (por defecto: INFO). Los registros van a stderr y Claude Desktop los captura en mcp-server-snowstorm.log. El servidor imprime la configuración de protecciones activa al iniciarse para que puedas confirmar que los ajustes se están cargando desde el archivo de configuración correcto.

Registro

Por defecto, el servidor registra un objeto JSON por línea con una marca de tiempo UTC, que los agregadores de registros pueden analizar directamente:

{"timestamp": "2026-07-13T10:29:04.929Z", "level": "ERROR", "logger": "snowstorm_mcp_server.mcp_app", "message": "Tool call failed [E_BACKEND_HTTP]: HTTP 502 ...", "error_code": "E_BACKEND_HTTP", "error_type": "HttpRequestError", "status_code": 502}

Los fallos de las herramientas incluyen campos estructurados (error_code, error_type, status_code) para que puedas desglosar la tasa de errores por causa. Las activaciones de protecciones (límites de velocidad, ECL bloqueado, detección de recorridos) se registran como advertencias. Usa --log-format text para la salida tradicional legible por humanos durante el desarrollo local.

Streamable HTTP (para clientes MCP basados en HTTP):

uv run snowstorm-mcp-server --transport streamable-http

El transporte independiente sse se eliminó en favor de Streamable HTTP. El transporte HTTP+SSE está en desuso desde MCP 2025-03-26 y está formalmente en desuso según la política de ciclo de vida de funciones a partir de 2026-07-28.

Ejemplo de configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "snowstorm": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/snowstorm-mcp-server",
        "snowstorm-mcp-server",
        "--transport", "stdio"
      ]
    }
  }
}

Nota: Claude Desktop ejecuta uv desde el directorio del proyecto, por lo que recoge el archivo .env automáticamente. Si prefieres variables de entorno explícitas, pásalas mediante la clave "env" en la configuración de Claude Desktop.

Empaquetado local / instalaciones MCPB

Si instalas el servidor desde una entrada de Connector Directory, el manifiesto solicita una ruta de archivo de configuración y la pasa como --config al iniciarse. Elige uno de los archivos YAML en example-configs/ para el desarrollo local, o proporciona la ruta a tu propia configuración de despliegue de Snowstorm/Snowstorm Lite.

Configuración

Consulta example-configs/config.local.yaml (Snowstorm en http://localhost:8080).

Restricción del tipo de backend

Una única configuración debe usar o bien destinos de Snowstorm o bien de Snowstorm Lite: no se admite mezclar ambos en la misma configuración. El campo server_mode debe coincidir con el tipo de destino ("snowstorm" para destinos Snowstorm, "lite" para destinos Lite).

Se admiten múltiples instancias de Snowstorm Lite (una por edición de SNOMED).

Ejemplo de configuración Lite multiedición

server_mode: "lite"
default_terminology: snomedct
response_limits:
  max_expand_contains: 100
  max_search_hits: 50
  max_synonyms: 25

# Guards — all values shown are defaults. Omit the block to use defaults.
# For public-facing HTTP deployments, do per-client limiting at the reverse
# proxy: MCP 2026-07-28 removed sessions, so per_session_rate_limit_calls
# only has an effect on stdio.
# guards:
#   rate_limit_calls: 10
#   rate_limit_window_seconds: 60
#   max_concurrent_requests: 3
#   max_count_per_call: 500
#   large_result_threshold: 1000
#   max_children_calls_per_minute: 5
#   per_session_rate_limit_calls: null   # stdio only; no effect over HTTP
#   block_zero_cardinality_on_large_sets: false  # set true to block [0..0] on top-level roots
#   enable_expansion_size_guard: false   # preflight summary check for any non-summary expansion
#   expansion_count_threshold: 20000     # block if total concepts exceeds this value
#   size_cache_ttl_seconds: 86400

targets:
  lite-int:
    base_url: "http://localhost:8081"
    mode: "lite"
    terminology_name: "snomedct"
    fhir_path: "/fhir"
    auth:
      mode: "none"

  lite-us:
    base_url: "http://localhost:8082"
    mode: "lite"
    terminology_name: "snomedct-us"
    fhir_path: "/fhir"
    auth:
      mode: "bearer"
      token: "${SNOWSTORM_LITE_TOKEN}"

Enrutamiento basado en terminología

Este servidor enruta las solicitudes por terminología (edición de SNOMED), no por destino de backend.

• Snowstorm: Las terminologías se descubren automáticamente desde GET /codesystems. El shortName de cada sistema de códigos (en minúsculas) se convierte en el nombre de la terminología (p. ej., snomedct, snomedct-us). La ruta de la rama se usa automáticamente para las operaciones nativas de Snowstorm.

• Snowstorm Lite: Cada instancia sirve una terminología. Configura terminology_name en la configuración del destino.

Terminología predeterminada

Establece default_terminology en la configuración para permitir que los llamadores omitan el parámetro terminology. Si solo hay una terminología disponible, se convierte en la predeterminada automáticamente.

Herramientas MCP disponibles

Todas las herramientas aceptan un parámetro opcional terminology (p. ej., "snomedct-us"). La mayoría de las herramientas también aceptan target opcional para restringir el enrutamiento o desambiguar la selección de destino. Si se omite, se utiliza la terminología predeterminada.

Anulaciones de secretos de entorno

Los secretos se pueden inyectar en tiempo de ejecución mediante variables de entorno en lugar de confirmar valores:

• Interpolación de marcadores de posición en la configuración: ${ENV_VAR} o ${ENV_VAR:-default}

• Variables de anulación de secretos de autenticación de destino:

  • SNOWSTORM_MCP_TARGETS__<TARGET_NAME_UPPER>__AUTH__PASSWORD

  • SNOWSTORM_MCP_TARGETS__<TARGET_NAME_UPPER>__AUTH__TOKEN

Ejemplos de llamadas a herramientas MCP

list_terminologies:

{}

Forma de respuesta esperada:

{
  "terminologies": [
    {"name": "snomedct", "backend_type": "snowstorm", "branch_path": "MAIN"},
    {"name": "snomedct-us", "backend_type": "lite", "branch_path": null}
  ],
  "default_terminology": "snomedct"
}

server_capabilities (terminología predeterminada):

{}

Forma de respuesta esperada:

{
  "terminology": "snomedct",
  "backend_type": "snowstorm",
  "reachable": true,
  "fhir_base_url": "http://localhost:8080/fhir",
  "capabilities": {"has_fhir": true, "has_native_api": true, "has_lite_load_package": false},
  "fhir_metadata_summary": {"resourceType": "CapabilityStatement", "fhirVersion": "4.0.1"}
}

fhir_metadata en modo solo resumen (omite el cuerpo sin procesar de CapabilityStatement):

{"terminology": "snomedct", "include_raw": false}

Forma de respuesta esperada:

{
  "terminology": "snomedct",
  "fhir_base_url": "http://localhost:8080/fhir",
  "summary": {"resourceType": "CapabilityStatement", "fhirVersion": "4.0.1"}
}

snomed_lookup:

{"code": "404684003", "terminology": "snomedct"}

Forma de respuesta esperada:

{
  "terminology": "snomedct",
  "code": "404684003",
  "found": true,
  "display": "Clinical finding",
  "system": "http://snomed.info/sct"
}

Si el código no existe en la edición, la herramienta devuelve un resultado negativo estructurado en lugar de un error:

{
  "terminology": "snomedct",
  "code": "99999999999",
  "found": false,
  "message": "Code '99999999999' was not found in this SNOMED CT edition/version. Verify the concept ID or search for the concept by term."
}

snowstorm_search_concepts (solo Snowstorm):

{"terminology": "snomedct", "term": "myocardial infarction", "limit": 5}

Forma de respuesta esperada:

{
  "terminology": "snomedct",
  "term": "myocardial infarction",
  "branch": "MAIN",
  "returned": 5,
  "hits": [{"concept_id": "22298006", "pt": "Myocardial infarction"}]
}

Ejemplos de uso

Estos ejemplos muestran cómo un asistente de IA utiliza las herramientas del servidor en respuesta a preguntas en lenguaje natural.

Ejemplo 1 — Consulta de un concepto clínico

Usuario: "¿Qué es el concepto SNOMED CT 22298006?"

El asistente llama a snomed_lookup con {"code": "22298006"} y recibe el término preferido del concepto ("Myocardial infarction"), su URI de sistema SNOMED CT y cualquier propiedad asociada. El asistente puede entonces explicar el concepto al usuario en lenguaje sencillo, incluido su significado clínico.

Ejemplo 2 — Comprobación de una relación jerárquica

Usuario: "¿Es la diabetes mellitus tipo 2 un tipo de trastorno endocrino en SNOMED CT?"

El asistente llama a snomed_subsumes con {"code_a": "362969004", "code_b": "44054006"} (Trastorno endocrino y Diabetes mellitus tipo 2, respectivamente). La respuesta indica si code_a subsume a code_b, confirmando o negando la relación IS-A.

Ejemplo 3 — Búsqueda de conceptos por término clínico

Usuario: "Busca conceptos SNOMED CT relacionados con 'atrial fibrillation'."

El asistente llama a snomed_expand con {"filter": "atrial fibrillation", "count": 10} para buscar en toda la terminología. La respuesta devuelve los conceptos coincidentes con sus ID, términos preferidos y si están activos, lo que permite al asistente presentar una lista concisa de coincidencias clínicamente relevantes.

Operaciones FHIR y Snowstorm con varias ediciones

Para las operaciones nativas de Snowstorm (búsqueda, detalle de concepto), la ruta de rama de la terminología se utiliza automáticamente para seleccionar la edición correcta.

Para las operaciones FHIR ($lookup, $validate-code, $subsumes), la terminología se enruta al servidor backend correcto. En una instancia de Snowstorm con varias ediciones, es posible que también deba especificar el parámetro version de FHIR para una selección precisa de la edición, ya que la selección de la edición FHIR se rige por los parámetros system/version en lugar de por las rutas de rama.

Las notas adicionales sobre capacidades del backend y los límites del alcance de v0.1 están documentadas en docs/v0.1-capability-matrix.md. Los pasos de etiquetado de versiones y pruebas de humo están en docs/release-v0.1-checklist.md.

Protecciones de rendimiento

Todas las herramientas que realizan llamadas HTTP al backend comparten un conjunto común de protecciones para evitar la sobrecarga de la instancia de Snowstorm. Estas se aplican independientemente de la herramienta que se llame: server_health, server_capabilities, fhir_metadata, snomed_expand, snomed_lookup, snomed_validate_code, snomed_subsumes, todas las herramientas de jerarquía y todas las herramientas nativas snowstorm_*.

Protecciones siempre activas:

Solo por proceso. Las protecciones utilizan estado en memoria. Si ejecuta varios procesos de servidor detrás de un balanceador de carga, cada proceso aplica sus propios límites independientes. Para límites compartidos entre procesos, se necesita una implementación respaldada por Redis.

Limitación de tasa por sesión (solo stdio)

MCP 2026-07-28 eliminó las sesiones a nivel de protocolo. Con Streamable HTTP, cada solicitud ahora es independiente, por lo que per_session_rate_limit_calls no tiene nada estable sobre lo que basarse y nunca se activará: cada solicitud recibe una ventana nueva y vacía. El servidor registra una advertencia al inicio si se configura. Sigue funcionando en stdio, donde un proceso atiende exactamente a un cliente. Para implementaciones HTTP, realice la limitación por cliente en el proxy inverso (Nginx limit_req, Caddy rate_limit, Cloudflare, etc.), que se basa en la identidad de red que el protocolo ya no transporta.

El límite de tasa global se comparte entre todos los llamadores y no se ve afectado: sigue siendo el control que limita la carga total del backend:

guards:
  rate_limit_calls: 30            # global ceiling across all callers
  rate_limit_window_seconds: 60
  per_session_rate_limit_calls: 8 # stdio only; a no-op over HTTP

Cuando se establece per_session_rate_limit_calls, cada sesión obtiene su propia ventana deslizante independiente utilizando el mismo rate_limit_window_seconds. Las sesiones se rastrean por identidad de objeto y se eliminan automáticamente cuando el objeto de sesión subyacente es recolectado como basura.

Herramientas sin protección

Las herramientas en memoria que no llaman al backend de Snowstorm se dejan intencionalmente sin protección: list_terminologies.

Restricción de búsqueda nativa de Snowstorm (importante)

La herramienta MCP snowstorm_search_concepts llama al endpoint nativo de búsqueda de descripciones de Snowstorm (GET /browser/{branch}/descriptions), que puede rechazar consultas muy cortas (por ejemplo, AD, B2) con HTTP 400.

Orientación práctica:

• Utilice al menos 3 caracteres buscables (letras/dígitos).

• Para acrónimos cortos, incluya contexto (por ejemplo, use una frase más larga en lugar de AD).

El servidor MCP valida esto de forma temprana: un término demasiado corto devuelve una respuesta correcta con cero resultados y un campo notice que explica la restricción, sin llamar a Snowstorm. Los resultados negativos esperados (un término demasiado corto o un código de snomed_lookup que no existe) se devuelven como datos estructurados en lugar de errores de herramienta, por lo que las métricas de error de MCP solo reflejan fallos reales.

Política de privacidad

Este servidor actúa como un proxy sin estado entre un cliente MCP y un backend SNOMED CT configurado (Snowstorm o Snowstorm Lite). No recopila, almacena ni procesa datos personales y no envía datos a ningún tercero más allá del backend configurado. Todo el contenido de las consultas se reenvía al backend y se descarta después de entregar la respuesta. Cuando la limitación de tasa por sesión está habilitada, el servidor mantiene marcas de tiempo de llamadas en memoria por sesión únicamente para hacer cumplir la limitación de tasa; este estado no contiene PII y se descarta automáticamente cuando finaliza la sesión.

Las respuestas contienen contenido de terminología SNOMED CT. El acceso a dicho contenido a través de este servidor se rige por el Acuerdo de Licencia del Navegador SNOMED CT (consulte Licencia más abajo). Cuando se implementa como un servicio alojado, la infraestructura de alojamiento puede conservar los registros de acceso estándar del servidor web (dirección IP, marca de tiempo, ruta de solicitud) con fines operativos.

Para conocer la política de privacidad completa, consulte PRIVACY.md.

Soporte

• Problemas e informes de errores: GitHub Issues

• Licencias y contenido de SNOMED CT: SNOMED International

• Consultas generales: info@snomed.org

Licencia

El software del servidor está licenciado bajo Apache 2.0.

El contenido de SNOMED CT devuelto por este servidor no está cubierto por esa licencia. El acceso a SNOMED CT a través de este servidor se rige por el Acuerdo de Licencia del Navegador SNOMED CT, la misma base sobre la que se proporciona el Navegador SNOMED CT público. En resumen, los usuarios finales que no poseen una Licencia de Afiliado de SNOMED International pueden utilizar este servidor para explorar y evaluar la terminología, pero no pueden:

• copiar identificadores de SNOMED CT en un sistema de registros, base de datos o documento (uso como "Sistema de Creación de Datos" o "Sistema de Análisis de Datos");

• traducir o modificar el contenido de SNOMED CT; o

• redistribuir o compartir el contenido de SNOMED CT.

Si desea alojar este servidor usted mismo, integrar SNOMED CT en un producto o servicio, o utilizar SNOMED CT más allá de explorarlo y evaluarlo, debe obtener una licencia completa de SNOMED CT; consulte Obtener SNOMED CT. Los afiliados de SNOMED International pueden utilizar este servidor dentro de los términos de su Licencia de Afiliado. SNOMED CT es © SNOMED International; "SNOMED" y "SNOMED CT" son marcas comerciales registradas.