ServiceNow MCP Server

O servidor MCP mais abrangente para ServiceNow — 17 ferramentas para CRUD completo, travessia de grafo CMDB, scripts em segundo plano e testes ATF. Funciona com Claude, Cursor e qualquer cliente MCP.

GitHub

Experimente este MCPPatrocinado

Documentação

@onlyflows/servicenow-mcp

O servidor MCP ServiceNow mais abrangente. 19 ferramentas para CRUD completo, journals de incidentes somente anexação, travessia de grafo CMDB, testes ATF, perfis multi-instância e muito mais.

Construído por OnlyFlows · Publicado por @onlyflowstech

Instalação

npm install -g @onlyflows/servicenow-mcp
servicenow-mcp-setup

Execute diretamente em um terminal; o servicenow-mcp-setup guia você por todo o processo em um único comando: ele gera o material de autenticação local, solicita sua instância e credencial, verifica essa credencial contra a instância, pergunta quais tabelas conceder, grava o perfil e registra qualquer cliente suportado cuja CLI esteja instalada. A credencial é inserida em um prompt oculto — nunca um argumento, nunca no histórico do shell — e nada é gravado no perfil até que a instância a tenha aceitado, então um erro de digitação ou uma senha errada não deixa nada para trás.

ServiceNow MCP setup

This walks through one ServiceNow connection end to end. Nothing is
written to the profile until your credential is verified against the
instance. Press Ctrl+C at any point to stop; nothing will be saved.

Profile name [dev]: dev
ServiceNow instance (for example dev12345.service-now.com): dev12345.service-now.com
Authentication:
  1) basic (default)
  2) oauth
  3) apikey
Choice [1]: 1
How should the credential be stored?:
  1) encrypted (default)
  2) reference
Choice [1]: 1
ServiceNow username: integration.user

Enter each secret now. Input is hidden — nothing you type from here
is displayed.
credential:

Verifying against the instance...
  ok  https://dev12345.service-now.com accepted the credential.

Table access is deny-by-default: a profile with no rules denies every
tool call. Grant the narrowest set that does the job; you can add more
later with servicenow-mcp-setup grant.

Tables to allow for READS:
  1) Just incident (default)
  2) Common ITSM set (incident,change_request,problem,task,sys_user)
  3) All tables (*)
  4) Enter a custom list
  5) None
Choice [1]: 1

Tables to allow for WRITES:
  1) Just incident
  2) Common ITSM set (incident,change_request,problem,task,sys_user)
  3) All tables (*)
  4) Enter a custom list
  5) None (default)
Choice [5]: 1

Wrote profile dev.

Register this server with codex and claude-code? [Y/n]: y

ServiceNow MCP doctor

ok    node: v22.11.0
ok    server command: servicenow-mcp resolves on PATH; clients spawn it over stdio
ok    config directory: ~/.servicenow-mcp (0700)
ok    profile dev: instance: https://dev12345.service-now.com
ok    profile dev: credential: basic credential resolves from its encrypted source
ok    profile dev: table access: 1 read, 1 write, 1 target(s)

All checks passed.

Setup complete.

Profile   dev
Reads     incident
Writes    incident
Transport stdio (each client spawns its own servicenow-mcp)
Clients   codex, claude-code

Start codex or claude-code and it will launch the server itself.
There is nothing to keep running between sessions.

Não há nada para iniciar. O servidor fala stdio: cada cliente registrado inicia sua própria cópia do servicenow-mcp sob demanda e conversa com ele pelo stdin e stdout desse processo. A configuração termina executando as mesmas verificações que o doctor executa, para que você possa reexecutá-las a qualquer momento:

servicenow-mcp-setup doctor --profile dev

O npx @onlyflows/servicenow-mcp@latest setup executa o mesmo assistente sem uma instalação global, e o servicenow-mcp setup é um alias para servicenow-mcp-setup.

Configuração por script

Passe qualquer flag, ou execute sem um terminal, e o assistente dá lugar ao comportamento não interativo original — portanto, CI e scripts de provisionamento não são afetados. O --non-interactive força isso explicitamente:

servicenow-mcp-setup --non-interactive --clients none --json
servicenow-mcp-profile create --name dev --instance https://yourinstance.service-now.com \
  --auth-type oauth --client-id <client-id> --source reference --provider env
servicenow-mcp-setup grant --profile dev --read incident,problem --write incident

Os comandos `servicenow-mcp-setup`

Comando	Finalidade
`servicenow-mcp-setup`	Gerar material de autenticação local e registrar clientes suportados
`servicenow-mcp-setup client --client <name>`	Imprimir configuração copiável para um cliente
`servicenow-mcp-setup grant --profile <name> --read <tables>`	Adicionar regras de acesso a tabelas a um perfil
`servicenow-mcp-setup doctor`	Diagnosticar a instalação e imprimir soluções

O --force regenera os identificadores de proprietário/cliente, mas preserva deliberadamente o SN_PROFILE_ENCRYPTION_KEY, que descriptografa todos os envelopes de credenciais em config.json. Adicione --help a qualquer comando para ver suas opções completas.

O servidor executa como você, e a lista de clientes é o limite. Nada escuta em uma porta, então nada fora desta máquina pode alcançá-lo e nenhuma página web pode acioná-lo. O que resta é o registro: cada cliente MCP registrado aqui pode iniciar o servidor e usar qualquer acesso ServiceNow que seus perfis concedam, como sua conta de integração. Mantenha as concessões restritas e remova um cliente que você não usa mais com claude mcp remove servicenow-mcp ou codex mcp remove servicenow-mcp. Nenhuma credencial ServiceNow é copiada para o arquivo de configuração de um cliente — o servidor iniciado lê o perfil e sua chave de criptografia do diretório ~/.servicenow-mcp somente do proprietário.

Conectando um cliente

O servicenow-mcp-setup registra Codex e Claude Code automaticamente quando suas CLIs estão no PATH. Para todo o resto:

servicenow-mcp-setup client --client claude-desktop
servicenow-mcp-setup client --client all

Todo cliente suportado fala stdio nativamente, então cada um é configurado da mesma forma: um comando para iniciar.

claude mcp add servicenow-mcp -- servicenow-mcp
codex mcp add servicenow-mcp -- servicenow-mcp

stdio é o transporte padrão para ambas as CLIs, então não há flag de transporte a passar. Para clientes configurados por arquivo:

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

Cliente	Configurado por	Local da configuração
Claude Code	`claude mcp add` ou `.mcp.json`	projeto ou `--scope user`
Codex	`codex mcp add` ou `config.toml`	`~/.codex/config.toml`
Cursor	arquivo	`~/.cursor/mcp.json` ou `.cursor/mcp.json`
VS Code	arquivo (`"type": "stdio"`)	`.vscode/mcp.json` ou usuário `mcp.json`
Claude Desktop	arquivo	`claude_desktop_config.json`
Windsurf	arquivo	`~/.codeium/windsurf/mcp_config.json`

