Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ServiceNow Incidents MCP list open high-priority incidents"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor Python/FastMCP para consultar, criar e atualizar incidentes pela Table API do ServiceNow. Executa localmente via stdio, com uma instância e uma identidade por processo.
Requisitos: Python 3.12+ e uv.
uv sync --lockedCrie um .env na raiz usando .env.example como referência e preencha as credenciais.
O arquivo .env está ignorado pelo Git. Também é possível fornecer variáveis de ambiente,
que têm precedência sobre o arquivo. Execute a partir da raiz:
uv run --locked servicenow-mcp
# Alternativa:
uv run --locked python -m servicenow_mcpO processo aguarda mensagens MCP em stdin; não é um terminal interativo nem um servidor HTTP. O cliente MCP normalmente inicia e encerra esse processo. Logs usam stderr, reservando stdout para o protocolo. Não há banco de dados ou persistência local de incidentes.
Related MCP server: ServiceNow MCP Server
Variável | Uso |
| Origem HTTPS, por exemplo |
|
|
| Usuário de integração, obrigatório para Basic |
| Senha, obrigatória para Basic |
| Token de acesso já obtido, obrigatório para Bearer |
| Timeout por operação de rede, padrão 30; maior que 0 e até 300 |
Bearer não obtém nem renova tokens. Após substituir um token expirado na configuração,
reinicie o processo MCP. A conta precisa de acesso REST e das ACLs adequadas à tabela
incident e aos campos usados. Não existe uma lista universal de papéis para todas as
instâncias; confirme com o administrador no REST API Explorer.
TLS permanece validado. Redirecionamentos e proxies de ambiente são desabilitados. Esta versão usa conexão direta à instância; ambientes que exigem proxy ou CA corporativa precisam de configuração adicional no cliente HTTP.
Exemplo para clientes que aceitam mcpServers. Substitua os caminhos absolutos; use o
caminho de uv retornado por command -v uv quando o aplicativo não herdar seu PATH.
O .env é carregado do diretório informado em --directory.
{
"mcpServers": {
"servicenow": {
"command": "/caminho/absoluto/para/uv",
"args": [
"--directory", "/caminho/absoluto/mcp-server-servicenow",
"run", "--locked", "servicenow-mcp"
]
}
}
}Ferramenta | Argumentos |
|
|
|
|
|
|
|
|
|
|
identifier aceita sys_id hexadecimal de 32 caracteres ou número INC seguido de dígitos.
A busca por número é exata; antes de alterar, o servidor resolve o número para sys_id.
Números inexistentes ou ambíguos geram erro, sem escrita.
Exemplos de argumentos de chamadas MCP:
{"query": "active=true^priority=1^ORDERBYsys_id", "limit": 20, "offset": 0}{"identifier": "INC0010001", "fields": ["number", "short_description", "state", "description"]}{
"short_description": "VPN indisponível",
"fields": {"description": "Falha ao conectar à rede interna", "impact": "2", "urgency": "2"}
}{"identifier": "INC0010001", "fields": {"urgency": "1", "u_external_reference": "SUP-123"}}{"identifier": "INC0010001", "text": "Investigação em andamento.", "field": "work_notes"}Campos de escrita aceitam valores escalares JSON ou null, cuja interpretação é da API.
Referências, como caller_id, assigned_to e assignment_group, usam sys_id, não nomes.
Campos number e sys_* são protegidos. Não envie short_description também dentro de
fields ao criar. Campos desconhecidos, obrigatórios e personalizados são tratados pelas
regras da instância; confira a resposta, pois a plataforma pode ignorar campos não reconhecidos.
Campos omitidos não são enviados no PATCH. Estados não são traduzidos ou fixados pelo servidor.
Para resolver um incidente, envie em update_incident o state e os demais campos exigidos
pela sua instância. Campos de journal acrescentam entradas; a consulta do incidente não é
uma API de histórico completo de comentários. A visibilidade de comments e work_notes
depende da configuração local do ServiceNow.
As operações individuais retornam o objeto result da API, sem converter strings numéricas,
booleanos ou referências. São solicitados valores internos (sysparm_display_value=false)
e referências sem links. get_incident retorna os campos acessíveis por padrão; a listagem
seleciona sys_id, number, short_description, state, priority, assigned_to,
assignment_group e sys_updated_on. Use fields para mudar essa seleção.
{"records": [], "limit": 20, "offset": 0, "total": 45, "next_offset": 20}total vem de X-Total-Count; next_offset usa o link next ou o total informado.
As ACLs podem produzir páginas curtas ou vazias antes do fim. Sem metadados de paginação,
next_offset=null significa que a próxima página é desconhecida; o cliente pode consultar
explicitamente offset + limit. Não há busca automática de todas as páginas.
A consulta padrão ordena por sys_id; ao passar query, inclua ordenação para percorrer
resultados de forma previsível. Alterações concorrentes na tabela podem afetar a paginação.
query é uma encoded query nativa, não SQL. A API pode ignorar partes inválidas de filtros
conforme a configuração da instância. Valide filtros no REST API Explorer; esta ferramenta
não valida o dicionário de campos da instância e consultas não autorizam alterações em lote.
Erros MCP distinguem configuração, validação local, HTTP 400/401/403/404/409/422/429/5xx, timeout, falha de conexão e respostas inesperadas. Corpos de erro remotos, credenciais e conteúdo dos incidentes não são incluídos nos logs. Não há tentativas automáticas, inclusive para escritas: em caso de timeout, falha de conexão ou erro 5xx, consulte o incidente antes de repetir para evitar incidentes ou comentários duplicados.
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked pytest
uv buildO pacote está dividido em configuração, cliente HTTP, serviço de incidentes e registro MCP
em src/servicenow_mcp. Os testes usam transporte HTTP simulado e cliente FastMCP em memória;
o teste stdio inicia um subprocesso real e verifica descoberta e validação local sem acessar
uma instância. Não precisa de credenciais reais para executar os testes.
Validação real: configure uma instância de desenvolvimento, conecte o cliente MCP, consulte um incidente conhecido e crie/atualize um incidente de teste com as ferramentas. Essa etapa exige credenciais e autorização para os registros envolvidos; não é executada pela suíte.
Não inclui exclusões, anexos, outros módulos ServiceNow, transporte HTTP remoto ou renovação OAuth. Nenhuma configuração ou ACL é alterada na instância pelo projeto.
A referência consultada é da família Australia. O projeto usa /api/now/table/incident
(versão padrão da instância); compatibilidade com customizações deve ser verificada localmente.
Adiciona comentário (comments) ou nota interna (work_notes), com seleção obrigatória.
A visibilidade segue a configuração da instância. Repetir pode duplicar a entrada.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| field | Yes | ||
| identifier | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (non-idempotent, write), the description adds two behavioral warnings: 'visibilidade segue a configuração da instância' and 'repetir pode duplicar a entrada'. These explain the consequences of non-idempotency and the variable scope of visibility, giving the agent extra context for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, the first front-loads the action and the mandatory selection, the second adds relevant behavioral caveats. There is no fluff or duplicated information from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose and risk, but does not explicitly connect the tool to its sibling context (e.g., 'use the identifier returned by list_incidents'). Since an output schema exists, return values are not mandatory to explain, yet the missing parameter linkage makes agent execution harder than it should be.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description does distinguish the two values for 'field', but says nothing explicit about 'identifier' (likely incident ID) or 'text' (the comment content). The agent must infer these from the tool name, which is incomplete and potentially ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a concrete verb (Adiciona), the target (comentário or nota interna), and differentiates the two fields. The tool name and sibling context make it clear this is a write operation on an incident, not one of the incident lifecycle operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear the caller must select between 'comments' and 'work_notes', and implicitly that this is for adding to an existing incident. However, it does not explicitly contrast with sibling tools like update_incident or create_incident, nor does it state when to prefer this over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cria incidente; fields aceita description, impact, urgency, caller_id e campos u_*.
Referências devem usar sys_id. Campos extras obrigatórios dependem da instância. Não permite number ou sys_*. Não repita automaticamente após falha de comunicação.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| short_description | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false, destructiveHint=false), but the description adds valuable non-obvious behavior: the instruction to not retry automatically after communication failure, the instance-dependent required fields, and the field whitelist/blacklist. This goes beyond what the annotations state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, the first states the core action and accepted fields, the second adds reference and instance constraints, and the third covers disallowed fields and retry behavior. Zero filler, front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential context for a create tool: accepted field names, reference format, instance-dependent required fields, forbidden fields, and retry policy. The output schema (not shown in description) and the required short_description are captured in the schema, so nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 0% coverage for the fields property (it is open-ended), so the description must compensate. It does so by naming accepted fields (description, impact, urgency, caller_id, u_*) and rules (references must be sys_id, number and sys_* are disallowed). It omits mentioning that short_description is required, but that is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it creates an incident ('Cria incidente') and enumerates accepted fields (description, impact, urgency, caller_id, u_*) and disallowed ones (number, sys_*), making it clearly distinct from sibling tools like list_incidents, get_incident, update_incident, and add_incident_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage constraints: references must use sys_id, extra required fields depend on the instance, and it disallows number or sys_* fields. However, it does not explicitly tell the agent when to use this tool versus updating an existing incident, though that is easily inferable from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtém um incidente por sys_id ou número INC; fields limita os campos retornados.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| identifier | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond annotations: it specifies the two identifier formats (sys_id or INC number) and explains that the fields parameter restricts the returned attributes. This supplements the readOnlyHint and openWorldHint by describing what the tool accepts and how it filters output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that front-loads the verb and resource and integrates both parameters meaningfully. Every word earns its place, and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with an output schema available, the description covers the essential inputs and their semantics. It does not discuss error cases or pagination, but given the output schema and readOnlyHint, the description is sufficiently complete for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since the schema provides no parameter descriptions (0% coverage), the description compensates by explaining that 'identifier' is a sys_id or INC number and that 'fields' limits the returned fields. This gives the agent enough semantic understanding to fill the parameters correctly, though it doesn't enumerate possible field values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a single incident by sys_id or INC number, distinguishing it from sibling tools like list_incidents (list) and create/update/comment (mutation). The specific verb 'obtém' and resource 'incidente' make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a specific incident by identifier but does not explicitly tell agents when to prefer this over list_incidents or other siblings. It lacks direct guidance on alternatives or exclusion conditions, so agents must infer from the singular nature of the operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista incidentes com encoded query ServiceNow, campos e paginação explícita.
Exemplo de query: active=true^priority=1^ORDERBYsys_id. Páginas vazias podem ocorrer por ACL; use next_offset/total quando disponíveis.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| fields | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| limit | Yes | |
| total | No | |
| offset | Yes | |
| records | Yes | |
| next_offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true and destructiveHint=false. The description adds useful behavioral caveats not available in the annotations: empty pages can occur due to ACL, and the consumer should use next_offset/total when present. This is meaningful context beyond the structured annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main purpose and immediately provides a concrete query example plus an ACL/pagination caveat. Each sentence contributes meaning without lengthy filler, though it packs quite a bit into two short blocks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The 4 parameters are optional, annotations declare a read-only/open-world tool, and an output schema exists. The description covers the essential query format, edge-case behavior around ACL filtering, and pagination hints. This is relatively complete for a tool definition, although the offset/limit parameters are still somewhat underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for query by giving an encoded-query example and identifies fields and pagination as explicit components. However, the exact semantics of limit and offset, and how fields maps to parameter values, is only implied, so it does the job only partially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Lista incidentes' with ServiceNow encoded query, fields, and explicit pagination, which is a specific verb and resource. It clearly distinguishes from siblings like get_incident, create_incident, update_incident, and add_incident_comment because it is the only listing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose list_incidents over get_incident or the other sibling tools. The description provides operational details (query example, ACL empty-page behavior) but does not explain selection criteria or exclusion situations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Altera apenas os campos fornecidos via PATCH, incluindo campos personalizados.
Exige fields não vazio. Não permite number ou sys_*. Para resolução, envie state e os campos exigidos pela instância; não há conversão automática de nomes de estados.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | ||
| identifier | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover destructive and readiness profile, so the description usefully adds PATCH-only behavior, support for custom fields, forbidden fields, and the lack of automatic state-name conversion. These details go beyond the structured annotations and help agents avoid common mistakes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, stays on topic, and front-loads the important PATCH behavior before the more specialized resolution note. Each sentence adds value, though some shorthand like 'number or sys_*' could be more explicit for agents unfamiliar with the domain.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool with an output schema and destructive annotation, the description covers the most critical constraints and gives targeted state-resolution guidance. However, identifier semantics are missing, and there is no guidance on prerequisites or alternative tool selection, so it is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description has the full burden of explaining the two parameters. It explains that fields must be non-empty and restricts certain field names, but it never clarifies the identifier parameter, what string format is expected, or exactly which fields are allowed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific action: 'Altera apenas os campos fornecidos via PATCH' (changes only the fields provided via PATCH), including custom fields. This clearly distinguishes it from read-only siblings like get_incident and list_incidents, and from create_incident, though it does not explicitly name the alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage constraints: fields must not be empty, number and sys_* are not allowed, and resolution requires state plus instance-required fields. However, it does not explicitly explain when to choose this tool over create_incident or add_incident_comment, leaving some usage routing implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_incident_commentcreate_incidentget_incidentlist_incidentsupdate_incidentScored across 5 tools
Each tool targets a distinct action and resource: listing, fetching, creating, updating, and commenting on incidents. The add_incident_comment tool is clearly separated from update_incident by its specific purpose of adding comments or work notes.
Tool names consistently follow a verb_noun pattern: list_incidents, get_incident, create_incident, update_incident, add_incident_comment. The only mild deviation is the wider verb 'add' for comments, but it still fits the convention.
Five tools is well-scoped for a ServiceNow incidents server, covering the core incident workflow without unnecessary bloat. Each tool earns its place and the count is appropriate for the domain.
The server provides solid lifecycle coverage with list, get, create, update, and comment operations. Missing delete is acceptable for incident management, though there is no direct way to retrieve existing comments/work notes, which is a minor gap.
Manage incidents and on-call: list/create/update incidents, who is on call, on-call overrides.
Read incidents, services, teams, on-call schedules; acknowledge, resolve and note incidents.
Manage incident alerts, events, and workflows with custom automations
Read Spike.sh incidents, on-call, escalations and services; acknowledge, resolve, set priority.