ServiceNow Knowledge MCP Server

Connect AI assistants to authoritative ServiceNow Knowledge content. Four focused, read-only tools for searching articles, browsing categories, retrieving canonical content, and downloading bounded attachments—available to any MCP client over Streamable HTTP.

Knowledge API · Category hierarchy · Entra ID · Azure APIM · Per-tool scopes · Streamable HTTP

What this does

This server gives MCP-compatible AI clients a narrow retrieval interface to ServiceNow Knowledge. It is designed for grounding an assistant with published enterprise content without granting generic table access or mutation capabilities.

• Deterministic and read-only: no create, update, or delete operations.

• Retrieval only: no answer generation, summarization, semantic reranking, vector search, OCR, or document parsing.

• Enterprise-friendly TLS: uses the operating-system trust store, including managed corporate root certificates.

• Bounded responses: limits search results, article content, attachment bytes, timeouts, and retries.

• Credential-safe logging: credentials, authorization headers, and article bodies are not logged.

• APIM trust boundary: APIM validates Entra ID tokens; the MCP server authenticates APIM, extracts the already-validated claims, and enforces a separate scope per tool.

Related MCP server: ServiceNow MCP Server

Quick start

1. Install from source

git clone https://github.com/Xingyuj/SnowMCP.git
cd SnowMCP
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Python 3.11 or newer is required.

2. Configure ServiceNow

cp .env.example .env

Set the ServiceNow instance URL and choose one outbound authentication method:

SERVICENOW_BASE_URL=https://your-instance.service-now.com

# Option A: static bearer token (takes precedence when configured)
SERVICENOW_ACCESS_TOKEN=

# Option B: OAuth client credentials
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET=your-client-secret
SERVICENOW_OAUTH_TOKEN_PATH=oauth_token.do
SERVICENOW_OAUTH_SCOPE=

Do not commit .env or expose access tokens and client secrets in logs or screenshots.

3. Start the server

The server uses Streamable HTTP:

servicenow-knowledge-mcp

The MCP endpoint is available at http://127.0.0.1:8080/mcp.

4. Verify

With the HTTP server running in another terminal:

python scripts/mcp_client.py list
python scripts/mcp_client.py categories
python scripts/mcp_client.py search "remote access" --limit 5

Configure an MCP client

Configure the client to connect to the deployed Streamable HTTP endpoint. A typical remote MCP configuration looks like this:

{
  "mcpServers": {
    "servicenow-knowledge": {
      "type": "http",
      "url": "https://your-mcp-host.example/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_ACCESS_TOKEN}"
      }
    }
  }
}

Exact field names and configuration file locations vary by client. In production, the client sends the Entra ID access token to APIM.

Available tools

Typical retrieval flow:

search_knowledge
      │
      ├── get_knowledge_article
      │         └── get_knowledge_attachment (when the selected article references one)
      │
      └── list_knowledge_categories (for discovery or filtering context)

search_knowledge preserves the order returned by ServiceNow and does not claim semantic, vector, AI, or UI-equivalent ranking behavior.

Architecture

flowchart TB
    Client[AI assistant / MCP client]
    Entra[Microsoft Entra ID]

    subgraph APIM[Azure API Management]
        direction LR
        Gateway[Streamable HTTP gateway]
        Validate[validate-azure-ad-token]
        Forward[Forward validated bearer token]

        Gateway --> Validate
        Validate --> Forward
    end

    subgraph FastMCP[FastMCP server]
        direction TB
        Transport[Streamable HTTP transport]
        Claims["Extract APIM-validated claims<br/>no JWT signature validation"]
        Scopes[Per-tool scope checks]
        Tools["Tool handlers<br/>search_knowledge<br/>list_knowledge_categories<br/>get_knowledge_article<br/>get_knowledge_attachment"]
        Resolver["Service resolver + shared state<br/>lazy initialization and reuse"]
        Service[KnowledgeService]
        API[ServiceNow Knowledge API Client]
        Lifecycle[FastMCP lifespan]

        Transport --> Claims
        Claims --> Scopes
        Scopes --> Tools
        Tools --> Resolver
        Resolver -->|resolve| Service
        Service --> API
        Lifecycle -.->|shutdown cleanup| API
    end

    subgraph DownstreamAuth[ServiceNow downstream authentication - choose one]
        direction LR
        ClientCredentials["Option 1 - current<br/>OAuth client credentials<br/>integration identity"]
        OBO["Option 2 - conditional<br/>Entra OBO exchange<br/>Token A → Entra → Token B<br/>delegated user identity"]
    end

    subgraph ServiceNow[ServiceNow]
        direction LR
        TokenEndpoint[OAuth token endpoint]
        OIDC["Third-party OIDC token validation<br/>issuer, JWKS, audience, and user mapping"]
        SN[Knowledge APIs]

        TokenEndpoint -->|ServiceNow-issued app token| SN
        OIDC -->|mapped end-user identity| SN
    end

    Client -->|request access token| Entra
    Entra -->|signed access token| Client
    Client -->|Bearer token| Gateway
    Entra -.->|issuer metadata and signing keys| Validate
    Forward -->|network-restricted backend route| Transport
    API --> ClientCredentials
    ClientCredentials -->|client ID and secret / HTTPS| TokenEndpoint
    API -.->|not implemented yet| OBO
    OBO -->|delegated bearer token / HTTPS| OIDC