Nenhum cliente guarda uma credencial ServiceNow. O servidor iniciado resolve a sua própria a partir de ~/.servicenow-mcp, que é somente do proprietário.

Blocos completos por cliente estão em Configuração de serviço e cliente V2.

O servicenow-mcp deve estar no PATH do cliente que inicia. Uma instalação global via npm o coloca lá. Se não estiver — uma instalação local ao projeto, ou um cliente GUI com um PATH diferente — registre o entrypoint absoluto; o servicenow-mcp-setup doctor verifica isso e imprime o comando exato.

Criação guiada de perfil a partir do seu cliente

Após o bootstrap, um cliente MCP conectado pode guiá-lo pela criação de perfil:

Add a ServiceNow MCP profile for https://yourinstance.service-now.com

O prompt MCP é servicenow-mcp.add-profile. Ele orienta a nomeação do perfil, o modo de autenticação e o acesso de privilégio mínimo com negação por padrão, e deliberadamente não pede que você cole senhas, chaves de API, tokens de portador, segredos de cliente OAuth ou chaves de criptografia no chat.

O que é instalado

servicenow-mcp — o próprio servidor MCP, iniciado por um cliente via stdio
servicenow-mcp-profile — gerencia credenciais de perfil fora de banda
servicenow-mcp-setup — bootstrap, configuração de cliente, concessões e diagnóstico

Configuração manual sem o bootstrap

O servidor mantém a configuração explícita. Uma execução manual precisa de:

identidade de auditoria: MCP_OWNER_ID e MCP_CLIENT_ID (opcional; elas rotulam registros de auditoria e usam como padrão local-owner/local-client)
um perfil ServiceNow nomeado, seja em ~/.servicenow-mcp/config.json ou por meio de SN_PROFILE_NAME + SN_INSTANCE + variáveis SN_* específicas de autenticação
regras de acesso a tabelas por perfil; acesso não configurado nega tudo

O caminho de ambiente SN_* cria um perfil somente quando o ~/.servicenow-mcp/config.json não existe. Uma vez que você cria um arquivo de perfil, SN_ALLOWED_READ_TABLES, SN_ALLOWED_WRITE_TABLES e SN_TABLE_ACCESS_TARGETS deixam de se aplicar e as regras devem viver no perfil (servicenow-mcp-setup grant). Esta é a causa mais comum de um servidor que nega toda chamada; o servicenow-mcp-setup doctor detecta isso.

O servidor lê o ~/.servicenow-mcp/server.env por conta própria na inicialização, porque o cliente que o inicia fornece seu próprio ambiente e não terá carregado nada. Um valor já presente no ambiente sempre vence sobre esse arquivo, então a configuração de contêiner e CI não é afetada.

Para uma execução rápida somente com ambiente e sem arquivo de perfil — dirigindo o servidor manualmente por um pipe, ou a partir de um cliente que passa variáveis de ambiente — injete valores protegidos do seu chaveiro ou gerenciador de segredos e passe apenas valores não secretos na linha de comando:

MCP_OWNER_ID=local-owner \
MCP_CLIENT_ID=local-client \
SN_PROFILE_NAME=dev \
SN_INSTANCE=https://yourinstance.service-now.com \
SN_USER=your_user \
SN_ALLOWED_READ_TABLES=incident,problem,change_request \
SN_ALLOWED_WRITE_TABLES=incident,change_request \
SN_TABLE_ACCESS_TARGETS='[{"table":"incident","kind":"canonical","tools":["sn_query","sn_get","sn_create","sn_update","sn_incident_add_comment","sn_incident_add_work_note","sn_delete","sn_batch"],"closureComplete":true,"relatedTables":["incident"]},{"table":"problem","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["problem"]},{"table":"change_request","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["change_request"]}]' \
servicenow-mcp

Não coloque SN_PASSWORD, segredos de cliente OAuth ou chaves de API no histórico de comandos. Injete-os no ambiente do servidor a partir do seu mecanismo de segredos aprovado, ou deixe-os no arquivo de perfil somente do proprietário, onde o servidor pode resolvê-los sem que nenhum cliente os veja.

Instalação a partir do código-fonte para desenvolvimento

Use a instalação a partir do código-fonte apenas para desenvolvimento ou mudanças não publicadas:

git clone https://github.com/onlyflowstech/servicenow-mcp.git
cd servicenow-mcp
npm install
npm run build
npm start

Para desenvolvimento local com recompilação e source maps:

npm run dev

A implantação em contêiner se aplica ao transporte HTTP dormente, e não a uma instalação stdio 2.0; veja Implantação de contêiner em produção e o limite empresarial.

Perfis Multi-Instância

Gerencie múltiplas instâncias ServiceNow (dev, teste, prod, PDI) com perfis nomeados. Toda chamada de ferramenta deve selecionar um perfil configurado explicitamente; o V2 não tem fallback de perfil ativo ou padrão.

Configuração

Crie perfis com a CLI em vez de manualmente — ela captura credenciais sem colocá-las em argv e grava o arquivo com a propriedade e o modo corretos:

servicenow-mcp-profile create --name dev  --instance https://mydev.service-now.com  --auth-type basic --username admin    --source reference --provider env
servicenow-mcp-profile create --name prod --instance https://myprod.service-now.com --auth-type basic --username api.user --source reference --provider env

servicenow-mcp-setup grant --profile dev  --read incident,problem --write incident
servicenow-mcp-setup grant --profile prod --read incident

O ~/.servicenow-mcp/config.json resultante se parece com isto. Observe o tableAccess: um perfil sem ele nega toda chamada de ferramenta.

{
  "version": 2,
  "profiles": {
    "dev": {
      "instance": "https://mydev.service-now.com",
      "username": "admin",
      "credential": { "type": "secret_ref", "provider": "env", "reference": "SN_PASSWORD_DEV" },
      "description": "Development instance",
      "tableAccess": {
        "readTables": ["incident", "problem"],
        "writeTables": ["incident"],
        "targets": [
          {
            "table": "incident",
            "kind": "canonical",
            "tools": ["sn_query", "sn_get", "sn_aggregate", "sn_schema", "sn_create", "sn_update"],
            "closureComplete": true,
            "relatedTables": ["incident"]
          },
          {
            "table": "problem",
            "kind": "canonical",
            "tools": ["sn_query", "sn_get", "sn_aggregate", "sn_schema"],
            "closureComplete": true,
            "relatedTables": ["problem"]
          }
        ]
      }
    }
  }
}

