ServiceNow MCP

Servidor MCP de ServiceNow: 65 herramientas sobre toda la superficie REST (Tabla, Agregado, Adjunto, Conjunto de Importación, Lote, CMDB/IRE, Catálogo, Cambio, Conocimiento, Correo Electrónico) con inteligencia de scripts, trazado de flujos, ejecuciones ATF, perfiles multi-instancia y diagramas Mermaid.

Documentación

servicenow-mcp-ai — Servidor MCP de ServiceNow

npm versionnpm downloadsnodetoolsLicense: MIT
CIcoveragelast commitMCPKnown Vulnerabilities

📖 Sitio de documentación →

Un servidor de Protocolo de Contexto de Modelo que permite a un cliente MCP (VS Code, Claude Desktop, etc.) ejecutar comandos contra una instancia de ServiceNow a través de sus API REST — Table, Aggregate, Attachment, Import Set, Batch y CMDB, además de las API de plugins de Service Catalog, Change Management y Knowledge. Las credenciales se guardan en un archivo de entorno local y se pueden actualizar en tiempo de ejecución mediante una herramienta.

¿Actualizando desde 1.x? v2.0 hace que las escrituras sean plan-por-defecto: create/update/delete y las demás herramientas de escritura de registros devuelven una vista previa no mutante a menos que pases apply: true (o establezcas SN_WRITE_MODE=apply para restaurar el comportamiento v1 de "ejecutar inmediatamente"). Consulta el CHANGELOG → 2.0.0 para la nota de migración completa.

Contenidos: Demo rápida · Características · Requisitos · Configuración · Configurar credenciales · Ejecutar / depurar · Desarrollar · Herramientas · Recursos · Prompts · Estructura del proyecto · Notas de seguridad · Documentación del proyecto · Soporte

Construido y mantenido en mi tiempo libre — si te resulta útil, una propina de GitHub Sponsors lo mantiene en marcha. Las opciones completas de Soporte están cerca del final.

Demo rápida

Tres cosas que la plataforma hace difíciles, una llamada cada una. Apunta tu cliente MCP a una instancia (Configuración) y pregunta:

1. "¿Dónde se usa realmente este campo?" — cada script, regla de negocio, script de cliente, política/acción de UI y ACL que lo toca, como JSON o un gráfico Mermaid. La búsqueda de usos con calidad de IDE para la que ServiceNow no tiene botón:

// servicenow_where_used
{
  "kind": "field", // "table" | "field" | "script"
  "name": "u_cost_center",
  "mermaid": true, // also render a reference graph
}

2. "¿Qué se ejecuta cuando guardo este registro?" — la cadena completa de automatización en orden de ejecución (reglas de negocio display → before → after → async, luego flujos, workflows y notificaciones), cada una con su condición — una prueba lógica que ejecuta nada:

// servicenow_trace_table_event
{
  "table": "incident",
  "operation": "update", // insert | update | delete | query
}

3. "¿Qué cambió entre dev y prod?" — un diff en Markdown de tablas, columnas, scripts (coincididos por sys_id y luego por nombre, con un diff unificado de cada script modificado) y plugins entre dos perfiles configurados — además, bajo petición, propiedades, opciones, ACLs, notificaciones, flujos, elementos de catálogo y roles — con un código de salida compatible con CI para que un pipeline pueda bloquear un despliegue arriesgado:

servicenow-mcp-ai drift dev prod   # report on stdout; exit 1 on drift, 0 if clean

Las tres son de solo lectura y funcionan contra cualquier instancia — incluida una PDI gratuita — con el modelo y cliente de tu elección.

Características

  • API Table completa: consultar, leer, crear, actualizar y eliminar registros en cualquier tabla, con consultas codificadas, selección de campos y paginación.
  • API adicionales de ServiceNow: Aggregate (Stats), Attachment (listar/subir/descargar/eliminar), Import Set, Batch (muchas llamadas REST en una sola solicitud), además de metadatos de tablas/columnas (sys_db_object, sys_dictionary).
  • API de procesos y plugins: CMDB (CRUD de CI con conocimiento de clases + meta, lecturas de relaciones desde cmdb_rel_ci, identificación y conciliación IRE con un plan solo de identificación), Service Catalog (explorar/ordenar elementos), Change Management (creación tipada + detección de conflictos) y Knowledge (búsqueda de artículos). Las API con ámbito de plugin informan claramente cuando no están activas en la instancia.
  • Inteligencia de scripts: leer y buscar el código propio de la instancia (reglas de negocio, script includes, scripts de cliente, políticas/acciones de UI, trabajos programados, scripts de transformación/REST, ACLs — y, aún no verificado en una instancia en vivo, widgets de Service Portal, páginas/scripts/macros de UI, procesadores, scripts de correo/fix/ validación, acciones de script, fuentes de datos, funciones de mensajes REST, mapas/entradas de transformación, scripts de cliente de catálogo y cálculos/ valores predeterminados de diccionario) y obtener la imagen completa de automatización de una tabla — todo de solo lectura a través de la API Table. servicenow_search_code devuelve cada línea coincidente por artefacto (hasta 20, con una línea de contexto a cada lado) y, como servicenow_where_used, acepta un scope de aplicación opcional. servicenow_where_used también encuentra referencias estructurales — campos de referencia de diccionario, diseños de lista y formulario, variables de catálogo, entradas de flujo e informes — en una sección structural separada.
  • Trazado de flujos y verificación de código (Fase 8): trazar de forma determinista qué ejecuta una operación de tabla (paquete flows — reglas de negocio, flujos, workflows y notificaciones, en orden, con un diagrama de flujo Mermaid), leer flujos de Flow Designer e historial de ejecución, y hacer lint de scripts contra un conjunto de reglas local con un informe agregado de salud de código (codecheck). Ejecutar pruebas ATF a través de la API CI/CD (atf, opt-in, no predeterminado — las herramientas de ejecución se ejecutan en la instancia).
  • Deshacer basado en diario (revert): listar el diario de escritura local y revertir un create/update/delete aplicado — con una verificación de desviación contra ediciones posteriores.
  • Lecturas genéricas de artefactos (artifacts, opt-in): listar y leer cualquier tipo de artefacto registrado — políticas de UI con sus acciones, páginas de portal con su diseño, flujos, elementos de catálogo y más — con estado de ámbito y gestión de SDK.
  • Conciencia de update sets (updatesets, opt-in): listar update sets, resumir un conjunto por artefacto, compararlo con otro perfil o una instantánea — y vincular escrituras de Table aplicadas a un update set nombrado (update_set / SN_UPDATE_SET), restaurando el conjunto actual del usuario después.
  • Operaciones y salud de datos (ops, opt-in): lecturas acotadas de "por qué está lento" del registro del sistema, la cola del programador, la cola de correo saliente y semáforos, además de servicenow_data_health — claves duplicadas, referencias huérfanas y obsoletas para una tabla, a partir de conteos de la API Aggregate.
  • Lecturas de operaciones (opt-in): historial de cambios de un registro desde sys_audit y sys_journal_field (history — incluidos los comentarios y notas de trabajo que la API Table devuelve vacíos), propiedades del sistema con secretos enmascarados y un conjunto registrado y reversible (properties), y búsquedas de usuario / grupo / rol con membresías (directory). Las ejecuciones de ATF pueden esperar su resultado (wait_seconds), y las inserciones de Import Set informan la ejecución de transformación y los mapas.
  • Autodocumentación: una base de conocimiento local en Markdown (lectura/escritura/búsqueda) más generadores deterministas de Mermaid (diagramas ER a partir de referencias, diagramas de flujo de ciclo de vida de registros a partir de reglas de negocio) para que el servidor construya contexto duradero y reutilizable.
  • Prompts: flujos de trabajo listos (triaje de incidentes, análisis de impacto de cambios, documentar una tabla, diagnosticar una instancia lenta) que orquestan las herramientas.
  • Paquetes de herramientas: cargar solo los grupos de herramientas que necesitas mediante SN_TOOL_PACKAGES (perfil predeterminado core; all habilita todo).
  • Autenticación Básica u OAuth 2.0 sobre HTTPS; la contraseña/token nunca se devuelve en el eco.
  • Controles de privilegio mínimo: listas de permitir/denegar de tablas y un modo global de solo lectura.
  • Resiliencia: tiempo de espera por solicitud, reintento con retroceso y Retry-After, protección SSRF y un guardián de tamaño de resultado.
  • Anotaciones de herramientas y recursos MCP, cargas de error estructuradas y registro estructurado en stderr.
  • Credenciales en un archivo de entorno (proyecto, ~/.config, o SN_ENV_FILE), actualizables en tiempo de ejecución mediante servicenow_set_credentials.

Requisitos

  • Node.js 20+ (obligatorio: engines + un guardián de tiempo de ejecución con un mensaje claro; el proyecto apunta a la versión en .nvmrc).

Configuración

Desde el código fuente (para desarrollo):

npm install
npm run build

O ejecuta el paquete publicado directamente, sin clonar:

npx servicenow-mcp-ai

Instalar en tu cliente MCP

Cada cliente lanza el mismo comando stdio, npx -y servicenow-mcp-ai (Node.js 20+), bajo el nombre de servidor servicenow. Los enlaces de un clic y los fragmentos a continuación no llevan credenciales: mantenlas en el archivo de entorno (~/.config/servicenow-mcp-ai/.env, consulta Configurar credenciales), ejecuta el npx servicenow-mcp-ai login único para OAuth, o pide al asistente que llame a servicenow_set_credentials una vez que el servidor esté conectado. Una variable de entorno real establecida en una configuración de cliente anula el archivo de entorno, así que solo agrega un bloque env cuando realmente lo necesites — y nunca pongas SN_PASSWORD u otros secretos en una configuración de cliente que compartas o confirmes (consulta SECURITY.md).

Install in VS Code Install in VS Code Insiders Install in Cursor

ClienteUna líneaArchivo de configuración
VS Code (Copilot Chat)Botón arriba, o code --add-mcp (abajo) — o la extensión ServiceNow MCP.vscode/mcp.json (servers)
VS Code InsidersBotón arriba, o code-insiders --add-mcp (abajo).vscode/mcp.json (servers)
Claude Codeclaude mcp add servicenow -- npx -y servicenow-mcp-ai, o el plugin.mcp.json (mcpServers)
Claude Desktop— (edita el archivo de configuración)claude_desktop_config.json (mcpServers)
CursorBotón arriba, o el deeplink cursor:// (abajo)~/.cursor/mcp.json o .cursor/mcp.json (mcpServers)
Windsurf— (edita el archivo de configuración)~/.codeium/windsurf/mcp_config.json (mcpServers)
Cline— (MCP Servers → Configure MCP Servers)cline_mcp_settings.json (mcpServers)
Zed— (edita la configuración)settings.json (context_servers)
JetBrains AI Assistant— (Settings → Tools → AI Assistant → Model Context Protocol)Diálogo JSON (mcpServers)
Gemini CLI— (edita la configuración)~/.gemini/settings.json (mcpServers)
Codex CLIcodex mcp add servicenow -- npx -y servicenow-mcp-ai~/.codex/config.toml ([mcp_servers.servicenow])
VS Code / VS Code Insiders

La ruta de configuración cero es la extensión ServiceNow MCP desde el Marketplace (code --install-extension ivanbbaev.servicenow-mcp-ai); registra el servidor en Copilot Chat (modo agente) automáticamente, sin mcp.json. Fuente: extension/.

Sin la extensión, agrega el servidor desde una terminal (perfil de usuario):

code --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'
code-insiders --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'

Los deeplinks crudos detrás de los botones (pégalos en la barra de direcciones del navegador):

vscode:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D
vscode-insiders:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D

O un archivo de espacio de trabajo, .vscode/mcp.json:

{
  "servers": {
    "servicenow": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}
Claude Code

Plugin (configuración cero — instala el servidor conectado):

/plugin marketplace add IvanBBaev/servicenow-mcp-ai
/plugin install servicenow-mcp-ai

El plugin también incluye cinco habilidades de workflow — consulta Habilidades del plugin.

CLI — --scope user lo hace disponible en cada proyecto; --env establece una variable no secreta (el host de la instancia) y deja los secretos en el archivo de entorno. Un valor establecido de esta manera gana sobre el archivo de entorno, así que elimina --env si cambias de instancia con servicenow_set_credentials:

claude mcp add servicenow --scope user --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai
Claude Desktop

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\ (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

Reinicia Claude Desktop después de guardar.

Cursor

Usa el botón de arriba, o abre el deeplink directamente:

cursor://anysphere.cursor-deeplink/mcp/install?name=servicenow&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlcnZpY2Vub3ctbWNwLWFpIl19

O edita ~/.cursor/mcp.json (global) / .cursor/mcp.json (proyecto) con el mismo bloque mcpServers que Claude Desktop.

Windsurf, Cline, JetBrains AI Assistant

Los tres aceptan el bloque mcpServers de Claude Desktop sin cambios:

  • Windsurf — ~/.codeium/windsurf/mcp_config.json (Cascade → MCP servers → View raw config), luego actualiza la lista de servidores.
  • Cline — Icono de MCP Servers → Configure MCP Servers abre cline_mcp_settings.json.
  • JetBrains AI Assistant — Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add → As JSON, pega el bloque.
{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}
Zed

En el settings.json de Zed (Zed → Settings → Open Settings):

{
  "context_servers": {
    "servicenow": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"],
      "env": {}
    }
  }
}
Gemini CLI

~/.gemini/settings.json (usuario) o .gemini/settings.json (proyecto):

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

Verifícalo con /mcp dentro de una sesión de Gemini CLI.

Codex CLI
codex mcp add servicenow --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai

O ~/.codex/config.toml:

[mcp_servers.servicenow]
command = "npx"
args = ["-y", "servicenow-mcp-ai"]
# Optional, non-secret only — secrets stay in ~/.config/servicenow-mcp-ai/.env:
# env = { SN_INSTANCE = "your-instance.service-now.com" }

¿Prefieres una instalación global (npm install -g servicenow-mcp-ai)? Reemplaza "command": "npx", "args": ["-y", "servicenow-mcp-ai"] con "command": "servicenow-mcp-ai" en cualquier fragmento. El MCP Inspector funciona de la misma manera: npx @modelcontextprotocol/inspector npx -y servicenow-mcp-ai.

Los enlaces de un clic se generan a partir de package.json mediante scripts/install-links.mjs (node scripts/install-links.mjs los imprime); test/install-links.test.js falla si este README o el sitio de documentación se desvían de las cadenas generadas.

Inicio rápido

La ruta más rápida son tres líneas de autenticación Basic: establece estas (en el archivo de entorno o en el entorno real) y estarás conectado:

SN_INSTANCE=dev12345.service-now.com
SN_USER=your.username
SN_PASSWORD=your-password

Todo lo demás es ajuste opcional; consulta la referencia completa de Variables de entorno para el resto.

Más allá de una prueba rápida, prefiere OAuth sobre una contraseña almacenada. Para cualquier cosa compartida o de larga duración, ejecuta el npx servicenow-mcp-ai login único en su lugar — almacena un token de actualización, no tu contraseña. Consulta Configurar credenciales → OAuth 2.1.

Verifica tu configuración

Una vez establecidas las tres variables, confirma la conexión antes de comenzar:

  1. Ejecuta la herramienta servicenow_test_connection — lee un registro sys_user y reporta ok, estado HTTP y latencia.
  2. Ejecuta servicenow_check_capabilities — previsualiza qué tablas sys_* restringidas por administrador puede leer realmente el usuario conectado.

O haz ambas desde el shell de una sola vez:

npx servicenow-mcp-ai doctor   # checks credentials, reachability and capabilities

¿Prefieres que te lo pregunten? npx servicenow-mcp-ai init solicita la instancia, el método de autenticación y las credenciales, escribe el archivo de entorno y ejecuta doctor — consulta Interfaz de línea de comandos.

Configurar credenciales

Las credenciales viven en .env en la raíz del proyecto (ignorado por git):

SN_INSTANCE=your-instance.service-now.com
SN_USER=your.username@example.com
SN_PASSWORD=your-password

SN_INSTANCE acepta dev12345, dev12345.service-now.com o una URL completa https://.

También puedes establecerlas o cambiarlas en tiempo de ejecución llamando a la herramienta servicenow_set_credentials — los nuevos valores se escriben directamente de vuelta al archivo de entorno. Mover un perfil configurado a una instancia diferente requiere user y password en la misma llamada (los secretos almacenados nunca se envían a otro host), y el cambio debe ser confirmado por el cliente — los clientes sin soporte de elicitación son rechazados a menos que SN_ALLOW_UNCONFIRMED_CREDENTIAL_CHANGE=1 esté establecido.

La herramienta también establece el método de autenticación (auth), el ID de cliente OAuth (oauth_client_id) y el grant (oauth_grant). Los secretos — la clave API y el secreto de cliente OAuth — nunca son argumentos de herramienta: listalos en request_secrets y el servidor los solicita mediante un aviso de elicitación, por lo que nunca aparecen en una llamada de herramienta registrada, en el resultado o en el diario de escritura. Un cliente sin soporte de elicitación es rechazado (la exclusión anterior no aplica a los secretos); establece esas claves en el archivo de entorno en su lugar. La regla de cambio de instancia sigue el método de autenticación resultante: un perfil de clave API necesita una nueva clave API, un perfil OAuth client_credentials un nuevo secreto de cliente, el grant OAuth password usuario, contraseña y secreto de cliente, Basic / none usuario y contraseña; los perfiles de token portador, refresh_token y jwt_bearer no se pueden mover con esta herramienta.

servicenow_get_status (authWarnings), servicenow_list_instances y doctor evalúan cada perfil contra su propio método de autenticación — un perfil de clave API no necesita contraseña — y reportan el método, el grant OAuth, el estado del token de actualización y el modo de escritura, nunca un valor secreto. Cuando el grant de token de actualización devuelve un token de actualización rotado, se escribe de vuelta a la clave de entorno de la que se leyó; si el archivo de entorno no se puede escribir, el nuevo token se mantiene en memoria (se pierde al reiniciar) y se registra y muestra una advertencia mediante get_status / doctor. Los valores que el servidor escribe mantienen las rutas de Windows literales (las barras invertidas están entre comillas simples) y un archivo de entorno CRLF permanece CRLF. En Windows, el archivo de entorno hereda la ACL de su carpeta — restringe el acceso tú mismo (por ejemplo icacls .env /inheritance:r /grant:r "%USERNAME%:F"); el servidor solo advierte, nunca ejecuta icacls.

El archivo de entorno se resuelve en este orden: SN_ENV_FILE, luego ~/.config/servicenow-mcp-ai/.env (XDG) si está presente, luego el .env de la raíz del proyecto. Una instalación global/npx por lo tanto escribe en tu configuración de usuario en lugar de en node_modules. Las variables de entorno reales siempre tienen prioridad sobre el archivo.

Primera ejecución: el modelo se configura solo

En initialize el servidor envía instructions construido a partir de la configuración en vivo: los paquetes habilitados y el recuento de herramientas, el modo de escritura, el perfil activo y, cuando no hay nada configurado, lo que falta y cómo solucionarlo. Hasta entonces, cada herramienta de instancia falla con error.code: "NOT_CONFIGURED" y una pista que nombra servicenow_set_credentials. Una primera sesión con un archivo de entorno vacío se ve así (resumido):

instructions  Credentials: NOT configured (missing instance, user, password). Instance tools
              fail with error.code NOT_CONFIGURED until fixed. To configure: ask the user for
              the instance and credentials, call servicenow_set_credentials, then
              servicenow_test_connection. Never guess or echo a password.
user          How many open P1 incidents do we have?
model         Which instance, user and password should I connect with?
user          dev12345, admin, ••••••
tool call     servicenow_set_credentials { instance: "dev12345", user: "admin", password: … }
tool result   { message: "Credentials saved", profile: "default", configured: true, password: "***" }
tool call     servicenow_test_connection {}
tool result   { ok: true, … }
tool call     servicenow_aggregate { table: "incident", query: "active=true^priority=1" }
model         There are 7 open P1 incidents.

servicenow_get_status luego muestra el estado en vivo: versión del servidor, tiempo de actividad y transporte, policy.summary, límites, redacción, el directorio de documentación, contadores de escritura, la fuente del perfil y profileDetails (modo de autenticación por perfil, modo de escritura y claves faltantes) — nunca un valor secreto.

OAuth 2.1 (Authorization Code + PKCE) — recomendado

Registra un endpoint de API OAuth de Authorization Code en ServiceNow con una URL de redirección de bucle invertido (por ejemplo, http://localhost:53682/callback), establece SN_OAUTH_CLIENT_ID (y SN_OAUTH_CLIENT_SECRET para un cliente confidencial), luego ejecuta el inicio de sesión interactivo único:

npx servicenow-mcp-ai login

Abre el navegador, apruebas, y el token de actualización obtenido se almacena en tu archivo de entorno. El servidor luego se ejecuta de forma no interactiva (grant refresh_token) — nunca se almacena una contraseña. PKCE (S256) siempre se usa.

El grant de contraseña OAuth 2.0 (ROPC) está obsoleto en OAuth 2.1 y deshabilitado en muchas instancias; prefiere login. Los grants client_credentials y refresh_token siguen siendo compatibles para cuentas de servicio. Consulta .env.example.

Métodos de autenticación compatibles

Cada método de autenticación REST entrante que ofrece ServiceNow está cubierto:

MétodoSN_AUTHEstablecerNotas
BasicbasicSN_USER / SN_PASSWORDPredeterminado.
OAuth 2.1 — Authorization Code + PKCEoauthnpx servicenow-mcp-ai loginRecomendado. Interactivo, almacena un token de actualización.
OAuth — Client CredentialsoauthSN_OAUTH_GRANT=client_credentialsServicio a servicio.
OAuth — Refresh TokenoauthSN_OAUTH_GRANT=refresh_token + SN_OAUTH_REFRESH_TOKENEstablecido por login.
OAuth — JWT BeareroauthSN_OAUTH_GRANT=jwt_bearer + SN_OAUTH_JWT_KEYAserción RS256; sin contraseña.
OAuth — Password (ROPC)oauthSN_OAUTH_GRANT=passwordObsoleto.
API KeyapikeySN_API_KEYEncabezado x-sn-apikey.
Bearer tokentokenSN_BEARER_TOKEN o SN_TOKEN_FILEToken preobtenido, usado tal cual. Un token rechazado (401) relee SN_TOKEN_FILE una vez, de lo contrario falla con AUTH_EXPIRED.
Mutual TLS (certificado de cliente)none (o en capas)SN_TLS_CLIENT_CERT / _KEYEl certificado se asigna a un usuario; necesita undici opcional.

Variables de entorno

Toda la configuración se lee de .env (o del entorno de proceso real, que tiene prioridad). Solo las primeras tres son obligatorias; el resto son ajustes opcionales. Consulta .env.example para una plantilla.

VariableRequeridoPredeterminadoDescripción
SN_INSTANCEsí—Nombre de instancia, host o URL de https:// (dev12345, dev12345.service-now.com).
SN_USERsí—Nombre de usuario de ServiceNow para autenticación básica.
SN_PASSWORDsí—Contraseña de ServiceNow. Nunca se registra ni se devuelve mediante ninguna herramienta.
SN_TIMEOUT_MSno30000Tiempo de espera por solicitud en milisegundos.
SN_MAX_RETRIESno2Reintentos para fallos transitorios (429/5xx, errores de red). Las escrituras no idempotentes solo se reintentan en errores de conexión.
SN_MAX_RECORDSno10000Límite máximo de registros devueltos por una consulta de fetchAll.
SN_MAX_RESULT_CHARSno100000Presupuesto de caracteres para un resultado de consulta antes de truncarse para el cliente; la nota de truncamiento menciona a format:"file". Una instantánea, comparación o resultado de diagrama que supere el presupuesto se devuelve completo con un note.
SN_OVERSIZE_TO_FILEnofalseS-11: escribir una instantánea, comparación o resultado de diagrama que supere SN_MAX_RESULT_CHARS en un archivo bajo SN_DOCS_DIR (<profile>/exports/, <profile>/diagrams/) y devolver {path, bytes, preview} en su lugar.
SN_RETRY_AFTER_MAX_MSno60000Límite superior respetado para un encabezado Retry-After en 429/503; un valor mayor se ajusta para que un upstream con mal comportamiento no pueda dejar al cliente en espera durante minutos.
SN_DEADLINE_MSno—Presupuesto total de tiempo de pared para una solicitud lógica a través de reintentos, retroceso, espera en cola y reautenticación OAuth; el valor predeterminado es max(120000, 2 × SN_TIMEOUT_MS). Un reintento que no quepa en el presupuesto restante no se intenta: la llamada falla con el código DEADLINE_EXCEEDED.
SN_ALLOWED_HOSTSno—Lista de permitidos separada por comas de hosts permitidos (para dominios personalizados o de nube soberana). Cuando se establece, solo se contactan los hosts coincidentes. Cuando no se establece, solo se permiten instancias de *.service-now.com y se bloquean los hosts internos/de bucle local (protección SSRF). Una entrada puede incluir un puerto (host:8443) o ser un literal IPv6 entre corchetes ([2001:db8::1]); un puerto explícito distinto de 443 o un literal IPv6 en el valor de instancia se acepta solo cuando dicha entrada coincide con él, nunca bajo la política predeterminada.
SN_MAX_BODY_BYTESno52428800Cuerpo de respuesta más grande (bytes) leído en memoria; un cuerpo declarado o transmitido mayor falla con RESPONSE_TOO_LARGE. Las redirecciones nunca se siguen: un 3xx falla con REDIRECT_BLOCKED que nombra al host de destino.
SN_AUTHnoautoMétodo de autenticación: basic, oauth, apikey, token o none (mTLS solo con certificado). Se detecta automáticamente según las claves presentes (clave API → bearer → OAuth → Básica).
SN_API_KEYno—Clave API entrante de ServiceNow, enviada como encabezado x-sn-apikey (habilita el modo apikey).
SN_BEARER_TOKENno—Un token bearer obtenido previamente, enviado textualmente como Authorization: Bearer … (habilita el modo token).
SN_TOKEN_FILEno—Archivo que contiene el token bearer (habilita el modo token; tiene prioridad sobre SN_BEARER_TOKEN). Se vuelve a leer una vez cuando la instancia rechaza el token con 401, para que un emisor externo pueda rotarlo; de lo contrario, la llamada falla con AUTH_EXPIRED.
SN_TOKEN_EXPIRES_ATno—Caducidad ISO 8601 del token bearer. get_status / doctor advierten cuando quedan menos de 24 horas, cuando ha caducado o cuando no se puede analizar.
SN_OAUTH_CLIENT_IDno—ID de cliente OAuth (su presencia habilita OAuth).
SN_OAUTH_CLIENT_SECRETno—Secreto de cliente OAuth.
SN_OAUTH_GRANTnopasswordConcesión OAuth: password (obsoleto — ROPC), client_credentials, refresh_token o jwt_bearer. El comando login lo establece en refresh_token por usted.
SN_OAUTH_JWT_KEYno—Clave privada PEM para la concesión jwt_bearer (o SN_OAUTH_JWT_KEY_FILE). Reclamaciones opcionales: SN_OAUTH_JWT_ISS (ID de cliente predeterminado), SN_OAUTH_JWT_SUB (predeterminado SN_USER), SN_OAUTH_JWT_AUD, SN_OAUTH_JWT_KID, SN_OAUTH_JWT_EXP_SEC (predeterminado 300).
SN_OAUTH_REFRESH_TOKENno—Token de actualización para la concesión refresh_token. Se obtiene automáticamente mediante npx servicenow-mcp-ai login (Código de Autorización + PKCE).
SN_OAUTH_REDIRECT_URInohttp://localhost:53682/callbackURL de redirección de bucle local para el flujo PKCE login. Debe coincidir con la redirección registrada en el endpoint OAuth.
SN_OAUTH_SCOPEno—Ámbito OAuth opcional solicitado durante login.
SN_HTTPS_PROXYno—URL de proxy HTTPS saliente (http://user:pass@proxy:3128) para todo el tráfico de ServiceNow y OAuth; requiere el paquete opcional undici. Cuando no se establece, se respetan las variables ambientales HTTPS_PROXY / HTTP_PROXY junto con NO_PROXY; SN_HTTPS_PROXY en sí es explícito e ignora NO_PROXY. Las credenciales del proxy nunca se registran.
SN_USER_AGENT_SUFFIXno—Token adicional añadido al User-Agent enviado en cada solicitud (servicenow-mcp-ai/<version> (node/<major>; <transport>; <client>)), p. ej., un ID de equipo o ticket para correlación en el registro de transacciones de la instancia. ASCII imprimible, hasta 80 caracteres.
SN_TLS_CLIENT_CERTno—Certificado de cliente (PEM) para TLS mutuo (o SN_TLS_CLIENT_CERT_FILE). Con SN_TLS_CLIENT_KEY presenta un certificado de cliente; el perfil de autenticación mutua de ServiceNow lo asigna a un usuario. Requiere el paquete opcional undici (npm i undici). El certificado y la clave deben establecerse juntos: solo uno de ellos es un error de configuración.
SN_TLS_CLIENT_KEYno—Clave privada (PEM) para el certificado de cliente (o SN_TLS_CLIENT_KEY_FILE).
SN_TLS_CAno—Paquete de CA opcional (PEM) para confiar (o SN_TLS_CA_FILE): se aplica con o sin certificado de cliente; requiere el paquete opcional undici. SN_TLS_REJECT_UNAUTHORIZED=false desactiva la verificación (no recomendado; se advierte una vez al inicio).
SN_TABLES_ALLOWno—Lista de permitidos de tablas separada por comas; cuando se establece, solo estas tablas son accesibles.
SN_TABLES_DENYno—Lista de denegados de tablas separada por comas; siempre tiene prioridad sobre la lista de permitidos.
SN_READONLYnofalseCuando es verdadero, rechaza toda creación/actualización/eliminación.
SN_ALLOW_UNCONFIRMED_CREDENTIAL_CHANGEnofalseH-2: exclusión voluntaria del operador: permite que servicenow_set_credentials continúe en clientes MCP sin soporte de elicitación (sin aviso de confirmación, sin servidor en vivo). Una denegación explícita aún se rechaza. Desactivado por defecto.
SN_WRITE_MODEnoplanplan (predeterminado) previsualiza una escritura como una diferencia antes/después sin mutar; apply ejecuta; pasar apply:true fuerza una sola llamada.
SN_DESTRUCTIVE_CONFIRMnooffH-3: confirmación para una apply:true destructiva (delete_record, delete_attachment, una batch de escritura, send_email, order_catalog_item, revert_write, change_conflicts con calculate:true) en modo plan. token: la vista previa del plan devuelve un plan_token de un solo uso y la aplicación debe devolverlo con los mismos argumentos, de lo contrario PLAN_REQUIRED; elicit: token más un aviso de confirmación en clientes con elicitación (una denegación es CONFIRM_DECLINED, registrada como rechazada). SN_WRITE_MODE=apply lo omite, excepto en un perfil marcado como prod (SN_ENV), que siempre es al menos elicit y se confirma también en modo aplicar. El valor predeterminado de 3.0 es una decisión del propietario (O-4).
SN_PLAN_TOKEN_TTL_SECno600H-3: vida útil de un plan_token en segundos (30–86400). Los tokens viven solo en el proceso del servidor y se consumen con la aplicación.
SN_BATCH_UNMAPPEDnoallowH-4: una sub-solicitud servicenow_batch cuya ruta REST no pertenece a ningún paquete de herramientas: allow la verifica contra la tabla y los ejes de solo lectura únicamente; deny la rechaza (por lo que una nueva API de plugin no puede pasar SN_PACKAGES_DENY / SN_PACKAGES_READONLY dentro de un lote). Un lote anidado siempre se rechaza. El valor predeterminado de 3.0 es una decisión del propietario (O-4).
SN_BATCH_MAX_REQUESTSno1000H-4: la mayoría de sub-solicitudes que una llamada servicenow_batch puede llevar (1–1000), verificadas antes de enviar cualquier cosa.
SN_PROTECTED_TABLES_WRITEnoallowH-11: deny rechaza escrituras en las tablas protegidas integradas (identidad, roles, ACL, sys_properties, OAuth, scripts, LDAP, certificados, fuentes de datos, mensajes REST — servicenow_explain_policy las lista) con POLICY_DENIED; una entrada exacta de SN_TABLES_ALLOW rehabilita una. Las lecturas no se ven afectadas. El valor predeterminado de 3.0 es una decisión del propietario (O-4). Por perfil: SN_PROFILE_<NAME>_PROTECTED_TABLES_WRITE.
SN_IMPORT_SET_TABLESno—H-11: patrones (*, ?) que la tabla de staging del conjunto de importación debe coincidir (p. ej., u_*,imp_*); sin establecer = cualquier tabla que permita la política de tablas.
SN_MAX_WRITES_PER_SESSIONno—H-11: la mayoría de escrituras aplicadas a la instancia por sesión (el proceso en stdio, una sesión MCP sobre HTTP; un lote cuenta sus sub-solicitudes de escritura). Pasado eso, las escrituras fallan con WRITE_CAP antes de cualquier solicitud; get_status.writes.caps muestra el uso. Sin establecer = sin límite.
SN_MAX_DELETES_PER_SESSIONno—H-11: la mayoría de eliminaciones aplicadas por sesión (WRITE_CAP). Sin establecer = sin límite.
SN_MAX_BATCH_WRITESno—H-11: la mayoría de sub-solicitudes de escritura (no GET) en un servicenow_batch (WRITE_CAP). Sin establecer = sin límite.
SN_ENVno—H-11: marca el perfil predeterminado como prod, test o dev (SN_PROFILE_<NAME>_ENV para otros). Un perfil prod permanece en modo plan incluso cuando aplicar está configurado, a menos que SN_PROD_WRITES (SN_PROFILE_<NAME>_PROD_WRITES) sea I_UNDERSTAND; sus aplicaciones destructivas siempre se confirman (al menos SN_DESTRUCTIVE_CONFIRM=elicit, también en modo aplicar — CONFIRM_REQUIRED para un cliente sin elicitación); los resultados llevan _meta.environment; use_instance advierte. SN_PROFILE_<NAME>_WRITE_MODE establece el modo de escritura por perfil.
SN_PROD_WRITESno—H-11: I_UNDERSTAND permite que un perfil predeterminado prod se ejecute en modo aplicar.
SN_UPDATE_SETno—S-6: conjunto de actualización (sys_id o nombre exacto) donde aterrizan las escrituras de herramientas de tabla aplicadas (crear / actualizar / upsert / eliminar); un update_set por llamada lo anula y SN_PROFILE_<NAME>_UPDATE_SET lo establece por perfil. El plan nombra el conjunto; el conjunto de actualización actual del usuario se cambia para la escritura y se restaura después. Las tablas de filas de datos se escriben sin cambios.
SN_EMAIL_ALLOWED_DOMAINSno—Dominios de destinatarios que servicenow_send_email puede dirigir (para/cc/cco; un dominio cubre sus subdominios, * permite cualquiera). Cuando no está establecido, cada destinatario debe ser el correo electrónico de un usuario en la tabla sys_user de la propia instancia; cualquier otra cosa falla con RECIPIENT_NOT_ALLOWED.
SN_MAX_UPLOAD_BYTESno10485760Mayor carga útil de adjunto decodificada, verificada en la longitud base64 antes de decodificar (PAYLOAD_TOO_LARGE).
SN_UPLOAD_MIME_ALLOWno—Lista de permitidos opcional de tipos de contenido de carga (exactos, o type/*); otros fallan con MIME_NOT_ALLOWED.
SN_REDACT_FIELDSno—DF-5: enmascarar estos valores de campo antes de que los registros lleguen al modelo (separados por coma/espacio).
SN_REDACT_PIInofalseDF-5: también enmascarar patrones de correo electrónico/teléfono/identificación nacional dentro de valores de cadena. Desde H-5, ambas configuraciones de redacción se aplican profundamente a cada resultado de herramienta (éxito y error) y al diario de escritura.
SN_JOURNAL_MAX_BYTESno20971520H-5: tamaño (bytes, predeterminado 20 MiB) en el que write-journal.jsonl rota a write-journal.<ISO-time>.jsonl; la cadena de hash continúa entre archivos.
SN_CSV_FORMULA_GUARDnotrueH-5: prefijar celdas de texto CSV que comiencen con =, +, -, @, tabulador o CR con ' para que las hojas de cálculo nunca las evalúen (un -5 de texto se exporta como '-5). 0 opta por no participar.
SN_CSV_BOMnotrueH-5: anteponer una marca de orden de bytes UTF-8 a las exportaciones format:"csv" para que Excel decodifique texto no ASCII. 0 opta por no participar.
SN_TRANSPORTnostdioDF-6: stdio (predeterminado) o http (HTTP Streamable para clientes remotos/agentes).
SN_PORTno3000DF-6: puerto TCP para el transporte http.
SN_HTTP_HOSTno127.0.0.1DF-6: dirección de enlace para el transporte http (loopback por defecto).
SN_HTTP_TOKENno—DF-6: cuando se establece, las solicitudes http deben enviar Authorization: Bearer <token>.
SN_LOG_LEVELnoinfoVerbosidad de registro en stderr: error, warn, info, debug.
SN_LOG_FORMATnojsonE-5: formato de línea de registro en stderr — json (un objeto por línea) o text (HH:MM:SS level message key=value).
SN_LOG_FILEno—E-5: también agregar cada línea de registro (JSON Lines, redactado, modo 0600) a este archivo, con rotación basada en tamaño (<file>.1 … <file>.5). Stderr sigue funcionando.
SN_LOG_FILE_MAX_BYTESno10485760E-5: umbral de rotación para SN_LOG_FILE (bytes).
SN_METRICSnooffE-5: solo transporte HTTP — servir métricas de Prometheus en GET /metrics, detrás de SN_HTTP_TOKEN (deshabilitado cuando no se establece token).
SN_EXPERIMENTAL_TASKSno0M-9, experimental: 1 agrega un argumento opcional run_as_task:true a snapshot_instance, compare_instances, run_atf_test, run_atf_suite, code_health y query_table (solo format:"file"). Tal llamada devuelve un identificador de tarea MCP de inmediato (_meta["io.modelcontextprotocol/related-task"]); el cliente consulta tasks/get, lee tasks/result (conservado 1 h, redactado) o lo detiene con tasks/cancel. Apagado: esquemas sin cambios. Construido sobre la API de tareas experimental del SDK.
SN_LOG_NOTIFY_RATEno20M-8: notificaciones de registro por segundo y sesión de cliente sobre la capacidad de registro de MCP (ráfaga 50, o la tasa si es mayor). Las líneas que lo superan se cuentan y se informan en una advertencia de "N mensajes de registro suprimidos" por minuto; stderr nunca se limita. 0 = sin límite.
SN_ENV_FILEno—Ruta explícita al archivo de entorno para leer/escribir.
SN_TOOL_PACKAGESnocorePaquetes de herramientas o perfiles separados por coma/espacio para habilitar. Perfiles: core (predeterminado), all y los preajustes reader | developer | admin (ver Preajustes). Paquetes: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf, revert, artifacts, updatesets, ops, history, properties, directory, ui. Las herramientas de administración siempre están activadas. atf ejecuta pruebas en la instancia — habilítelo solo en una instancia que no sea de producción.
SN_PACKAGES_DENYno—Paquetes separados por coma/espacio para excluir incluso si están habilitados por SN_TOOL_PACKAGES. La única forma de bloquear APIs de plugin (catálogo, cambio, conocimiento…) — la política de tablas no las ve.
SN_PACKAGES_READONLYno—Paquetes separados por coma/espacio cuyas herramientas de escritura no están registradas; sus herramientas de lectura permanecen. Complemento por paquete al SN_READONLY global.
SN_SCHEMA_CACHE_TTL_SECno300TTL para la caché de lecturas de esquema casi estáticas (list_tables, describe_table, get_cmdb_meta). 0 deshabilita el almacenamiento en caché.
SN_SCHEMA_CACHE_MAXno256Entradas máximas en la caché de lecturas de esquema; cuando está llena, se expulsa la entrada menos recientemente usada. Los contadores (size, hits, misses, evictions) aparecen en get_status bajo schemaCache.
SN_CAPABILITY_TTL_MSno600000Cuánto tiempo se almacena en caché una sonda de capacidad exitosa — la matriz servicenow_check_capabilities y la disponibilidad de API de plugin (CI/CD, Code Search, Batch…). Pase refresh: true para volver a sondear antes.
SN_PLUGIN_NEGATIVE_TTL_MSno60000Cuánto tiempo se almacena en caché una sonda de capacidad fallida (HTTP 401/403/404/5xx) o una API de plugin faltante antes de intentarlo nuevamente. Los errores de transporte nunca se almacenan en caché.
SN_MAX_CONCURRENTno4Máximo de solicitudes HTTP paralelas a la instancia (semáforo simple en proceso).
SN_MAX_QUEUEno64Máximo de solicitudes en espera por host para una ranura libre más allá de SN_MAX_CONCURRENT. El desbordamiento falla inmediatamente con código BUSY en lugar de acumularse. Los diagnósticos (servicenow_test_connection, doctor) omiten la cola para que aún respondan mientras está detenida.
SN_QUEUE_TIMEOUT_MSnoSN_TIMEOUT_MSTiempo máximo que una solicitud espera una ranura antes de fallar con código BUSY. El tiempo de espera no se factura al tiempo de espera por intento, solo a SN_DEADLINE_MS.
SN_BREAKER_THRESHOLDno0 (off)Disyuntor de circuito opcional por host: después de este número de solicitudes fallidas consecutivas (error de transporte, plazo vencido, 5xx), las solicitudes posteriores fallan rápidamente con el código CIRCUIT_OPEN hasta que pase SN_BREAKER_RESET_MS. Los diagnósticos nunca se bloquean.
SN_BREAKER_RESET_MSno30000Cuánto tiempo un disyuntor de circuito abierto rechaza solicitudes antes de permitir una solicitud de prueba; el primer fallo lo reabre, el primer éxito lo cierra.
SN_INCLUDE_REF_LINKSnofalseLos campos de referencia se devuelven sin sus URLs de link de forma predeterminada (ahorro de tokens). Establezca true para incluirlos.
SN_RESULT_PRETTYnofalseLos resultados de las herramientas son JSON compacto de forma predeterminada (el formato bonito duplica aproximadamente los tokens). Establezca true para una salida indentada.
SN_DOCS_DIRnodocs/instanceDirectorio donde el paquete docs lee/escribe Markdown. Las rutas relativas se resuelven contra el directorio de trabajo. También contiene el diario de escritura por perfil: agregue docs/instance/ a .gitignore en cualquier repositorio desde el que ejecute el servidor.
SN_DOCS_MAX_FILE_BYTESno5242880Límite de tamaño por archivo para las herramientas de documentación: escrituras más grandes se rechazan, las lecturas devuelven los primeros bytes con truncated: true, la búsqueda omite el archivo.
SN_DOCS_STALE_DAYSno30servicenow_docs_list marca un documento generado stale cuando su sn_generated_at es más antiguo que este número de días.
SN_DOCS_SEARCH_MAXno200La mayoría de coincidencias que servicenow_docs_search devuelve; más allá de eso, el resultado lleva truncated: true.
SN_DIAGRAM_MAX_NODESno200Límite de nodos para los diagramas Mermaid generados (flujo de tablas, rastreo de eventos, dónde se usa; tablas en un diagrama ER detallado). Los nodos que lo superen se pliegan en un nodo +N more.
SN_SDK_MANAGED_SCOPESno—P-3: ámbitos de aplicación separados por comas/espacios (espacio de nombres como x_acme_app, o el sys_id de sys_scope) que declara como gestionados por un proyecto ServiceNow SDK (Fluent). La fuente de mayor autoridad para la detección gestionada por SDK; listado en get_status / check_capabilities bajo sdkManaged.
SN_SDK_MANAGED_WRITESnowarnP-22: escrituras en un ámbito gestionado por SDK (un registro cuyo sys_scope P-3 detecta como gestionado por SDK) desde create_record, update_record, upsert_record, delete_record, set_property y revert_write: warn previsualiza y aplica con un bloque sdkManaged nombrando la alternativa Fluent; deny rechaza la aplicación con SDK_MANAGED_SCOPE (el plan dice would_refuse); allow omite la verificación. Se ejecuta después de la política de tablas y no cuesta nada a menos que SN_SDK_MANAGED_SCOPES o SN_SDK_PROJECT_DIRS esté establecido.
SN_SDK_PROJECT_DIRSno—P-3: directorios (separados por comas o el delimitador de ruta de la plataforma) escaneados en solo lectura para proyectos SDK: cada now.config.json declara su scope / scopeId como gestionado por SDK. Acotado (profundidad 4, 2000 directorios, 100 archivos de configuración, 256 KiB por archivo), nunca sigue enlaces simbólicos, omite carpetas ocultas, node_modules y de compilación, y no lee nada más que now.config.json.
SN_CODESEARCHnofalseOpte por la API de búsqueda de código (sn_codesearch) para servicenow_search_code (FT-7). Cuando true y el plugin está activo, reemplaza la iteración LIKE; vuelve a LIKE ante cualquier fallo.
SN_PROFILE_<NAME>_*no—Perfiles de conexión nombrados: SN_PROFILE_DEV_INSTANCE / _USER / _PASSWORD definen el perfil dev. Las claves simples SN_INSTANCE/SN_USER/SN_PASSWORD son el perfil default.
SN_ACTIVE_PROFILEnodefaultQué perfil usan las herramientas. Cambie en tiempo de ejecución con servicenow_use_instance (persistido en el archivo de entorno).

Política de acceso de dos ejes

El acceso se controla en dos ejes independientes: tablas y paquetes de herramientas.

EjeHabilitar / denegar / solo lecturaEjemplo
TablasSN_TABLES_ALLOW / SN_TABLES_DENY / SN_READONLYSN_TABLES_DENY=change_request bloquea la API de Tablas y (desde H-4) las herramientas de Cambio, que verifican su tabla subyacente.
PaquetesSN_TOOL_PACKAGES / SN_PACKAGES_DENY / SN_PACKAGES_READONLYSN_PACKAGES_DENY=change elimina las herramientas de Gestión de Cambios y bloquea la API del plugin sn_chg_rest, también dentro de un lote.

Desde H-4, las herramientas respaldadas por plugins (Cambio, Catálogo, Conocimiento, Correo electrónico, ATF) y los adjuntos (a través de la tabla del registro padre) también obedecen el eje de tablas; el eje de paquetes aún elimina superficies completas. Consulte Notas de seguridad para el modelo completo (incluyendo cómo la API de Lotes obedece ambos ejes).

Sintaxis de listas: las listas de tablas (SN_TABLES_ALLOW / SN_TABLES_DENY) están separadas por comas; las listas de paquetes (SN_TOOL_PACKAGES, SN_PACKAGES_DENY, SN_PACKAGES_READONLY) aceptan comas o espacios en blanco. Los espacios circundantes se recortan en ambas, y la coincidencia de tablas no distingue entre mayúsculas y minúsculas — por lo que SN_TABLES_DENY=Change_Request, sys_user funciona. Desde H-11, una entrada de tabla puede ser un patrón (* cualquier secuencia, ? un carácter): SN_TABLES_DENY=sys_* bloquea sys_user y deja incident intacto. El orden es: una denegación exacta, una permitida exacta, una denegación por patrón, las tablas protegidas (escrituras, con SN_PROTECTED_TABLES_WRITE=deny), luego los patrones de la lista de permitidas. Pregunte servicenow_explain_policy({table, action}) qué regla decide, o lea servicenow://policy.

Ejecutar / depurar

  • VS Code: abra la Paleta de Comandos e inicie el servidor definido en .vscode/mcp.json, luego úselo desde Chat.
  • Inspector MCP: npm run inspector
  • Directamente: npm start

Observabilidad

  • Estado. servicenow_get_status lleva un bloque observability: por herramienta {count, errors, p50, p95, totalMs} (percentiles en ms sobre las últimas 256 llamadas de cada herramienta — la memoria permanece acotada), aciertos/fallos de caché de esquema, contadores de reintentos por host, límites y ocupación de cola, estado del interruptor de circuito y las últimas X-RateLimit-* cabeceras que cada host envió. Nunca llama a la instancia.

  • Registros. Los registros van solo a stderr (stdout es el protocolo MCP). SN_LOG_FORMAT=text cambia de líneas JSON a un formato legible por humanos; SN_LOG_FILE también añade líneas JSON a un archivo rotado por tamaño. Los campos con nombres de credenciales (password, token, authorization, …) se enmascaran en cada destino, y las reglas SN_REDACT_FIELDS / SN_REDACT_PII se aplican además.

  • Enlaces de rastreo. El bucle de solicitudes publica en node:diagnostics_channel, por lo que un suscriptor de OpenTelemetry (o cualquier otro) puede conectarse sin dependencia de este servidor:

    CanalCuándoCampos de mensaje
    servicenow-mcp:http.request.startcomienza una solicitud lógicaid, system, method, host, telemetryKey, url, y profile / requestId / sessionId / tool en una llamada
    servicenow-mcp:http.request.endse resolvió con una respuesta OKlos campos de inicio más status, attempts, ms
    servicenow-mcp:http.request.errorfallólos campos de inicio más attempts, ms, status, code, errorName, errorMessage
    servicenow-mcp:http.request.retryse reproduce un intento (backoff, re-autenticación 401)id, system, method, host, url, attempt, reason, waitMs

    url nunca incluye la cadena de consulta; las cabeceras, los cuerpos y las credenciales nunca se publican, y errorMessage pasa por las reglas de redacción.

  • Prometheus. Con el transporte HTTP, SN_METRICS=1 y SN_HTTP_TOKEN configurados, GET /metrics (mismo token de portador) sirve las mismas cifras en el formato de texto de Prometheus (familias servicenow_mcp_*, etiquetadas solo por tool / host). Sin un token, el endpoint permanece desactivado y se registra una advertencia.

Interfaz de línea de comandos

El binario publicado servicenow-mcp-ai (ejecútelo directamente, o mediante npx servicenow-mcp-ai) inicia el servidor MCP cuando no se le da ningún comando, y de lo contrario ejecuta uno de los comandos siguientes y sale. La configuración de conexión proviene de variables de entorno / el archivo de entorno (consulte Variables de entorno). servicenow-mcp-ai --help lista todo; --version imprime la versión. Un comando u opción desconocido imprime el uso en stderr y sale con 2 — nunca inicia el servidor.

ComandoOpcionesQué haceCódigos de salida
servicenow-mcp-ai(ninguna)Inicia el servidor MCP. El transporte (stdio predeterminado, o http) se elige mediante SN_TRANSPORT; se ejecuta hasta SIGINT/SIGTERM. stdout es el canal de protocolo.0 apagado limpio · 1 error fatal de inicio
servicenow-mcp-ai init--profile <name>, --skip-doctorConfiguración interactiva: solicita la instancia, el método de autenticación y sus credenciales (secretos mediante un aviso oculto), escribe el archivo de entorno, luego ejecuta doctor.el código de salida doctor · 0 con --skip-doctor · 2 respuestas rechazadas / inválidas
servicenow-mcp-ai doctor--json, --ascii, --profile <name>Verificación de salud: credenciales, una sonda de conectividad en vivo y la verificación previa de capacidades. La primera línea nombra el archivo de entorno que se usó.0 saludable · 1 degradado o inalcanzable · 2 no configurado
servicenow-mcp-ai login--profile <name>Inicio de sesión único OAuth 2.1 Código de Autorización + PKCE: abre el navegador, captura la redirección de bucle local, almacena un token de actualización.0 éxito · 1 inicio de sesión fallido
servicenow-mcp-ai drift <profileA> <profileB>(ninguna)Puerta de deriva CI DF-3: compara las dos instancias y escribe un informe de diferencias en Markdown.0 sin deriva · 1 deriva encontrada · 2 uso / error
servicenow-mcp-ai support-bundle--out <file>, --profile <name>Escribe un archivo JSON para un informe de error e imprime su ruta en stdout.0 escrito · 1 fallo de escritura

init escribe a través del mismo escritor de archivos de entorno atómico, solo propietario (0600) que servicenow_set_credentials, al archivo que doctor nombra (por defecto ~/.config/servicenow-mcp-ai/.env). Pregunta, en orden: la instancia (dev12345 o un host completo; un dominio personalizado necesita SN_ALLOWED_HOSTS), el método de autenticación (basic / oauth / apikey / token), luego la configuración de ese método — para oauth la concesión (client_credentials, password, o authorization_code, que termina con una pista para ejecutar login). Los secretos nunca se muestran ni se registran; el resumen lista solo los nombres de las claves. Con --profile qa las claves se escriben como SN_PROFILE_QA_*. Un perfil existente se sobrescribe solo después de un y. Las respuestas se pueden canalizar, una por línea, que es como CI y las pruebas lo manejan:

printf 'dev12345\nbasic\nalice\n%s\n' "$SN_PASSWORD" | npx servicenow-mcp-ai init

Sin una terminal y sin respuestas canalizadas, init se niega (salida 2) y no escribe nada.

doctor imprime ASCII simple ([ok] / [x] en lugar de marcas de verificación) con --ascii, cuando stdout no es una terminal, y en Windows fuera de Windows Terminal. --json imprime un documento JSON en su lugar: envFile, status, summary, checks[] (name, ok, detail), config, connection, capabilities y serverStatus (el payload servicenow_get_status) — por ejemplo servicenow-mcp-ai doctor --json | jq .checks. Los códigos de salida son los mismos.

support-bundle recopila el payload doctor --json, cada configuración SN_* con secretos enmascarados como ***, npm ls --omit=dev (mejor esfuerzo), el resumen del manifiesto de herramientas (versión, recuentos de herramientas y paquetes, herramientas activas) y las últimas 200 líneas de SN_LOG_FILE cuando se configura una. Cada valor enmascarado también se limpia de todo el archivo. La ruta predeterminada es ./servicenow-mcp-ai-support-<timestamp>.json (modo 0600). Los nombres de instancia y de usuario no están enmascarados — revise el archivo antes de adjuntarlo a un problema.

login opera en el perfil activo (SN_ACTIVE_PROFILE, predeterminado default) y lee, para ese perfil:

  • SN_INSTANCE — obligatorio; la instancia de destino.
  • SN_OAUTH_CLIENT_ID — obligatorio; id de cliente de un endpoint de API OAuth de Código de Autorización.
  • SN_OAUTH_CLIENT_SECRET — opcional; para un cliente confidencial.
  • SN_OAUTH_REDIRECT_URI — opcional; URL de bucle local, predeterminado http://localhost:53682/callback. Debe coincidir con la redirección registrada en el endpoint.
  • SN_OAUTH_SCOPE — opcional; ámbito OAuth solicitado.

En caso de éxito, escribe SN_AUTH=oauth, SN_OAUTH_GRANT=refresh_token y SN_OAUTH_REFRESH_TOKEN de vuelta al archivo de entorno (con prefijo de perfil cuando el perfil no es default). La URL de autorización se imprime en stderr en caso de que el navegador no se abra automáticamente.

drift toma dos nombres de perfil posicionales; cada uno debe resolverse a un perfil configurado (SN_PROFILE_<NAME>_*, o las claves simples SN_INSTANCE / SN_USER / SN_PASSWORD para default). El informe en Markdown se escribe en stdout (captúrelo como un artefacto de CI); un resumen de deriva de una línea va a stderr.

Puerta de deriva CI (DF-3)

Compare dos perfiles configurados y haga fallar una canalización en caso de deriva de configuración:

servicenow-mcp-ai drift dev prod   # report on stdout; exit 1 on drift, 0 if clean, 2 on error

El informe muestra cada script cambiado como un bloque diff. La CLI compara tablas, columnas, scripts, plugins y aplicaciones; las secciones de registros (sections en servicenow_compare_instances) son opcionales, por lo que los códigos de salida no cambian.

servicenow_snapshot_instance escribe el mismo material en la carpeta de documentación, un archivo por sección, como máximo cuatro secciones a la vez. Una ejecución interrumpida se marca partial en index.json; vuelva a ejecutarla con resume: true para omitir cada sección cuyos archivos no hayan cambiado.

Desarrollar

npm run check     # full gate: build, lint, format check, coverage-gated tests, tarball guard, prod audit
npm test          # unit tests only (node:test; needs a prior npm run build)
npm run lint      # ESLint (flat config + typescript-eslint)
npm run format    # format with Prettier

Consulta CONTRIBUTING.md para conocer las convenciones (un commit por tarea, las pruebas se incluyen con el cambio, documentación generada).

Herramientas

Esta tabla se genera a partir de los registros de herramientas: edita las definiciones de herramientas en src/tools/ y luego ejecuta npm run docs:readme.

PaqueteHerramientaSolo lecturaDescripción
tableservicenow_query_tablesíLeer registros de cualquier tabla (API de Tablas): consulta codificada, campos, paginación, fetchAll
tableservicenow_get_recordsíLeer un único registro de una tabla por su sys_id
tableservicenow_create_recordnoCrear un nuevo registro en una tabla con los valores de campo dados
tableservicenow_update_recordnoActualizar campos en un registro existente identificado por su sys_id
tableservicenow_upsert_recordnoCrear o actualizar un registro que coincida con una clave exacta de pares campo/valor: sin coincidencia crea, una actualiza, se…
tableservicenow_delete_recordnoEliminar un registro de una tabla por su sys_id
schemaservicenow_list_tablessíListar tablas de sys_db_object, opcionalmente filtradas por un fragmento de nombre o etiqueta
schemaservicenow_describe_tablesíListar las columnas de una tabla desde sys_dictionary (nombre, etiqueta, tipo, obligatorio, referencia, valor por defecto, solo lectura/uni…
aggregateservicenow_aggregatesíCalcular agregados del lado del servidor (count, avg, min, max, sum) sobre una tabla mediante la API de Estadísticas, con agrupación opcional…
attachmentservicenow_list_attachmentssíListar metadatos de adjuntos, opcionalmente limitados a un registro específico (tabla + sys_id)
attachmentservicenow_get_attachmentsíLeer los metadatos de un único adjunto por su sys_id
attachmentservicenow_download_attachmentsíDescargar los bytes de un adjunto, devueltos como base64
attachmentservicenow_upload_attachmentnoAdjuntar un archivo (proporcionado como base64) a un registro identificado por tabla + sys_id
attachmentservicenow_delete_attachmentnoEliminar un adjunto por su sys_id
importsetservicenow_insert_import_set_rownoInsertar una fila en una tabla de preparación y ejecutar su mapa de transformación
importsetservicenow_get_import_set_rowsíLeer el resultado de la transformación para una fila de preparación previamente insertada por su sys_id
batchservicenow_batchnoEjecutar varias sub-solicitudes REST de ServiceNow en un único viaje de ida y vuelta HTTP mediante la API de Lotes
catalogservicenow_list_catalogssíListar los Catálogos de Servicios disponibles en la instancia (API de Catálogo de Servicios)
catalogservicenow_list_catalog_categoriessíListar las categorías dentro de un catálogo de servicios
catalogservicenow_list_catalog_itemssíBuscar/listar artículos de catálogo pedibles, opcionalmente por texto o categoría
catalogservicenow_get_catalog_itemsíObtener un artículo de catálogo, incluyendo sus variables de pedido, por sys_id
catalogservicenow_order_catalog_itemnoPedir un artículo de catálogo directamente ('pedir ahora')
changeservicenow_list_changessíListar solicitudes de cambio mediante la API de Gestión de Cambios
changeservicenow_get_changesíObtener una única solicitud de cambio por sys_id
changeservicenow_create_changenoCrear un cambio normal, estándar o de emergencia
changeservicenow_update_changenoActualizar campos en una solicitud de cambio por sys_id
changeservicenow_change_conflictsnoLeer conflictos de agenda para un cambio, o recalcularlos (calculate=true)
knowledgeservicenow_search_knowledgesíBúsqueda de texto completo de artículos de conocimiento (API de Conocimiento), con consulta codificada y paginación opcionales
knowledgeservicenow_get_knowledge_articlesíObtener un artículo de conocimiento (contenido y metadatos) por sys_id
knowledgeservicenow_knowledge_highlightssíListar artículos de conocimiento destacados o más vistos para el usuario actual
cmdbservicenow_list_cissíListar elementos de configuración de una clase CMDB mediante la API de Instancia CMDB consciente de clases
cmdbservicenow_get_cisíObtener un CI con sus atributos y relaciones entrantes/salientes por clase y sys_id
cmdbservicenow_create_cinoCrear un CI mediante la API de Instancia CMDB (enrutado a través de Identificación y Reconciliación)
cmdbservicenow_update_cinoActualizar los atributos de un CI mediante la API de Instancia CMDB (IRE)
cmdbservicenow_get_cmdb_metasíObtener el esquema/metadatos de una clase CMDB (atributos, reglas de relación) desde la API Meta CMDB
cmdbservicenow_list_ci_relationssíListar las relaciones de un CI desde cmdb_rel_ci, cada una orientada desde ese CI (saliente = es el padre,…
cmdbservicenow_identify_reconcilenoEnviar CIs y relaciones a través del Motor de Identificación y Reconciliación (/api/now/identifyreconcile),…
scriptsservicenow_list_scriptssíListar artefactos de script de un tipo como metadatos compactos (sin código fuente); 'type' lista los estándar y opt-i…
scriptsservicenow_get_scriptsíLeer un artefacto de script completo, incluyendo su código fuente y contexto de ejecución
scriptsservicenow_search_codesíBuscar en el código fuente de scripts una subcadena literal en uno o todos los tipos de script
scriptsservicenow_table_logicsíEnsamblar la automatización que se ejecuta en una tabla: reglas de negocio (ordenadas por cuándo+orden), scripts de cliente, po…
scriptsservicenow_where_usedsíEncontrar referencias a una tabla, campo (tabla.campo) o script: líneas coincidentes en fuentes de script, reglas/ACLs att…
flowsservicenow_trace_table_eventsíRastrear qué se ejecutaría para una operación de tabla, en orden, sin ejecutar: mostrar/antes/después/async negocio…
flowsservicenow_list_flowssíListar flujos de Flow Designer (sys_hub_flow) o flujos de trabajo heredados (kind: 'workflow') como metadatos compactos
flowsservicenow_get_flowsíObtener una vista estructurada de un flujo o flujo de trabajo: su disparador (tabla/condición/cuándo) y pasos ordenados
flowsservicenow_get_flow_runssíLeer evidencia de ejecución de flujo desde sys_flow_context — por sys_id de flujo o por el registro (documento) contra el que se ejecutó…
flowsservicenow_explain_flowsíExplicar un flujo/subflujo (disparador, árbol de pasos con entradas y píldoras decodificadas, llamadas a subflujo/acción expandidas, dr…
codecheckservicenow_lint_scriptsíEjecutar reglas deterministas de calidad de código sobre un artefacto de script (sys_ids/URLs codificados, sin límite o en-loo…
codecheckservicenow_lint_tablesíLint de cada regla de negocio activa, script de cliente y política de UI de una tabla (vía table_logic), devolviendo por-sc…
codecheckservicenow_code_healthnoInforme de salud de código: recuentos de scripts por tipo, escaneo de seguridad de ACL (abiertas, rol público, con script, ACLs elevadas, p…
docsservicenow_docs_listsíListar los documentos Markdown en la carpeta local de documentación de instancia (SN_DOCS_DIR), con metadatos por archivo…
docsservicenow_docs_readsíLeer un documento Markdown o un compañero .json generado desde la carpeta local de documentación de instancia; el r…
docsservicenow_docs_searchsíBuscar en la documentación local de instancia una subcadena; devuelve un fragmento y el encabezado más cercano por coincidencia…
docsservicenow_docs_writenoCrear o sobrescribir un documento Markdown en la carpeta local de docs y actualizar index.md
docsservicenow_generate_er_diagramsíConstruir un erDiagram de Mermaid desde sys_dictionary: una entidad por tabla, una relación por campo de referencia
docsservicenow_generate_table_flowsíDiagrama de flujo Mermaid del ciclo de vida de un registro en una tabla: reglas de negocio activas por fase (mostrar/antes/después/…
docsservicenow_document_tablenoEscribir /tablas/.md + .json solo desde metadatos: herencia, columnas, columnas de referencia, ER…
docsservicenow_document_appnoEscribir /apps/.md + .json para una aplicación con ámbito: su registro, tablas con un diagrama ER, roles, c…
docsservicenow_document_instancenoEscribir /README.md (versión, recuentos, apps, plugins, automatización, conjuntos de actualización) y artifact-types.md, …
instanceservicenow_snapshot_instancenoDescargar metadatos estructurales a SN_DOCS_DIR// como Markdown + JSON: tablas, esquema/.md, plugi…
instanceservicenow_compare_instancesnoComparar dos perfiles: tablas solo en uno, diferencias de tipo de columna/obligatorio/referencia, scripts faltantes/renombrados…
emailservicenow_send_emailnoEnviar un correo electrónico a través de la API de Correo (el plugin debe estar activo), opcionalmente vinculado a un registro (tabla + sys_id)
emailservicenow_get_emailsíLeer un registro de correo enviado/recibido por su sys_id (API de Correo)
atfservicenow_list_atf_testssíListar pruebas del Marco de Pruebas Automatizadas (sys_atf_test) como metadatos: nombre, indicador activo, descripción
atfservicenow_list_atf_suitessíListar suites de pruebas del Marco de Pruebas Automatizadas (sys_atf_test_suite) como metadatos
atfservicenow_run_atf_testnoEjecutar una prueba ATF a través de la API CI/CD
atfservicenow_run_atf_suitenoEjecutar una suite de pruebas ATF a través de la API CI/CD
atfservicenow_get_atf_resultsíConsultar una ejecución ATF por su id de ejecución: estado, porcentaje completado y mensaje (API de progreso CI/CD)
revertservicenow_list_writessíListar el diario de escritura local (más reciente primero): cada crear/actualizar/eliminar/ejecutar que este servidor hizo, con su …
revertservicenow_revert_writenoDeshacer una escritura aplicada del diario local: una actualización restaura sus valores anteriores, un crear se elimina, un…
artifactsservicenow_list_artifactssíListar registros de cualquier tipo de artefacto de registro (reglas de negocio, políticas de UI, widgets, flujos, artículos de catálogo, …) …
artifactsservicenow_get_artifactsíLeer un artefacto de cualquier tipo de registro completo: el registro, sus registros hijos de registro (p. ej.
artifactsservicenow_explain_artifactsíExplicar un artefacto de cualquier tipo de registro: resumen, campos de disparo, campos no vacíos, hijos, referenciados …
artifactsservicenow_artifact_dependenciessíGrafo de dependencias de un artefacto: saliente (campos de referencia, JSON decodificado, llamadas de script y tablas GlideRecord…
updatesetsservicenow_list_update_setssíListar conjuntos de actualización (sys_update_set), más reciente primero, con estado, ámbito de aplicación y si cada uno es del usu…
updatesetsservicenow_get_update_setsíResumir un conjunto de actualización: sus actualizaciones de cliente (sys_update_xml) por artefacto — tipo, nombre de destino, acción, t…
updatesetsservicenow_compare_update_setsíComparar los artefactos de un conjunto de actualización con otro perfil (en vivo) o una instantánea almacenada: por artefacto igual / dif…
opsservicenow_ops_readsíVistas operativas limitadas para el triaje de 'por qué es lento': resumen (todos los recuentos), syslog (entradas recientes por niv…
opsservicenow_data_healthsíRecuentos de calidad de datos para una tabla (gemelo de servicenow_code_health): grupos duplicados sobre key_fields, y o…
historyservicenow_get_record_historysíLeer el historial de cambios de un registro: cambios de campo sys_audit y entradas sys_journal_field (comentarios, work_notes…
propertiesservicenow_get_propertiessíLeer propiedades del sistema (sys_properties) por nombre exacto o prefijo de nombre: valor, tipo, descripción, lectura/escritura …
propertiesservicenow_set_propertynoEstablecer el valor de una propiedad del sistema existente (sys_properties) por nombre
directoryservicenow_lookup_directorysíEncontrar usuarios (user_name, prefijo de correo o nombre), grupos o roles por término de búsqueda o sys_id
uiservicenow_explain_portalsíExplicar un Portal de Servicios (url_suffix o sys_id) o una página como un árbol: tema, menú, páginas, luego contenido de diseño…
adminservicenow_set_credentialsnoGuardar credenciales de conexión en el archivo de entorno para solicitudes posteriores (cualquier subconjunto; auth / oauth_client_id / oauth_…
adminservicenow_list_instancessíLista los perfiles de conexión de ServiceNow configurados (instancias): nombre, host, usuario, método de autenticación (y OAuth gr…
adminservicenow_use_instancenoCambia el perfil de conexión de ServiceNow activo (persistido en el archivo de entorno)
adminservicenow_explain_policysíIndica si una tabla puede leerse o escribirse bajo la política activa y qué regla lo decide (las propias reglas de los guards…)
adminservicenow_get_statussíMuestra instancia, autenticación, credenciales faltantes, modo de escritura por perfil, política, límites, TLS, cola, contador de escrituras…
adminservicenow_test_connectionsíVerifica que las credenciales configuradas realmente funcionan: lee un registro de sys_user e informa ok/estado/latencia
adminservicenow_check_capabilitiessíPreflight de qué tablas sys_* puede leer el usuario y qué capacidades (esquema, inteligencia de scripts, auditoría de ACL…)
adminservicenow_list_packagessíLista los paquetes de herramientas con su estado para esta sesión: habilitado, configurado (SN_TOOL_PACKAGES), denegado, r…
adminservicenow_enable_packagenoHabilita un paquete de herramientas para esta sesión: sus herramientas, recursos y prompts aparecen (se envía list_changed)
adminservicenow_disable_packagenoDeshabilita un paquete de herramientas para esta sesión: sus herramientas, recursos y prompts se retiran (se envía list_changed)

Todas las herramientas llevan anotaciones MCP (readOnlyHint, destructiveHint, idempotentHint) para que los clientes puedan aplicar la experiencia de confirmación adecuada.

Paquetes de herramientas

Las herramientas se agrupan en paquetes para que puedas exponer solo lo que un cliente determinado necesita (menos herramientas mantienen el modelo enfocado). Establece SN_TOOL_PACKAGES a una lista separada por comas o espacios de perfiles o nombres de paquetes:

  • core (predeterminado) — table, schema, aggregate, attachment.
  • all — todos los paquetes a continuación.
  • Paquetes individuales: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf, revert, artifacts, updatesets, ops, history, properties, directory, ui.

Las herramientas de administración (servicenow_set_credentials, servicenow_get_status, servicenow_enable_package y el resto del paquete de administración) siempre están registradas, independientemente de los paquetes activos. Los nombres desconocidos se ignoran. servicenow_get_status informa el enabledPackages resuelto.

# Only table + batch tools (plus the always-on admin tools)
SN_TOOL_PACKAGES=table,batch

Ajustes preestablecidos

Si prefieres no seleccionar la lista tú mismo, tres ajustes preestablecidos con nombre cubren los roles comunes. Las herramientas de administración siempre están activas, por lo que no se enumeran. Cada ajuste preestablecido también tiene un alias de una palabra — SN_TOOL_PACKAGES=reader|developer|admin — que se expande al mismo conjunto de paquetes.

Ajuste preestablecidoSN_TOOL_PACKAGES=…Para quién
readertable,schema,aggregatePrimer contacto, analistas, un juego de PDI — solo lectura y consulta.
developertable,schema,aggregate,scripts,flows,codecheck,docsEl segmento principal: inteligencia de scripts, trazado de flujos, linting, documentación y diagramas.
adminallTodo, incluido el plugin y los paquetes con muchas escrituras.

El ajuste preestablecido developer se basa en el conjunto reader; el paquete docs incluye los generadores de diagramas Mermaid. Usa el alias por brevedad o escribe los paquetes para añadir o quitar uno.

Cambio de paquetes en tiempo de ejecución

Un cliente puede ampliar o reducir su superficie sin reiniciar: servicenow_list_packages muestra cada paquete con su estado para esta sesión (habilitado, configurado, denegado, solo lectura, número de herramientas), y servicenow_enable_package / servicenow_disable_package alternan uno. El servidor anuncia el cambio con notifications/tools/list_changed (y los equivalentes de prompts / recursos cuando esos también cambian), uno por lista por alternancia. Una alternancia nunca excede los ejes de política: un paquete en SN_PACKAGES_DENY es rechazado (PACKAGE_DENIED), un paquete en SN_PACKAGES_READONLY trae solo sus herramientas de lectura, y las herramientas de administración no se pueden deshabilitar. Las alternancias duran la sesión; una sesión HTTP que se cierra vuelve a SN_TOOL_PACKAGES. Nada cambia a menos que un cliente llame a estas herramientas.

El servidor también declara resources.subscribe: después de servicenow_use_instance o servicenow_set_credentials envía notifications/resources/list_changed y, a los suscriptores, notifications/resources/updated para servicenow://status.

Upsert por clave

servicenow_upsert_record({table, key, fields}) crea o actualiza un registro coincidente por key, una coincidencia exacta en uno o más pares de campo/valor (por ejemplo {"u_external_id": "A-17"}; una cadena vacía coincide con un campo vacío). Sin coincidencia crea un registro con la clave y los campos, exactamente una coincidencia lo actualiza, y más de una coincidencia se rechaza con AMBIGUOUS_KEY — también se rechaza una coincidencia que el usuario no puede leer, ya que crear otra la duplicaría.

La acción se decide en el plan: sin apply:true la herramienta devuelve create o update (con los valores de sys_id y before) más apply_with: {expected_action, expected_sys_id}. Pásalos de vuelta con apply:true; si la clave ahora se resuelve de manera diferente (el registro apareció, desapareció o es otro) la llamada falla con STALE_RECORD y no escribe nada. La escritura aplicada se registra como una creación o una actualización, por lo que servicenow_revert_write la deshace como un create_record / update_record directo.

Deshacer una escritura (reversión basada en diario)

Cada escritura aplicada se registra en el diario de escrituras local encadenado por hash (<SN_DOCS_DIR>/<profile>/write-journal.jsonl). El paquete opcional revert lo convierte en un deshacer:

  • servicenow_list_writes — el diario más reciente primero, filtrado por profile, table, since (fecha/hora ISO), result y action. Cada fila lleva la entrada id y si la línea sola permite una reversión (revertible + reason).
  • servicenow_revert_write — entry_id → la escritura inversa a través de la API de Tabla: una actualización escribe de vuelta sus valores before registrados, una creación se elimina, una eliminación se recrea desde su registro before (campos de sistema omitidos, el sys_id original solicitado; el resultado informa sys_id_preserved). Sigue plan/aplicar como toda herramienta de escritura: sin apply:true devuelve la inversa, el estado actual del registro y la verificación de desviación, y no cambia nada.

Reglas de seguridad:

  • Verificación de desviación. El sys_mod_count del registro se compara con el valor que la escritura registrada dejó (after_mod_count, o before.sys_mod_count + 1); cuando no hay recuento disponible, los valores de campo escritos se comparan en su lugar. Si el registro cambió desde entonces — o no se pudo comparar nada — la reversión se rechaza con STALE_RECORD; pasa force:true para sobrescribir de todos modos (la línea del diario de la reversión entonces registra force: true).
  • NOT_REVERTIBLE, con el motivo, cuando la entrada es desconocida, la cadena del diario está rota, la escritura no fue applied, la línea no tiene estado before, un valor before fue redactado (SN_REDACT_FIELDS / SN_REDACT_PII), la entrada ya fue revertida, o su origen no tiene una inversa segura: carga/eliminación de adjuntos, send_email, filas de conjunto de importación, pedidos de catálogo, sub-solicitudes de API Batch, ejecuciones de ATF, creaciones de CMDB (IRE puede haber coincidido con un CI existente) y entradas locales/de configuración. Un valor redactado nunca se restaura como [redacted]: toda la entrada se rechaza, sin reversión parcial — restaura esos campos a mano.
  • La reversión en sí misma se registra (reverts: <entry_id>, tool: servicenow_revert_write), por lo que revertir la reversión es un rehacer. La política se aplica como para una escritura directa: SN_READONLY, las listas de permitir/denegar de tablas y los ejes de paquete tanto del paquete original como de table. Pon revert en SN_PACKAGES_READONLY para mantener list_writes sin el deshacer.

Conjuntos de actualización

El paquete opcional updatesets lee conjuntos de actualización (las tres herramientas son solo lectura y pasan por la política de tablas y la redacción como cualquier lector):

  • servicenow_list_update_sets — state opcional, fragmento name, application (espacio de nombres de alcance, global o sys_id), query, limit / offset → conjuntos más recientes primero, con el conjunto actual del usuario marcado.
  • servicenow_get_update_set — update_set (sys_id o nombre exacto) → sus actualizaciones de cliente (sys_update_xml) por artefacto: tipo, nombre de destino, acción, tabla, más recuentos by_type / by_action. Los cargas útiles se omiten a menos que include_payload: true; luego se analizan en valores de campo, cada uno limitado a payload_max_chars (predeterminado 500), con campos de apariencia secreta enmascarados.
  • servicenow_compare_update_set — update_set más with_profile (lectura en vivo) o with_snapshot (una instantánea servicenow_snapshot_instance) → por artefacto same / different (solo nombres de campo diferentes) / missing / not_comparable / not_covered / unknown. Solo se comparan los campos en la carga útil de la actualización; las columnas de auditoría se ignoran.

Escrituras: servicenow_create_record, servicenow_update_record, servicenow_upsert_record y servicenow_delete_record toman un update_set opcional (sys_id o nombre exacto; predeterminado SN_UPDATE_SET). La vista previa del plan nombra el conjunto de destino; aplicar cambia la preferencia sys_update_set del usuario (y la preferencia updateSetForScope<scope> del alcance para un conjunto con alcance), ejecuta la escritura y restaura el valor anterior — el resultado informa update_set: { bound, previous, restored } y la entrada del diario registra update_set. Un conjunto que no es in progress se rechaza (UPDATE_SET_NOT_IN_PROGRESS); una tabla de filas de datos (cualquier cosa que no extienda sys_metadata y sin el atributo update_synch) se escribe sin cambiar, y el plan lo dice. Sin el argumento o la configuración nada cambia. Otras herramientas de escritura (batch, catálogo, cambio…) no están vinculadas.

Operaciones y salud de datos

El paquete opcional ops contiene dos herramientas de solo lectura para el triaje de "la instancia está lenta" y la calidad de datos. Cada sección lee su propia tabla; una tabla ilegible (ACL, política de tablas, tabla faltante) informa available: false con el motivo en lugar de fallar la llamada, por lo que una sección en blanco nunca se lee como saludable.

  • servicenow_ops_read — kind:

    • overview — los recuentos de cada sección a continuación en una llamada.
    • syslog — entradas de los últimos minutes (predeterminado 60, máximo 1440) en o por encima de level (predeterminado warning), fragmento source opcional: recuentos por nivel, fuentes principales y las filas más recientes (mensajes limitados a 500 caracteres).
    • jobs — la cola del programador (sys_trigger) por estado, el número de trabajos listos más de overdue_minutes después de su próxima acción, y los trabajos overdue (predeterminado), running o queued con su nodo de reclamación.
    • email_queue — sys_email saliente: el backlog listo para enviar y su entrada más antigua, recuentos por tipo en la ventana y los fallos de envío recientes.
    • semaphores — filas sys_semaphore, más recientes primero.

    Las filas están limitadas por limit (predeterminado 25, máximo 200).

  • servicenow_data_health — el gemelo de datos de servicenow_code_health para un table, opcionalmente limitado por query (sin ^NQ / ORDERBY): grupos duplicados sobre key_fields (agrupación de API Aggregate, recuento > 1, limitado por limit), y por campo de referencia (reference_fields, predeterminado los primeros 10 no de sistema) las referencias huérfanas (fila de destino faltante) y — cuando el destino tiene una columna active y stale no es false — las referencias obsoletas (destino inactivo), cada una con la consulta codificada que lista las filas. Los nombres de campo se verifican contra el diccionario primero. Una fila de destino que el usuario no puede leer también cuenta como huérfana.

El prompt servicenow_why_is_it_slow guía a través de estas lecturas y, con un table, la lógica que se ejecuta en sus escrituras.

Historial de registros, propiedades y directorio

Tres paquetes opcionales cubren preguntas de operaciones del día a día. Cada lectura pasa por la política de tablas y la redacción como cualquier otro lector.

  • servicenow_get_record_history (history) — table + sys_id → cambios de campo desde sys_audit y entradas de diario (comentarios, notas de trabajo) desde sys_journal_field, fusionados del más reciente al más antiguo. source (all / audit / journal), fields, since (YYYY-MM-DD[ HH:MM:SS]), limit (por defecto 100) y value_max_chars (por defecto 2000) lo acotan. Las filas de auditoría que repiten una entrada de diario se omiten. Si una fuente no se puede leer (ACL o política), se informa bajo sources y la otra aún se devuelve.

  • servicenow_get_properties (properties) — un name exacto o un nombre prefix → filas de sys_properties. Las propiedades de tipo contraseña o de aspecto secreto se devuelven como [redacted], y los valores largos se truncan.

  • servicenow_set_property (properties) — establece el valor de una propiedad existente. Se ejecuta como plan/aplicar: el plan muestra el valor actual y el nuevo, y la aplicación se registra en el diario. servicenow_revert_write puede deshacerlo, excepto para propiedades secretas, que nunca se registran en claro. Respeta SN_READONLY y SN_PACKAGES_READONLY=properties. Una propiedad faltante es PROPERTY_NOT_FOUND; la herramienta nunca crea una.

  • servicenow_lookup_directory (directory) — kind (user / group / role) más una búsqueda term o un sys_id. Con include_details y exactamente una coincidencia, el resultado añade:

    • para un usuario, sus roles y grupos;
    • para un grupo, sus miembros y roles;
    • para un rol, sus roles contenidos y los grupos que lo otorgan.

    Una tabla de detalle que no se puede leer se lista en details_unavailable. Pon directory en SN_PACKAGES_DENY para eliminar la superficie de datos de usuario.

Descubrimiento de instancias

servicenow_document_instance (docs) toma un depth opcional que añade una carpeta de descubrimiento, <SN_DOCS_DIR>/<profile>/discovery/, junto a README.md. Los niveles son acumulativos:

depthArchivos
overviewoverview.md — versión, conteos, automatización, los archivos escritos
apps+ apps.md y un tables-<scope>.md por alcance (tablas y su diccionario)
artefacts+ un artifacts-<scope>.md por alcance

Los alcances son los apps nombrados, si no, cada alcance sys_app no global, hasta el límite objetivo por ejecución (el resto se lista como omitido). artifacts-<scope>.md lista cada tipo de artefacto con una columna Recopilado / no recopilado y por qué: recopilado (con un conteo), limitado, no verificado (la tabla no es legible aquí), sin tal tabla, ilegible para este usuario, paquete desactivado o sin registros en este alcance. Cada lectura pasa por la misma política, redacción, verificación previa de capacidades y diario de escritura que los otros generadores. Sin depth la herramienta se comporta como antes.

Habilidades del plugin

El plugin de Claude Code (/plugin install servicenow-mcp-ai) incluye cinco habilidades bajo skills/. Cada una solo orquesta las herramientas de este servidor; ninguna contiene credenciales ni llama a ServiceNow por sí sola.

HabilidadÚsala para
sn-discoverMapear una instancia o sus aplicaciones personalizadas con servicenow_document_instance({depth})
sn-triageInvestigar un registro, flujo o script fallido (estado, historial, lógica, registros)
sn-impactEvaluar qué afectaría un cambio en una tabla, campo o script (dónde se usa, lógica de tabla)
sn-driftComparar dos instancias o una instantánea guardada, o revisar un conjunto de actualizaciones
sn-safe-writeHacer un cambio de registro con plan-y-aplicar, el diario de escritura y una ruta de reversión

Una prueba (test/plugin-skills.test.js) verifica que cada nombre de servicenow_* en una habilidad exista en el manifiesto de herramientas. Las habilidades no forman parte del paquete npm.

Árbol de Service Portal

servicenow_explain_portal (ui, opt-in) explica un Service Portal (portal: url_suffix o sys_id) o una página (page: página id o sys_id) como un árbol. El árbol va de página → contenedor → fila → columna → instancia de widget → widget. Las instancias widget_parameters se mapean sobre el option_schema del widget, y cada widget lista sus dependencias, inclusiones de JS / CSS, proveedores Angular y plantillas. El tema, menú, encabezado / pie de página y mapas de rutas se incluyen. Las filas anidadas se siguen hasta depth (por defecto 3, máximo 6), y el diseño se lee para las primeras 5 páginas. format es json, markdown, mermaid (árbol de diseño) o file. Una tabla de Service Portal que no se puede leer se convierte en una advertencia, no en un fallo.

El paquete cmdb también tiene servicenow_list_ci_relations (relaciones de cmdb_rel_ci de una CI en cualquier dirección, con el nombre y la clase de la CI relacionada) y servicenow_identify_reconcile, que envía una carga útil de IRE de elementos y relaciones. En modo plan, servicenow_identify_reconcile llama al endpoint de solo identificación y muestra lo que IRE coincidiría; cuando el endpoint falta, el plan se marca como degraded. Aplicar se registra en el diario pero no es reversible, porque IRE decide por elemento.

servicenow_run_atf_test y servicenow_run_atf_suite toman wait_seconds (0–300). La herramienta consulta el endpoint de progreso de CI/CD con notificaciones de progreso, y cancelar la solicitud detiene la espera. Una ejecución que aún está en curso cuando el tiempo se agota devuelve wait.state: "running" con un tracker para servicenow_get_atf_result.

servicenow_insert_import_set_row también devuelve import_set_run (la fila sys_import_set_run del conjunto de importación) y transform_maps (los mapas de la tabla de staging, los que usó esta fila marcados como used: true). Si alguna de las lecturas de seguimiento falla, obtienes warnings en lugar de un error.

Lecturas genéricas de artefactos

El paquete opt-in artifacts lee cualquier tipo en el registro de artefactos (el recurso servicenow://artifact-types los lista, con sus tablas, campos clave y tablas hijas):

  • servicenow_list_artifacts — artifactType más scope opcional (espacio de nombres o sys_id), active, query y limit → resúmenes: sys_id, nombre, clave natural, alcance, indicador de activo, veredicto de gestión SDK y los metadatos del tipo. Sin cuerpos de script.
  • servicenow_get_artifact — artifactType más sys_id o la key natural → el registro completo, sus registros hijos en orden de registro (las acciones de una política de UI; los contenedores, filas, columnas e instancias de widget de una página de portal; las instancias de acción de un flujo), su alcance y si ese alcance está gestionado por SDK.
  • servicenow_explain_artifact — misma identificación → una explicación estructurada: un summary de una línea, when cuando se ejecuta (los campos de disparo que están establecidos), sus fields no vacíos, sus registros hijos como items compactos, los registros que references, y sus campos JSON codificados decoded (parámetros de widget, props y datos de UI Builder, cachés de etiquetas de flujo). Un valor que no se puede decodificar se devuelve en bruto con decoded: false y un reason — un campo defectuoso nunca falla la llamada. Los valores largos se limitan contra SN_MAX_RESULT_CHARS (un valor recibe como máximo una vigésima parte, la explicación completa cuatro quintos); truncatedFields, truncated / preview y el conteo de omitted de un hijo dicen qué se recortó. Los valores de acciones de flujo y las composiciones de UI Builder se leen con el decodificador JSON simple hasta que sus decodificadores dedicados se publiquen (via: "json"). Algunos tipos también obtienen un explanation con lines de prosa: un modelo de estado lista sus estados y transiciones from -> to con sus condiciones, un conjunto de opciones o tabla sus opciones por elemento en orden de secuencia, y una política de UI o de datos el efecto en cada campo cuando su condición se cumple (y, con inverso-si-falso, cuando no).
  • servicenow_artifact_dependencies — misma identificación más direction (outbound / inbound / both, por defecto), depth (1–3, por defecto 1), limit (filas por fuente entrante, 1–100) y format (json o mermaid) → un grafo de dependencias de nodes y edges (from depende de to, con via y field). Los bordes salientes provienen de campos de referencia del registro en el registro y sus hijos, JSON decodificado (valores de pasos de flujo, opciones de widget, datos de UI Builder) y texto de script (llamadas de script-include, clases GlideAjax, tablas GlideRecord literales). Los bordes entrantes provienen de consultas de referencia inversa y — para un script include — llamadores de script, pasos de flujo cuyos valores lo llaman y el pase estructural del grafo de dónde se usa. El recorrido visita cada nodo una vez (los ciclos son seguros), se detiene en 150 nodos (truncated), y convierte una fuente ilegible en una entrada unavailable en lugar de un error.

Cada lectura de tabla obedece SN_TABLES_ALLOW / SN_TABLES_DENY; una tabla hija denegada se devuelve como redacted: true en lugar de fallar la lectura, y SN_REDACT_FIELDS / SN_REDACT_PII se aplican como en todas partes. Los tipos cuyas tablas aún no están confirmadas en una instancia en vivo llevan verified: false y un caveat; cuando la instancia rechaza tal tabla, el resultado es vacío con una razón degraded en lugar de un error, más available: false cuando sys_db_object muestra que la tabla no existe en la instancia.

Ejemplos

Consulta los 5 incidentes activos más recientes:

// servicenow_query_table
{
  "table": "incident",
  "query": "active=true^ORDERBYDESCsys_created_on",
  "fields": ["number", "short_description", "priority", "state"],
  "limit": 5,
}

Crea un incidente:

// servicenow_create_record
{
  "table": "incident",
  "fields": {
    "short_description": "Printer on 3rd floor is down",
    "urgency": "2",
    "impact": "2",
  },
}

Actualiza credenciales en tiempo de ejecución:

// servicenow_set_credentials
{
  "instance": "dev98765.service-now.com",
  "user": "admin",
  "password": "••••••",
}

Recursos

Los metadatos de solo lectura también se exponen como recursos MCP, para que los clientes puedan adjuntarlos declarativamente en lugar de llamar a una herramienta:

URIDescripción
servicenow://statusEstado de conexión, modo de autenticación, política de acceso (nunca incluye la contraseña).
servicenow://capabilitiesVerificación previa de capacidades: qué lecturas sys_* restringidas por administrador (esquema, inteligencia de scripts, auditoría de ACL) puede lograr realmente el usuario conectado, más la matriz de capacidades por grupo.
servicenow://tablesLista de tablas desde sys_db_object.
servicenow://schema/{table}Columnas de una tabla desde sys_dictionary (vinculadas al perfil activo).
servicenow://instancesPerfiles de conexión configurados: nombre, host, usuario, indicador de solo lectura, completitud de credenciales.
servicenow://{profile}/schema/{table}Columnas de una tabla leídas a través de un perfil de conexión nombrado específico.
servicenow://docs/{+path}Un documento Markdown del almacén de documentos local (se permiten rutas anidadas), envuelto en un bloque de contenido no confiable.
servicenow://artifact-typesTipos de artefactos que aceptan las herramientas genéricas de artefactos: tabla, campos de nombre / clave / alcance, tablas hijas, API de SDK, indicador verificado (paquete artifacts).
servicenow://reference/encoded-queryReferencia de consulta codificada: sintaxis, valores javascript:, límites (sin escape ^, longitud de URL, campos ignorados silenciosamente, filas ocultas por ACL) y cómo fetchAll pagina.
servicenow://reference/toolsEl manifiesto de herramientas como Markdown: cada herramienta por paquete, lectura / escritura, y si esta sesión la registró bajo la política de paquetes.
Los recursos están sujetos a paquetes como las herramientas: status, capabilities y la referencia de herramienta están siempre activos; encoded-query viene con el paquete table, tables/schema con el paquete schema, instances/esquema por perfil con instance, y docs con el paquete docs.

Las tres plantillas admiten autocompletado y listado: {table} completa desde las tablas ya presentes en la caché de esquema más una breve lista semilla de tablas comunes, {profile} desde los perfiles configurados, y {path} desde el manifiesto de documentación (index.json) por prefijo y bajo la carpeta del perfil activo. resources/list muestra las tablas en caché y los documentos (los generados primero, titulados desde el manifiesto; como máximo 100 por plantilla, con los documentos index.md siempre al final). Los listados y autocompletados nunca llaman a la instancia.

Prompts

Los flujos de trabajo listos para usar se exponen como prompts de MCP; orquestan las herramientas e insisten en leer valores reales de la instancia. Los argumentos de table y profile se completan como las plantillas de recursos. Los argumentos (máximo 200 caracteres) llegan al modelo dentro de un bloque de contenido no confiable, y cada prompt le indica al modelo que trate los datos de la instancia como datos, no como instrucciones. Un prompt solo se lista cuando los paquetes en los que viven sus herramientas están habilitados (triaje: table; impacto de cambios: change o table; tabla de documentos: docs y scripts; por qué es lento: ops; la vista general de la instancia usa solo herramientas de administración y siempre se lista). La lista sigue servicenow_enable_package / servicenow_disable_package en vivo, con notifications/prompts/list_changed:

PromptArgumentoPropósito
servicenow_incident_triageincidentResumir, evaluar prioridad, categorizar y recomendar próximos pasos.
servicenow_change_impact_analysischangeCIs afectados, conflictos de agenda y una llamada de aprobar/no aprobar.
servicenow_document_tabletable, profileEjecuta servicenow_document_table, luego completa el bloque manual de Propósito de <profile>/tables/<table>.md; adjunta la referencia de consulta codificada.
servicenow_why_is_it_slowsymptom, table (ambos opcionales)Registro del sistema, backlog del programador, cola de correo y semáforos (ops), luego la lógica sobre una tabla → causas clasificadas.
servicenow_instance_overviewgoal (opcional)Matriz de capacidades (servicenow_check_capabilities), estado y los paquetes de la sesión; trata el perfil como producción hasta que H-11 agregue un marcador de entorno.

Estructura del proyecto

.
├── .env                   # credentials (git-ignored; or ~/.config/servicenow-mcp-ai/.env)
├── .env.example           # template
├── .github/workflows/     # CI matrix, CodeQL, npm / MCP Registry / Marketplace publishing
├── .vscode/mcp.json       # VS Code MCP server registration
├── bin/                   # CLI launcher (servicenow-mcp-ai.cjs, incl. the doctor command)
├── extension/             # VS Code extension (thin wrapper that registers the server)
├── docs/                  # GitHub Pages site
├── scripts/               # generators + guards (README tools table, tool manifest, coverage guard)
├── src/
│   ├── index.ts           # bootstrap: load env, register, connect transport
│   ├── core/              # HTTP client (auth, retry, SSRF guard), OAuth/JWT/mTLS, policy,
│   │                      # settings, logging, config store, write journal, request
│   │                      # context (profiles); jira/ is a dark scaffold — no tools (ARCH-14)
│   ├── api/               # one module per REST area: table, aggregate, attachment,
│   │                      # importset, batch, catalog, change, knowledge, cmdb, scripts,
│   │                      # flows, codecheck, atf, email, docs, diagrams, meta, doctor,
│   │                      # history, properties, directory, portal…
│   ├── mcp/               # MCP surface: package registry/manifest, tool definition,
│   │                      # resources, prompts, result envelopes, redaction, write mode
│   │                      # (plan/apply), CSV export, stdio + HTTP transports
│   └── tools/             # tool registrations, one file per package (26 packages)
├── test/                  # node:test suite (406 tests): unit, mock-fetch api, MCP smoke, doc guards
└── build/                 # compiled output (after npm run build)

Nota sobre nombres: el paquete npm y el repositorio de GitHub son ambos servicenow-mcp-ai (el servicenow-mcp sin ámbito ya estaba tomado en npm); la carpeta de trabajo local es servicenow-mcp. La diferencia es cosmética y no afecta la compilación ni el tiempo de ejecución.

Notas de seguridad

  • El archivo de entorno está ignorado por git — no confirmes credenciales reales.
  • El archivo de entorno se escribe solo para el propietario (0600) — contiene una contraseña en texto plano.
  • El servidor usa el transporte stdio y solo registra en stderr; los secretos y las consultas codificadas sin procesar nunca se registran.
  • La contraseña/token nunca se devuelve mediante ninguna herramienta.
  • Los hosts están restringidos: sin SN_ALLOWED_HOSTS, solo se contactan instancias *.service-now.com (interno/loopback bloqueado a menos que una entrada de lista de permitidos nombre el host exactamente), por lo que un host mal escrito no puede recibir credenciales silenciosamente. Las redirecciones nunca se siguen (REDIRECT_BLOCKED) y los cuerpos de respuesta están limitados por SN_MAX_BODY_BYTES. Establece SN_ALLOWED_HOSTS para optar por un dominio personalizado o de nube soberana. Un puerto explícito distinto de 443 o un literal IPv6 en el valor de la instancia se acepta solo cuando una entrada de lista de permitidos lo nombra (host:8443, [2001:db8::1]).
  • Cada solicitud — incluidas las solicitudes de token OAuth — lleva el User-Agent: servicenow-mcp-ai/<version> (node/<major>; <transport>; <client>) identificador para que el registro de transacciones de la instancia pueda atribuir el tráfico; extiéndelo con SN_USER_AGENT_SUFFIX. Las URL de proxy (SN_HTTPS_PROXY, HTTPS_PROXY) se respetan para cada solicitud, pero sus credenciales nunca se registran.
  • Prefiere OAuth 2.0 sobre Basic cuando sea posible (SN_OAUTH_CLIENT_ID).
  • Aplica el principio de mínimo privilegio con SN_TABLES_ALLOW / SN_TABLES_DENY y SN_READONLY=true para implementaciones de solo lectura.
  • La política de tablas no cubre las API de complementos. SN_TABLES_DENY=change_request bloquea la ruta de la API de Tablas, pero la API de Gestión de Cambios (sn_chg_rest) aún puede leer/escribir cambios. Para restringir las superficies respaldadas por complementos, usa SN_PACKAGES_DENY (elimina todo el paquete) o SN_PACKAGES_READONLY (registra solo sus herramientas de lectura). La API de Lotes también obedece ambos ejes: una sub-solicitud a la ruta de un paquete denegado se rechaza, y las escrituras a un paquete de solo lectura se bloquean — un lote no se puede usar para eludir la política de paquetes.

Documentación del proyecto

DocumentoContenido
ARCHITECTURE.mdArquitectura en capas, diagramas Mermaid (módulos, ciclo de vida de solicitudes, modelo de seguridad, autenticación, paquetes), ADRs condensados
PRODUCT-STATE.mdEstado actual del producto: mapa de cobertura de API, estado de calidad, línea de tiempo histórica, hoja de ruta
ROADMAP.mdPlan a futuro: las fases enviadas, la línea de endurecimiento 2.x, el hito 3.0 propuesto, elementos opcionales y diferidos
ROADMAP-V3.md / DEEP-REVIEW-2026-09.mdEl rastreador de ejecución v3.0 propuesto (corrección, gobernanza, alcance a escala) / la revisión de cinco lentes sobre la que se construyen sus elementos
GAP-ANALYSIS-2026-09.mdLa segunda pasada del 2026-09-09 sobre el plan v3.0: nueve lentes más estrechos, 67 hallazgos cada uno con diseño, criterios de aceptación y pruebas, mapeados a elementos del rastreador
INSTANCE-DOCS-ANALYSIS-2026-09.mdLa pasada del 2026-09-23 sobre la documentación de la instancia: el almacén de documentos, los generadores Mermaid, el prompt document_table y los tipos de documentos faltantes — 17 hallazgos con diseño, criterios de aceptación y pruebas, mapeados a S-14 … S-16
INSTANCE-DOCS-ANALYSIS-2026-09-25.mdLa segunda pasada del 2026-09-25 sobre la documentación de la instancia: disposiciones de los primeros 17 hallazgos después de que el almacén de documentos, el registro de artefactos, los lectores de artefactos y el escaneo de seguridad aterrizaran, más 12 nuevos hallazgos (ID-18 … ID-29) con diseño, criterios de aceptación y pruebas, mapeados a S-15, S-16, M-4, M-8, S-7, E-6, E-7
COMPETITIVE-ANALYSIS.mdPosicionamiento frente al ServiceNow MCP Server Console oficial: comparación, dónde se queda atrás estructuralmente, el plan de impulso de la Fase 9 y riesgos de plataforma
IMPLEMENTATION-PLAN.mdEspecificaciones detalladas para las próximas fases (harness 2.0, multi-instancia, pruebas de flujo)
DONE.md / TODO.mdTrabajo completado con referencias de confirmación / decisiones pendientes
WORKLOG.md / CHANGELOG.mdDiario de trabajo detallado / registro de cambios orientado al usuario
CONTRIBUTING.md / SECURITY.mdConfiguración de desarrollo, puertas y convenciones / modelo de seguridad y reporte

Soporte

Este proyecto se construye y mantiene en mi tiempo libre. Si te ahorra tiempo a ti o a tu equipo, considera apoyar su desarrollo continuo — el patrocinio financia directamente nuevas herramientas, correcciones de errores y mantenerse al día con la superficie REST de ServiceNow.

  • GitHub Sponsors — apoyo único o recurrente, sin comisión de plataforma (la opción preferida).
  • Ko-fi — apoyo único rápido; también acepta PayPal, por lo que es la alternativa para quienes no tienen cuenta de GitHub.
  • Donar (Donatree) — una página de donación sin cuenta (tarjeta, PayPal y más) para una propina única.

Sponsor on GitHub Support on Ko-fi Donate via Donatree

Marca registrada

servicenow-mcp-ai es un proyecto independiente construido por la comunidad. No está afiliado, respaldado ni patrocinado por ServiceNow, Inc.

"ServiceNow", el logotipo de ServiceNow, "Now" y las marcas relacionadas son marcas comerciales o marcas registradas de ServiceNow, Inc. en los Estados Unidos y otros países. Se usan en el nombre y la documentación de este proyecto solo de manera nominativa — para identificar la plataforma con la que este software interoperar — y no se implica afiliación ni respaldo. Todos los demás nombres de productos y marcas son propiedad de sus respectivos dueños.

Este proyecto está licenciado bajo la Licencia MIT; esa licencia cubre el código fuente y no otorga ningún derecho para usar las marcas comerciales de ServiceNow.