The tool handlers call the service resolver rather than constructing dependencies for every request. On the first call, the resolver creates the outbound authenticator, ServiceNowKnowledgeApiClient, and KnowledgeService, then stores the owned instances in shared server state. Later calls reuse them, including the HTTP connection pool and cached OAuth token. When FastMCP shuts down, its lifespan hook closes the owned ServiceNow client and authenticator.

APIM validates the user token's signature, issuer, audience, and expiry. The MCP server deliberately does not repeat those cryptographic checks: it relies on the enforced APIM-only network boundary, decodes the forwarded validated token, and applies FastMCP per-tool scope checks. APIM_AUTH_ENABLED=false disables claims extraction and tool scope enforcement and is intended only for local development.

KnowledgeService owns request validation, configured limits, category pagination, and response construction. ServiceNowKnowledgeApiClient owns authentication headers, endpoint construction, field selection, TLS, bounded transient retries, upstream error mapping, and JSON normalization. The solid downstream path is implemented today. The dotted OBO path is a conditional design option, not current behavior.

Configuration

All supported settings and defaults are documented in .env.example. The most important groups are:

A configured static ServiceNow access token takes precedence over OAuth client credentials. When client credentials are used, the server obtains and caches the access token automatically.

The default Knowledge API path, field names, and query parameters are implementation assumptions. Validate them against the API version and customizations of the target ServiceNow instance before production deployment.

Authentication and authorization boundary

There are three distinct security boundaries:

1. MCP client → APIM: the client obtains an Entra ID access token. APIM must use validate-azure-ad-token to verify its signature, issuer, audience, and expiry.

2. APIM → MCP server: enforced network controls guarantee that only APIM can reach the backend. APIM forwards the validated bearer token, and the MCP server extracts oid/sub and scp/scope/roles without repeating signature validation.

3. This server → ServiceNow: choose either a ServiceNow integration identity or, only when the target ServiceNow instance supports it, a delegated end-user identity.

APIM must forward the original validated Authorization: Bearer ... header because the MCP server uses its claims for tool authorization. The APIM-only network restriction is a mandatory security control for this design; exposing the backend through another route would allow unvalidated claims to reach the MCP server.

ServiceNow downstream identity options

OBO does not mean forwarding Token A directly to ServiceNow. Token A is issued for the MCP API and must only be presented to that audience. The MCP server uses Token A as the assertion in the Entra OBO exchange and receives Token B for the ServiceNow audience.

The ServiceNow configuration is more specific than merely enabling OpenID Connect for interactive SSO. The ServiceNow team must configure inbound third-party OIDC token validation for the target Knowledge APIs and confirm that the instance/release accepts the Entra OBO access token. Current ServiceNow documentation describes third-party OIDC inbound API authentication, but its detailed setup primarily demonstrates an ID token in the Authorization header. Because Entra OBO returns an access token, compatibility must be proven with the target instance before selecting this option.

Until that validation and the OBO code path are complete, this server uses the integration-identity path. A configured static ServiceNow bearer token remains available operationally, but it has the same authorization limitation: it does not preserve the original MCP user's identity.

See APIM claims authorization and local testing for the APIM contract, scope mapping, and copy-ready calls.

Docker

docker build -t servicenow-knowledge-mcp .
docker run --env-file .env -p 8080:8080 servicenow-knowledge-mcp

The container runs as a non-root user and exposes the HTTP server on port 8080 by default.

Local client examples

python scripts/mcp_client.py list
python scripts/mcp_client.py categories
python scripts/mcp_client.py search "remote access" --limit 5
python scripts/mcp_client.py article ARTICLE_ID
python scripts/mcp_client.py attachment ARTICLE_ID ATTACHMENT_ID --output attachment.bin

The helper uses HTTP/JSON-RPC directly and does not require the FastMCP CLI. See the MCP client cheatsheet for authentication, diagnostics, copy-ready commands, and troubleshooting.

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

pytest
ruff format --check src tests
ruff check src tests
mypy src