Peça ao supervisor, orquestrador, chaveiro ou gerenciador de segredos aprovado para fornecer os valores referenciados por SN_PASSWORD_DEV e SN_PASSWORD_PROD no ambiente em que o servidor é iniciado, ou em ~/.servicenow-mcp/server.env, ao qual o servidor recorre. Não digite nenhum dos valores em um comando de shell, argumento de comando, arquivo dotenv ou histórico de comandos.

Cada entrada targets afirma closureComplete: true, ou seja, o relatedTables lista todas as tabelas de suporte, ancestrais e descendentes que a operação pode alcançar. Quando uma tabela estende outra, declare-a: servicenow-mcp-setup grant --profile dev --read change_request --related change_request=task. Tabelas relacionadas entram na allowlist, mas não recebem alvo próprio, então um chamador não pode endereçá-las diretamente.

Opções de Credencial

Formato	Exemplo	Descrição
Referência de ambiente legada	`"env:SN_PASSWORD_DEV"`	Forma V1 compatível com leitura; migrada para uma referência estruturada na próxima gravação
Referência de segredo	`{"type":"secret_ref","provider":"env","reference":"SN_PASSWORD_DEV"}`	Referência neutra de provedor resolvida apenas para a solicitação selecionada
Envelope criptografado	`{"type":"encrypted","version":1,...}`	Valor AES-256-GCM criado pela CLI de administração protegida

Segredos de perfil em texto puro são rejeitados. Use o comando de operador servicenow-mcp-profile instalado para criar, inspecionar, rotacionar ou remover perfis; ele lê segredos por meio de um prompt protegido ou entrada padrão limitada e rejeita argumentos de linha de comando que contenham credenciais. Fontes criptografadas exigem exatamente 32 bytes aleatórios codificados como base64 ou base64url em SN_PROFILE_ENCRYPTION_KEY, fornecidos separadamente pelo mecanismo de segredos da implantação e nunca armazenados no arquivo de perfil. Veja o guia de credenciais de perfil e administração.

A indireção legada env:VAR_NAME permanece legível para cada campo de segredo: credential, clientSecret e apiKey.

Usando Perfis

Passe o parâmetro profile em toda chamada de ferramenta:

"consultar incidentes em prod" — chama sn_query com profile: "prod"
"obter incidente INC0010001 em dev" — chama sn_get com profile: "dev"
"mostre-me o endpoint do perfil dev" — chama o diagnóstico somente leitura sn_profile com profile: "dev"

Os perfis são criados e alterados fora de banda pelo operador do serviço. Os metadados legados default_profile são ignorados e não são persistidos na próxima gravação administrativa; o limite MCP nunca os consulta.

Compatibilidade de configuração `SN_*`

Se nenhum arquivo de configuração existir, os valores de conexão canônicos SN_* são expostos apenas por meio de um mapeamento explícito SN_PROFILE_NAME. Por exemplo, defina SN_PROFILE_NAME=dev com SN_INSTANCE, SN_USER e SN_PASSWORD, depois chame ferramentas com profile: "dev". Sem SN_PROFILE_NAME, variáveis de conexão simples não criam perfil e não podem rotear uma solicitação. Valores secretos permanecem referências de ambiente somente em tempo de execução e nunca são persistidos como texto puro.

Autenticação

Três tipos de autenticação ServiceNow estão disponíveis por perfil, selecionados com authType (padrão: basic). A configuração do perfil é gerenciada fora de banda pelo operador do serviço. Esta é a única autenticação envolvida: o transporte é stdio, então não há endpoint na frente do servidor para proteger.

Atenção: o programa de restrição de autenticação básica de entrada do ServiceNow está eliminando gradualmente a autenticação básica para solicitações de API — as instâncias podem começar a rejeitá-la a qualquer momento (isenções: contas Web-Service-Access-Only ou a função snc_basic_auth_api_access). OAuth é o tipo de autenticação recomendado. O servidor imprime um aviso de inicialização para perfis de autenticação básica.

OAuth 2.0 (recomendado)

Concessão client_credentials (padrão) — crie um cliente de endpoint de API OAuth no ServiceNow (System OAuth → Application Registry) e referencie o segredo via indireção env::

{
  "version": 2,
  "profiles": {
    "dev": {
      "instance": "https://mydev.service-now.com",
      "authType": "oauth",
      "clientId": "your-oauth-client-id",
      "clientSecret": "env:SN_CLIENT_SECRET",
      "description": "OAuth client_credentials"
    }
  }
}

Concessão password — defina grantType e forneça as credenciais do usuário também:

{
  "instance": "https://mydev.service-now.com",
  "authType": "oauth",
  "grantType": "password",
  "clientId": "your-oauth-client-id",
  "clientSecret": "env:SN_CLIENT_SECRET",
  "username": "integration.user",
  "credential": "env:SN_PASSWORD_DEV"
}

Os tokens são armazenados em cache até pouco antes da expiração do expires_in e renovados automaticamente (incluindo uma única renovação + nova tentativa em 401). As respostas de token nunca são registradas.

Chave de API

Para instâncias que usam Perfis de Autenticação de Entrada com chaves de API. O nome do cabeçalho é configurável (padrão x-sn-apikey):

{
  "instance": "https://mydev.service-now.com",
  "authType": "apikey",
  "apiKey": "env:SN_API_KEY",
  "apiKeyHeader": "x-sn-apikey"
}

Básica (padrão, obsoleta no ServiceNow)

{
  "instance": "https://mydev.service-now.com",
  "username": "admin",
  "credential": "env:SN_PASSWORD_DEV"
}

Em um 401, o erro explica o programa de restrição de autenticação básica (KB3096078) e como migrar para OAuth.

Timeouts e novas tentativas

Toda solicitação é limitada por um timeout (padrão de 30s; por perfil timeoutMs ou env SN_TIMEOUT_MS) e repetida até duas vezes com backoff exponencial em 429/502/503/504, respeitando Retry-After. Solicitações POST são repetidas apenas em 429 — nunca após um 5xx que possa ter executado efeitos colaterais.

O ServiceNow upstream pode retornar HTTP 429 com corpo vazio, enquanto as rejeições de limite de taxa HTTP deste servidor retornam um corpo JSON curto além de Retry-After. Trate o status e o cabeçalho Retry-After como autoritativos; não avalie nem valide o sucesso da ferramenta apenas pela latência ou formato do corpo. Em instâncias normais do ServiceNow, planeje em torno do padrão de throttling em Background de aproximadamente 120 solicitações por 60 segundos por identidade, a menos que o limite da instância seja explicitamente elevado.

Por que este MCP Server?

A maioria das integrações MCP do ServiceNow é somente leitura e suporta um punhado de tabelas. Este serviço oferece um catálogo de ferramentas mais amplo por trás de uma política explícita de tabelas e ferramentas com negação por padrão:

Recurso	Outros	@onlyflows/servicenow-mcp
Consultar registros	✅	✅
Criar registros	❌	✅
Atualizar registros	❌	✅
Excluir registros	❌	✅ (com confirmação de segurança)
Operações em lote	❌	✅ (dry-run por padrão)
Agregações (COUNT/AVG/MIN/MAX/SUM)	❌	✅
Introspecção de esquema de tabela	❌	✅
Travessia de relacionamento CMDB	❌	✅ (recursiva, profundidade configurável)
Monitoramento de saúde da instância	❌	✅ (versão, nós, jobs, estatísticas)
Gerenciamento de anexos	❌	✅ (listar, enviar, baixar; base64 inline, sem sistema de arquivos do host)
Consultas de logs do sistema	❌	✅
Busca de código em artefatos	❌	✅
Descoberta de tabelas/apps/plugins	❌	✅
Execução de testes ATF	❌	🚧 listagem/resultados disponíveis; execução atualmente negada por política
Interface em linguagem natural	❌	🚧 atualmente negada por política, aguardando um plano de acesso tipado
Scripts em background	❌	🚧 no roadmap (SNS-39)
Perfis multi-instância	❌	✅ (perfis nomeados, override por chamada)
Total de ferramentas	1–3	19

Início Rápido

O servidor fala stdio e requer Node.js 20 ou mais recente. O caminho mais curto é o bootstrap descrito em Instalação:

servicenow-mcp-setup

Isso registra seus clientes; cada um inicia o servidor quando necessário.

O restante desta seção é o caminho manual de ambiente, para uma implantação que injeta tudo a partir de um supervisor ou gerenciador de segredos, ou para operar o servidor manualmente por um pipe.

Use .env.example apenas como um inventário de configuração não secreto. Suas atribuições de valores protegidos são intencionalmente vazias; injete segredos do ServiceNow por meio de um supervisor, orquestrador, keychain ou gerenciador de segredos, em vez de preencher um arquivo dotenv do repositório.

As variáveis SN_ALLOWED_* e SN_PROFILE_NAME abaixo constroem um perfil apenas quando ~/.servicenow-mcp/config.json não existe. Com um arquivo de perfil presente, coloque as regras no perfil com servicenow-mcp-setup grant.

export MCP_OWNER_ID="your-owner-id"
export MCP_CLIENT_ID="your-client-id"
export SN_ALLOWED_READ_TABLES="incident,problem,change_request"
export SN_ALLOWED_WRITE_TABLES="incident,change_request"
export SN_TABLE_ACCESS_TARGETS='[{"table":"incident","kind":"canonical","tools":["sn_query","sn_get","sn_create","sn_update","sn_incident_add_comment","sn_incident_add_work_note","sn_delete","sn_batch"],"closureComplete":true,"relatedTables":["incident"]},{"table":"problem","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["problem"]},{"table":"change_request","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["change_request"]}]'
export SN_PROFILE_NAME="dev"
export SN_INSTANCE="https://yourinstance.service-now.com"
export SN_USER="your_username"
npm run build
npm start

Antes de executar esses comandos não secretos, o mecanismo aprovado de segredos em tempo de execução já deve ter injetado o segredo específico de autenticação do ServiceNow no processo. Não o insira neste bloco de shell.

Um cliente se conecta iniciando o comando; não há URL nem cabeçalho:

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

Mensagens JSON-RPC trafegam no stdin e stdout do processo filho, uma mensagem delimitada por nova linha por quadro. Todo o resto que o servidor reporta — avisos de inicialização e um evento estruturado em linha JSON por chamada de ferramenta concluída — vai para stderr, que seu cliente captura como log do servidor. Não há limite de tamanho por mensagem imposto pelo transporte.

Para exemplos completos do SDK oficial e de clientes independentes, configuração segura de dois perfis e verificações cruzadas de perfil/resultado/auditoria, consulte Configuração do serviço e cliente V2.

Mudanças que quebram compatibilidade na 2.0

Toda chamada de ferramenta deve nomear um profile, e o acesso a tabelas é negado por padrão. Essas duas exigem ação em toda instalação. O transporte é stdio, como era em 1.0.0, então um cliente configurado com uma entrada command continua funcionando.

As mudanças que quebram compatibilidade desde 1.0.0, cada uma com exemplo antes/depois, estão em Migrando para 2.0.

Guias de implantação para o transporte HTTP dormente

A 2.0 inclui apenas stdio. A imagem de contêiner, o contrato de saúde e encerramento, o runbook de operações e o adaptador Secure MCP Tunnel descrevem o transporte HTTP dormente, que nenhum caminho de CLI alcança. Eles são mantidos porque esse transporte é um formato planejado de implantação empresarial, não porque se aplicam a uma instalação 2.0 — nada nesta seção é necessário para usar este servidor.

Implantação de contêiner de produção — artefato OCI, runtime não-root, proveniência e varredura
Runbook de operações remotas — interpretação de saúde, telemetria, alertas, rotação, resposta a incidentes
Conectividade ChatGPT privada — adaptador Secure MCP Tunnel somente de saída

Referência de Ferramentas

CRUD Principal

Ferramenta	Descrição
`sn_query`	Consultar uma tabela aprovada com filtros estruturados, seleção de campos, paginação e ordenação; leituras brutas limitadas exigem uma regra de política explícita
`sn_get`	Obter um único registro por sys_id de uma tabela aprovada
`sn_create`	Criar um registro em qualquer tabela concedida para escrita, usando apenas campos graváveis aprovados pela política de campos; `incident` adicionalmente exige um `short_description` limitado
`sn_update`	Atualizar um registro selecionado por `sys_id` exato em qualquer tabela concedida para escrita, usando apenas campos graváveis aprovados pela política de campos; rejeita `comments` e `work_notes` com orientação de migração de ferramenta dedicada
`sn_incident_add_comment`	Acrescentar um comentário limitado visível ao cliente em um incidente; chamadas repetidas acrescentam novamente
`sn_incident_add_work_note`	Acrescentar uma nota de trabalho interna limitada a um incidente; chamadas repetidas acrescentam novamente
`sn_delete`	Excluir um registro em uma tabela de escrita aprovada (exige `confirm: true`)
`sn_batch`	Atualização/exclusão em lote usando um filtro estruturado obrigatório e segurança dry-run (seletores brutos codificados são proibidos; exige `confirm: true` para executar)

Análise e Esquema

Ferramenta	Descrição
`sn_aggregate`	COUNT, AVG, MIN, MAX, SUM com agrupamento
`sn_schema`	Definições de campos de tabela, tipos, referências
`sn_health`	Versão da instância, nós do cluster, jobs travados, estatísticas principais

CMDB e Operações

Ferramenta	Descrição
`sn_relationships`	Travessia de grafo CI CMDB — upstream/downstream/ambos, profundidade configurável
`sn_attach`	Listar anexos, retornar downloads como base64 inline e enviar conteúdo base64 inline; nunca toca em um caminho do sistema de arquivos do host
`sn_syslog`	Consultar logs do sistema com filtros de severidade/origem/tempo
`sn_codesearch`	Buscar regras de negócio, script includes, scripts de cliente, etc.
`sn_discover`	Descobrir tabelas, apps com escopo, apps da loja, plugins

Testes e Automação

Ferramenta	Descrição
`sn_atf`	Listar testes/suítes ATF e obter resultados; `run`/`run-suite` atualmente falham fechados
`sn_nl`	Atualmente falha fechado até que a composição em linguagem natural emita um plano de acesso tipado completo

sn_script (execução de script em background) foi lançado na 1.0.0 como um stub não implementado e não é publicado na 2.0 — não aparece em tools/list. Use sn_query e sn_batch em vez disso. Veja Roadmap.

Gerenciamento de Perfis

Ferramenta	Descrição
`sn_profile`	Inspecionar metadados não secretos de um perfil explicitamente nomeado; a configuração do perfil é gerenciada pelo operador fora de banda

Variáveis de Ambiente

Runtime MCP

Variável	Obrigatória	Padrão	Descrição
`MCP_OWNER_ID`	❌	`local-owner`	Identificador estável não secreto do proprietário registrado no contexto de solicitação/ferramenta e em todo registro de auditoria. Um rótulo, não uma credencial; nunca é verificado.
`MCP_CLIENT_ID`	❌	`local-client`	Identificador estável não secreto do cliente registrado no contexto de solicitação/ferramenta e em todo registro de auditoria. Um rótulo, não uma credencial; nunca é verificado.

Essa é a lista completa. Não há endereço de bind, porta, lista de permissões Host/Origin, limite de concorrência, limite de conexões, período de graça de encerramento, token bearer ou limite de taxa, porque não há listener: um cliente inicia o servidor e controla seu ciclo de vida.

O servidor lê essas variáveis do seu ambiente e recorre a ~/.servicenow-mcp/server.env para qualquer uma que não encontrar lá. Esse arquivo é somente do proprietário (modo 0600) e é onde servicenow-mcp-setup grava os identificadores gerados e SN_PROFILE_ENCRYPTION_KEY. Ele existe porque o cliente que inicia o servidor fornece seu próprio ambiente e não terá obtido nada. Um valor já presente no ambiente sempre vence, então um contêiner ou runner de CI que passa configuração diretamente não é afetado. servicenow-mcp-setup doctor reporta o modo e o conteúdo desse arquivo.

Observabilidade

Cada chamada de ferramenta concluída emite um evento em linha JSON para stderr, que o cliente que inicia captura como log do servidor:

{"schemaVersion":1,"type":"mcp_tool","observedAtMs":1737000000000,"latencyMs":42,
 "correlationId":"stdio-<session>-<invocation>","ownerIdHash":"sha256:...",
 "clientIdHash":"sha256:...","tool":"sn_query","profile":"dev",
 "instance":"https://dev00001.service-now.com","outcome":"success","reason":null,
 "errorCategory":null,"retry":null,"retryAfterSeconds":null}

As auditorias de ferramentas classificam cancelamento de solicitação e expiração de prazo de solicitação separadamente de falhas de handler. Identificadores configurados de proprietário/cliente são representados apenas por pseudônimos SHA-256; cabeçalhos, URLs/strings de consulta, corpos, credenciais, tokens, objetos de configuração e texto de exceção não são campos de evento. A telemetria nunca bloqueia um resultado de ferramenta: o backpressure do stderr retém no máximo 256 linhas pendentes, descarta eventos excedentes e emite um resumo {"type":"telemetry_dropped","count":N} após o fluxo drenar.

Um ID de correlação é stdio-<session>-<invocation>. A metade da sessão é fixa pela vida de um servidor iniciado, então todos os registros de uma sessão de cliente se agrupam; a metade da invocação é nova por chamada. Nenhuma metade é derivada de nada que o chamador enviou.

stdout carrega o protocolo e nada mais. Todo diagnóstico vai para stderr. Um único byte perdido no stdout dessincronizaria o parser JSON-RPC do cliente e encerraria a sessão, então não existe algo como um console.log inofensivo no caminho de inicialização ou solicitação; test/stdio-entrypoint.test.ts inicia um servidor real e o verifica.

Argumentos que falham no esquema de uma ferramenta são rejeitados pelo SDK MCP antes de qualquer handler rodar, então retornam um erro ao chamador, mas produzem nenhum evento de auditoria — o contexto de execução que emitiria um nunca é aberto. Toda chamada que alcança uma ferramenta é auditada.

Tamanho do corpo e concorrência (somente runtime HTTP dormente)

Nada disso se aplica ao servidor enviado. Descreve o runtime HTTP dormente, que nenhum caminho de CLI alcança — veja o limite de lançamento empresarial — e se aplica apenas a alguém que embute este pacote e chama createHttpRuntime diretamente. Via stdio não há limite de corpo de solicitação nem teto de admissão.

O tamanho do corpo da solicitação e a concorrência trocam diretamente entre si sob o teto de admissão de 512 MiB:

`maxBodyBytes`	Maior concorrência que inicia	Efeito
1 MiB (padrão enviado)	2	416 MiB orçados; a configuração pretendida
1.75 MiB	2	512 MiB — exatamente no teto
2 MiB	1	Single-flight: toda chamada de ferramenta serializa
5.75 MiB	1	o último valor que inicia de qualquer forma
acima de 5.75 MiB	nenhum	a inicialização falha em qualquer concorrência

Dois modos de falha valem a pena conhecer:

A partir de 2 MiB, o servidor opera em modo single-flight. Concorrência 2 não é mais suportada, então o runtime só pode iniciar com 1 e cada chamada de ferramenta fica na fila atrás de todas as outras. Não há aviso nem linha de log — isso se apresenta como "o servidor ficou lento", e um upload grande bloqueia todas as outras ferramentas durante sua execução. Nada conecta a causa ao efeito.
Acima de 5,75 MiB, o servidor se recusa a iniciar. Um construtor throw, não um limitador. A mensagem menciona maxConcurrentRequests e maxBodyBytes, mas não informa nem o teto, nem a aritmética, nem um valor funcional; a tabela acima é o caminho a seguir.

maxBodyBytes não é configurável pelo operador. src/http-entrypoint.ts constrói a política de requisição apenas com allowedHosts e allowedOrigins, então o limite é sempre 1 MiB e nenhuma variável de ambiente o altera.

Cache de metadados

Leituras estáveis de metadados do ServiceNow são armazenadas em cache por instância e identidade de credencial por 24 horas por padrão. Os padrões de tabela em cache padrão são sys_glide_object, sys_dictionary, sys_db_object, sys_app, sys_plugins, sys_metadata* e sys_flow*. Defina metadataCache.ttlMs e metadataCache.tables em um perfil baseado em arquivo, ou SN_METADATA_CACHE_TTL_MS / SN_METADATA_CACHE_TABLES para o perfil de ambiente explícito. sn_query, sn_get e sn_schema aceitam force_recache: true para atualizar metadados. Uma ocorrência de cache realiza uma sondagem leve de sys_updated_on e é usada somente quando nenhuma linha de metadados correspondente mudou desde a sincronização anterior.

Pré-requisito: um fuso horário de sessão resolvível. A sondagem de atualização compara sys_updated_on, que o ServiceNow avalia no fuso horário do usuário da sessão, não em UTC. Resolver esse fuso exige que o user_name da conta autenticada consulte sys_user.time_zone, com fallback para a propriedade glide.sys.default.tz. Quando não pode ser resolvido, o cache se desativa para essa identidade em vez de assumir UTC — uma suposição errada serviria silenciosamente metadados obsoletos pela duração do deslocamento. O servidor registra um aviso nomeando as leituras que precisa.

Isso tem uma consequência que vale a pena conhecer antes de configurar:

Autenticação do perfil	Cache de metadados
Básica	funciona — o perfil carrega um nome de usuário
Concessão de senha OAuth	funciona — o perfil carrega um nome de usuário
OAuth client_credentials	desativado — sem nome de usuário para resolver um fuso horário
Chave de API	desativado — sem nome de usuário para resolver um fuso horário

O perfil também precisa de acesso de leitura a sys_user (para time_zone) e sys_properties (para glide.sys.default.tz) para que a consulta tenha sucesso.

A compensação honesta: o cache só economizou bytes de payload, nunca viagens de ida e volta — uma ocorrência de cache ainda custa uma sondagem de atualização. Então, em um perfil client-credentials ou chave de API, a perda prática é largura de banda em leituras de sys_dictionary, não latência. Se você está escolhendo um modo de autenticação, isso não deve ser o fator decisivo.

Exclusões tornam-se visíveis dentro de um TTL. A sondagem de atualização detecta atualizações, não exclusões, então uma linha excluída upstream continua sendo servida até que sua entrada expire e seja buscada novamente — até 24 horas no TTL padrão. Isso é um comportamento aceito, não um defeito; reduza SN_METADATA_CACHE_TTL_MS ou passe force_recache: true se precisar que uma exclusão seja refletida mais cedo.

Seleção de campos irrestrita (`fields=all`, `response_format=detailed`)

Ambos resolvem para uma seleção curinga. Eles anteriormente descartavam sysparm_fields inteiramente, então o ServiceNow retornava todas as colunas e uma tabela ampla poderia exceder o limite cumulativo upstream de 1 MiB e falhar a chamada completamente. Agora eles são limitados a no máximo 100 colunas.

O limite restringe a requisição upstream, não a resposta — truncar após o recebimento não ajudaria, porque os bytes já cruzaram o fio e já excederam o limite. As colunas são resolvidas de sys_dictionary, percorrendo super_class para que uma tabela estendida contribua com seus campos herdados. A ordenação é determinística: a projeção padrão curada da tabela primeiro em sua ordem declarada, depois cada coluna restante em ordem alfabética. Os padrões lideram para que um resultado limitado permaneça útil; alfabético depois porque a ordem das linhas do dicionário não é estável entre instâncias. Todo caminho de falha recai na projeção padrão limitada da tabela, nunca no descarte de sysparm_fields.

sn_query relata truncamento através de seu campo hint. sn_get carregará o mesmo aviso em breve.

Duas mudanças de comportamento que valem a pena declarar claramente, porque mudam o que um chamador recebe de volta:

Campos de diário agora são retornados. comments e work_notes são incluídos no conjunto resolvido para fields=all e detailed. Veja Conteúdo de diário e seleção de campos.
Nomes de campos com aparência sensível são excluídos do conjunto resolvido inteiramente. Um nome que corresponde ao padrão de campo sensível nunca é solicitado, em vez de ser solicitado e limpo na chegada. Sob o comportamento curinga antigo, o valor cruzava o fio e era então removido; nomeá-lo em sysparm_fields o teria puxado deliberadamente, o que é pior.

Conteúdo de diário e seleção de campos

O conteúdo de diário em incident — comments (visível ao cliente) e work_notes (interno) — é legível através de fields=all, response_format: "detailed", um fields=comments explícito e sn_schema. A projeção padrão ainda o exclui, então um sn_query ou sn_get comum não o retorna.

Declarado como um fato em vez de um aviso: o conteúdo de diário em instâncias reais rotineiramente contém PII do cliente, então pedir todos os campos em incident retorna comentários visíveis ao cliente junto com todo o resto. Operadores que concedem leituras de incident a um agente devem saber disso. Se isso não for desejado, conceda uma leitura mais restrita via política de campos em vez de confiar na projeção padrão, já que o chamador escolhe fields.

Payloads de anexos

sn_attach nunca lê ou escreve em caminhos do sistema de arquivos do host. Uploads usam um file_name folha seguro mais content_base64; downloads retornam content_base64, file_name, content_type e size_bytes. O download também exige o table proprietário e o registro sys_id, que são autorizados por política e verificados contra os metadados do anexo antes que qualquer byte seja retornado.

Limite de tamanho: 10 MiB decodificados, e esse é o único. O transporte stdio enquadra mensagens por nova linha sem limite de tamanho, então os próprios limites da ferramenta são os que se aplicam — 10 MiB de bytes decodificados para um upload, e um orçamento bruto separado de 10 MiB para um download. A descrição do esquema content_base64 da ferramenta carrega o valor autoritativo.

O teto prático de ~760 KiB documentado antes da 2.1 veio do limite do corpo HTTP, que não se aplica mais: o cliente e o servidor compartilham um pipe, não um envelope. O Base64 ainda infla um arquivo em cerca de um terço na própria mensagem, então um anexo de 10 MiB é aproximadamente um quadro JSON de 13,3 MiB — grande, mas o transporte o carregará.

Trate sn_attach como adequado para logs, configurações, capturas de tela e documentos em vez de transferência em massa; um quadro muito grande ainda custa memória tanto no cliente quanto no servidor, e a própria UI do ServiceNow ou uma integração dedicada é um caminho melhor para movimento de arquivos em massa.

Política de acesso a tabelas

A 2.0 nega todas as tabelas do ServiceNow por padrão. O acesso a tabelas é selecionado por perfil, não de um padrão implícito em todo o processo. Perfis baseados em arquivo definem tableAccess em ~/.servicenow-mcp/config.json; o perfil de ambiente explícito SN_PROFILE_NAME mapeia as variáveis SN_ALLOWED_* para esse único perfil somente quando nenhum arquivo de perfil existe. Se um perfil não tem regras de tabela, ele nega tudo.

Escreva as regras com a CLI em vez de manualmente — ela valida o resultado com o mesmo carregador que o servidor usa no momento da requisição:

servicenow-mcp-setup grant --profile dev --read incident,problem --write incident
servicenow-mcp-setup grant --profile dev --read cmdb_ci --tools sn_query,sn_relationships
servicenow-mcp-setup grant --profile dev --read change_request --related change_request=task

Entradas de allowlist podem ser nomes de tabela exatos ou o literal * para permitir todas as tabelas para essa operação. Nomes de tabela são aparados, convertidos para minúsculas, deduplicados e devem ser identificadores válidos do ServiceNow.

tableAccess é a única autoridade em nível de tabela. Não há mais uma lista embutida de tabelas que o servidor recusa incondicionalmente. Um perfil que concede uma tabela a obtém, sujeito apenas às ACLs por usuário do próprio ServiceNow — então uma concessão de sys_script, sys_user_role ou uma tabela de credenciais é honrada. Escrever sys_script é execução de script no lado do servidor sob a conta de integração. O privilégio mínimo agora vive inteiramente na concessão e nos papéis que você dá a essa conta; conceda o conjunto mais restrito que faz o trabalho e prefira uma conta cujos papéis do ServiceNow não possam alcançar o que a concessão não precisa.

Variável	Obrigatória	Padrão	Descrição
`SN_ALLOWED_READ_TABLES`	❌	negar tudo	Tabelas permitidas para operações de leitura no perfil de ambiente explícito `SN_PROFILE_NAME` somente. Use `*` para permitir todas as tabelas legíveis.
`SN_ALLOWED_WRITE_TABLES`	❌	negar tudo	Tabelas permitidas para criar, atualizar, anexar diário de incidente, excluir, enviar e operações em lote confirmadas no perfil de ambiente explícito `SN_PROFILE_NAME` somente. Use `*` para permitir todas as tabelas graváveis. Permissão de escrita nunca implica permissão de leitura.
`SN_TABLE_ACCESS_TARGETS`	Obrigatória para tabelas exatas na allowlist endereçáveis pelo chamador; opcional com `*`	`[]`	Classificação JSON confiável com `table`, `tools` exatos permitidos, `kind` (`canonical`, `alias`, `view` ou `extension`), literal `closureComplete: true` e o fechamento completo de `relatedTables` de suporte/ancestral/descendente. Com `*`, entradas de destino omitidas usam a concessão de operação curinga; entradas de destino explícitas ainda podem restringir ferramentas e validar o fechamento de tabelas relacionadas.
`SN_FIELD_POLICY_DEFINITIONS`	Obrigatória para campos de tabela personalizados/genéricos	política finita embutida	Objeto JSON confiável chaveado por nome de tabela ou ``. Cada entrada pode definir `defaults`, `readable` e `writable`; `readable`/`writable` aceitam arrays de campos exatos ou `""`. Nomes de campos sensíveis ainda são negados. Use `{"":{"defaults":["sys_id"],"readable":"","writable":[]}}` para exploração ampla somente leitura de tabelas personalizadas. Use `writable:"*"` somente para acesso intencional amplo de mutação.
`SN_ENCODED_QUERY_READ_POLICY`	❌	negar tudo	Objeto JSON confiável contendo `rules` limitados para um par exato de `sn_query`/tabela. Cada regra exige `maxLength`, `maxTerms`, `fields` legíveis, `operators` suportados, `maxLimit`, `maxOffset` e `maxResponseBytes`. Nenhuma regra pode autorizar uma escrita ou outra ferramenta.

Configuração de política inválida falha na inicialização. Uma ferramenta composta é admitida somente quando seu plano completo de tabelas de suporte é permitido antes do primeiro acesso ao cliente do ServiceNow. Cada destino relacionado deve ter a mesma permissão de leitura ou escrita, então uma tabela base, alias, visão ou extensão não pode contornar uma tabela de suporte ou descendente não listada. Permissão relacionada não torna uma dependência diretamente endereçável pelo chamador sem sua própria entrada de destino. A política de campos restringe o que uma tabela concedida expõe; ela não nega uma tabela que o operador concedeu. Nomes de campos com aparência sensível permanecem excluídos independentemente. Construa o catálogo completo de destinos a partir de metadados aprovados do ServiceNow e trate-o como configuração de inicialização confiável; omita um destino quando a alcançabilidade não puder ser comprovada como completa. Exemplo de perfil baseado em arquivo:

{
  "version": 2,
  "profiles": {
    "dev": {
      "instance": "https://dev.service-now.com",
      "username": "integration.user",
      "credential": "env:SN_PASSWORD",
      "tableAccess": {
        "readTables": ["incident", "sys_dictionary"],
        "writeTables": ["incident"],
        "targets": [
          {
            "table": "incident",
            "kind": "canonical",
            "tools": ["sn_query", "sn_get", "sn_create", "sn_update"],
            "closureComplete": true,
            "relatedTables": ["incident"]
          }
        ]
      }
    }
  }
}

sn_nl e ATF run/run-suite atualmente falham de forma fechada porque não emitem um plano completo de efeitos colaterais tipado; use a ferramenta tipada correspondente. Os campos de diário de incidentes são somente de acréscimo: o sn_update genérico rejeita comments e work_notes antes das credenciais ou da criação do cliente. Use sn_incident_add_comment ou sn_incident_add_work_note com exatamente profile, incidente sys_id e content limitado; conceda à ferramenta selecionada explicitamente no destino incident, bem como acesso de escrita a essa tabela.

Perfis do ServiceNow

Nota: Um arquivo de perfil é autoritativo quando presente. Sem um, SN_PROFILE_NAME deve mapear explicitamente as variáveis de conexão canônicas para um perfil nomeado; não há perfil sintético ou padrão.

Variável	Obrigatória	Padrão	Descrição
`SN_PROFILE_NAME`	✅*	—	Nome explícito para o perfil de ambiente local do processo; obrigatório antes que variáveis de conexão simples definam qualquer perfil.
`SN_INSTANCE`	✅*	—	URL da instância (ex.: `https://yourinstance.service-now.com`)
`SN_USER`	✅*	—	Nome de usuário do ServiceNow (autenticação básica / concessão de senha OAuth)
`SN_PASSWORD`	✅*	—	Senha do ServiceNow (autenticação básica / concessão de senha OAuth)
`SN_AUTH_TYPE`	❌	`basic`	Esquema de autenticação: `basic`, `oauth` ou `apikey`
`SN_CLIENT_ID`	❌	—	ID do cliente OAuth (`SN_AUTH_TYPE=oauth`)
`SN_CLIENT_SECRET`	❌	—	Segredo do cliente OAuth (`SN_AUTH_TYPE=oauth`)
`SN_GRANT_TYPE`	❌	`client_credentials`	Concessão OAuth: `client_credentials` ou `password`
`SN_API_KEY`	❌	—	Chave de API (`SN_AUTH_TYPE=apikey`)
`SN_API_KEY_HEADER`	❌	`x-sn-apikey`	Cabeçalho no qual a chave de API é enviada
`SN_TIMEOUT_MS`	❌	`30000`	Tempo limite por solicitação em milissegundos
`SN_DISPLAY_VALUE`	❌	`true`	Modo padrão de exibição de valores (`true`, `false`, `all`)
`SN_REL_DEPTH`	❌	`3`	Profundidade padrão de travessia de relacionamentos CMDB

*SN_PROFILE_NAME e SN_INSTANCE não são obrigatórias ao usar ~/.servicenow-mcp/config.json. As variáveis específicas de autenticação dependem do tipo de autenticação selecionado.

Exemplos de Uso

Uma vez conectado, seu assistente de IA pode:

Consultar incidentes:

"Em dev, mostre-me todos os incidentes P1 atribuídos à equipe de Rede" (profile: "dev")

Criar um registro:

"Em staging, crie um incidente para o teste de VPN aprovado" (profile: "staging")

Agregar dados:

"Em prod, quantos incidentes estão agrupados por prioridade?" (profile: "prod")

Verificar integridade:

"Execute a verificação de integridade da instância dev" (profile: "dev")

Travessia CMDB:

"Em prod, mostre as dependências upstream para email-server-01" (profile: "prod")

Introspecção de esquema:

"Em dev, quais campos existem em change_request?" (profile: "dev")

Busca de código:

"Em dev, encontre regras de negócio que referenciam GlideRecord('incident')" (profile: "dev")

Testes ATF:

"Em staging, liste a suíte ATF aprovada" (profile: "staging")

Seleção explícita de perfil:

"Consulte incidentes em dev" (o cliente envia profile: "dev" nessa chamada)

O cliente deve traduzir cada exemplo em uma invocação de ferramenta contendo exatamente esse profile; nenhuma chamada anterior cria estado padrão, ativo ou de troca de perfil.

Recursos de Segurança

Este servidor foi projetado para uso em produção com múltiplas camadas de segurança:

Operações de exclusão exigem confirm: true explícito
Operações em lote executam em modo de simulação por padrão — mostram a contagem de correspondências sem fazer alterações
Operações em massa exigem confirm: true para sair do modo de simulação
Composição não classificada é negada — sn_nl e a execução de ATF não são executadas até que possam emitir planos completos de acesso tipado
Acesso a tabelas é negado por padrão com listas de permissões exatas independentes de leitura/escrita e negações não configuráveis de tabelas sensíveis
A entrada do usuário é neutralizada antes da interpolação em consultas codificadas (^ é removido dos valores de filtro — a sintaxe de consulta do ServiceNow não possui sequência de escape)

Desenvolvimento

Peça ao supervisor local aprovado ou ao chaveiro para injetar o segredo de autenticação do ServiceNow selecionado antes de iniciar o processo. Os comandos abaixo contêm apenas configuração não secreta; nunca acrescente ou anexe valores protegidos na linha de comando.

# Clone
git clone https://github.com/onlyflowstech/servicenow-mcp.git
cd servicenow-mcp

# Install & build
npm install
npm run build

# Run the server directly, speaking stdio on this terminal's pipes
MCP_OWNER_ID=local-owner \
MCP_CLIENT_ID=local-client \
SN_ALLOWED_READ_TABLES=incident,problem,change_request \
SN_ALLOWED_WRITE_TABLES=incident,change_request \
SN_TABLE_ACCESS_TARGETS='[{"table":"incident","kind":"canonical","tools":["sn_query","sn_get","sn_create","sn_update","sn_incident_add_comment","sn_incident_add_work_note","sn_delete","sn_batch"],"closureComplete":true,"relatedTables":["incident"]},{"table":"problem","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["problem"]},{"table":"change_request","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["change_request"]}]' \
SN_PROFILE_NAME=dev \
SN_INSTANCE=https://yourinstance.service-now.com \
SN_USER=your_user \
npm start

# Build and run with source maps for local development
MCP_OWNER_ID=local-owner \
MCP_CLIENT_ID=local-client \
SN_ALLOWED_READ_TABLES=incident,problem,change_request \
SN_ALLOWED_WRITE_TABLES=incident,change_request \
SN_TABLE_ACCESS_TARGETS='[{"table":"incident","kind":"canonical","tools":["sn_query","sn_get","sn_create","sn_update","sn_incident_add_comment","sn_incident_add_work_note","sn_delete","sn_batch"],"closureComplete":true,"relatedTables":["incident"]},{"table":"problem","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["problem"]},{"table":"change_request","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["change_request"]}]' \
SN_PROFILE_NAME=dev \
SN_INSTANCE=https://yourinstance.service-now.com \
SN_USER=your_user \
npm run dev

Testes com o MCP Inspector

Use o conjunto de ferramentas isolado e exatamente bloqueado do Inspector no Node.js 22.19 ou mais recente; o próprio servidor permanece suportado no Node.js 20. Defina o MCP_PROFILE não secreto, instale a partir de tools/inspector/package-lock.json e execute o iniciador somente local:

MCP_PROFILE=dev npm run inspector

(Execute npm ci --prefix tools/inspector --engine-strict --ignore-scripts primeiro.)

O iniciador imprime o comando e os argumentos exatos de STDIO para inserir na interface do Inspector. Não há endpoint nem token para digitar. Inclua o perfil explícito em cada chamada. O Inspector inicia o próprio servidor e herda um ambiente limpo com todos os valores de MCP_* e SN_* removidos; o servidor ainda resolve sua credencial, pois lê o ~/.servicenow-mcp/server.env somente do proprietário na inicialização, em vez de depender do que recebeu. O iniciador não expõe o Inspector além do loopback nem cria um túnel.

npm run smoke é o segundo cliente. Ele inicia o dist/index.js da mesma forma e precisa apenas de MCP_PROFILE:

MCP_PROFILE=dev npm run smoke

Consulte docs/RELEASE-VALIDATION.md para os portões de lançamento, confirmação de escrita, evidências e procedimento de reversão.

Roteiro

Transporte stdio — o cliente inicia o servidor; existe um runtime HTTP Streamable, mas está dormente
Suporte a autenticação OAuth 2.0 (concessões client_credentials + password, chaves de API)
Execução de script em segundo plano sn_script (SNS-39) — estado futuro, deliberadamente não incluído na versão 2.0; requer automação do endpoint de interface sys.scripts.do com autenticação de sessão
Streaming para grandes conjuntos de resultados
Cache para consultas de esquema e relacionamentos

Licença

Construído com ❤️ por OnlyFlows · @onlyflowstech