FastMCP Server for ServiceNow Instances

The problem it solves. You want an AI client, Claude Code or any other MCP-capable client, to read and write ServiceNow data across several instances without building a separate integration per instance and without hosting anything. The answer here is deliberately small.

Facts at a glance

Placeholders used in this guide

flowchart TD
  subgraph LOCAL["Your machine"]
    direction TB
    CC["MCP client A
Claude Code · CLI or editor extension"]
    CW["MCP client B
second desktop MCP client"]
    CJ["Client A config
env block per server"]
    CI["Client B config
env placeholders per server"]
    UVA["uv run python server_single.py
one process per server"]
    UVB["uv run server_single.py
one process per server"]
    SA["Script A
<project-root>/mcp-server/server_single.py"]
    SB["Script B · local copy
~/<client-b-folder>/server_single.py"]
    CC --> CJ
    CJ --> UVA
    UVA --> SA
    CW --> CI
    CI --> UVB
    UVB --> SB
  end
  SA -- "HTTPS REST
/api/now/table/..." --> E1["Client A: one server per instance
e.g. <instance-a>, <instance-b>, <customer-a>"]
  SB -- "HTTPS REST" --> E2["Client B: one server per instance
same pattern"]
  classDef client fill:#e8f1ff,stroke:#3975c6,color:#132238;
  classDef cfg fill:#fff5dd,stroke:#9a6500,color:#5a3d00;
  classDef code fill:#f1eaff,stroke:#7b52b9,color:#2f1f4b;
  classDef inst fill:#e8f7f1,stroke:#157a5a,color:#103e31;
  class CC,CW client;
  class CJ,CI cfg;
  class UVA,UVB,SA,SB code;
  class E1,E2 inst;
    

Per-instance registration fan-out

flowchart TD
  SCRIPT["server_single.py
one file, 60 tool functions"]
  REG["Registered once per instance
same command, different env vars"]
  SCRIPT --> REG
  REG --> P1["Process 1
SN_INSTANCE=https://<instance-a>.service-now.com"]
  REG --> P2["Process 2
SN_INSTANCE=https://<instance-b>.service-now.com"]
  REG --> PN["Process N
SN_INSTANCE=https://<instance-n>.service-now.com"]
  P1 --> T1["Tools exposed as
mcp__servicenow-sn-<instance-a>__sn_*"]
  P2 --> T2["Tools exposed as
mcp__servicenow-sn-<instance-b>__sn_*"]
  PN --> TN["Tools exposed as
mcp__servicenow-sn-<instance-n>__sn_*"]
  classDef code fill:#f1eaff,stroke:#7b52b9,color:#2f1f4b;
  classDef proc fill:#e8f1ff,stroke:#3975c6,color:#132238;
  classDef tool fill:#e8f7f1,stroke:#157a5a,color:#103e31;
  class SCRIPT,REG code;
  class P1,P2,PN proc;
  class T1,T2,TN tool;
    

flowchart TD
  S0["0 · Prerequisites
Homebrew, uv, Python 3.13, Claude Code"] --> S1["1 · Create the project folder
pyproject.toml + server_single.py"]
  S1 --> S2["2 · Create the shared venv
uv sync with UV_PROJECT_ENVIRONMENT"]
  S2 --> S3["3 · Test the script by hand
with the three env variables"]
  S3 --> Q{"Prints the OK banner
and stays running?"}
  Q -- "No" --> T["Go to Troubleshooting"]
  Q -- "Yes" --> S4["4 · Register one server per instance
claude mcp add --scope user"]
  S4 --> S5["5 · Restart the client
tools appear as mcp__servicenow-sn-NAME__*"]
  S5 --> S6["6 · Prove it reaches the instance
query sys_user, limit 1"]
  S6 --> S7["7 · Optional: allow-list the read tools"]
  classDef a fill:#e8f1ff,stroke:#3975c6,color:#132238;
  classDef g fill:#e8f7f1,stroke:#157a5a,color:#103e31;
  classDef y fill:#fff5dd,stroke:#9a6500,color:#5a3d00;
  class S0,S1,S2,S3,S4,S5 a;
  class S6,S7 g;
  class Q,T y;
    

Step 1 · Create the project folder

Create the folder and put two files in it: server_single.py, whose structure section 8 describes, and pyproject.toml.

mkdir -p "<project-root>/mcp-server"
cd "<project-root>/mcp-server"

The whole of pyproject.toml:

[project]
name = "mcp-server"
version = "0.1.0"
description = "ServiceNow MCP server"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
  "mcp[cli]>=1.27.0",
  "python-dotenv>=1.2.2",
  "requests>=2.33.1",
]

Step 2 · Create the shared virtual environment

Point uv at one environment outside the project folder, then install the dependencies into it. All servers share this environment.

export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/mcp-server"
cd "<project-root>/mcp-server"
/opt/homebrew/bin/uv sync

Check the environment is real and the dependencies import:

~/.venvs/mcp-server/bin/python --version                            # prints Python 3.13.x
~/.venvs/mcp-server/bin/python -c "import mcp, requests, dotenv"     # prints nothing

Step 3 · Test the script by hand

Run it with the three environment variables set for one instance. This proves the script and its dependencies work before the AI client is involved.

cd "<project-root>/mcp-server"
SN_INSTANCE="https://<instance-a>.service-now.com" \
SN_USERNAME="<username>" \
SN_PASSWORD="<password>" \
UV_PROJECT_ENVIRONMENT="$HOME/.venvs/mcp-server" \
/opt/homebrew/bin/uv run python server_single.py

Step 4 · Register one server per instance

Use the Claude Code CLI at user scope so the servers are available in every project. Repeat for each instance, changing the server name, URL, username and password. The variable names stay the same for every instance, only the values change.

claude mcp add servicenow-sn-<instance-a> --scope user \
  -e SN_INSTANCE="https://<instance-a>.service-now.com" \
  -e SN_USERNAME="<username>" \
  -e SN_PASSWORD="<password>" \
  -e UV_PROJECT_ENVIRONMENT="$HOME/.venvs/mcp-server" \
  -- /opt/homebrew/bin/uv --directory "<project-root>/mcp-server" run python server_single.py

claude mcp add servicenow-sn-<instance-b> --scope user \
  -e SN_INSTANCE="https://<instance-b>.service-now.com" \
  -e SN_USERNAME="<username>" \
  -e SN_PASSWORD="<password>" \
  -e UV_PROJECT_ENVIRONMENT="$HOME/.venvs/mcp-server" \
  -- /opt/homebrew/bin/uv --directory "<project-root>/mcp-server" run python server_single.py

The result is stored in the Claude Code user config. One entry looks like this:

"servicenow-sn-<instance-a>": {
  "type": "stdio",
  "command": "/opt/homebrew/bin/uv",
  "args": [
    "--directory",
    "<project-root>/mcp-server",
    "run", "python", "server_single.py"
  ],
  "env": {
    "SN_INSTANCE": "https://<instance-a>.service-now.com",
    "SN_USERNAME": "<username>",
    "SN_PASSWORD": "<password>",
    "UV_PROJECT_ENVIRONMENT": "<home>/.venvs/mcp-server"
  }
}

Example server entries

Every server in ~/.claude.json is built this way. All of them use the same command, arguments and shared venv as step 4. Only the env values differ, as these examples show.

Step 5 · Restart the client and confirm the tools

Restart the editor window or the CLI session. Tools are named mcp__<server name>__<tool name>, for example mcp__servicenow-sn-<instance-a>__sn_query.

Step 6 · Prove it reaches the instance

Ask the client: "Using the <instance-a> server, query sys_user with limit 1." A returned record proves the whole chain: client, stdio, the script, HTTPS, Basic Auth, the instance.

Step 7 · Optional: avoid permission prompts for read tools

Add entries such as mcp__servicenow-sn-<instance-a>__sn_query to the permissions.allow list in ~/.claude/settings.json. Leave write and delete tools off the list so the client still asks first.

Client B is any second desktop MCP client that can launch a stdio server. The transferable part is the shape: its own copy of the script, its own virtual environment, and an integrations.json that stores the environment values as placeholders.

Step 1 · Create the Client B project folder

Client B runs its own copy. Create ~/<client-b-folder> and place server_single.py (Script B), pyproject.toml with the same dependencies, and .python-version containing 3.13 in it.

mkdir -p "$HOME/<client-b-folder>"
cd "$HOME/<client-b-folder>"
/opt/homebrew/bin/uv sync

Step 2 · Get Script B

Script B is Script A with the start-up code changed: no OAuth support, and it loads a .env from its own folder rather than using python-dotenv's default search. The easiest way to produce it is to copy Script A and apply the differences listed in section 13. Both copies expose the same 60 tool names.

Step 3 · Add one MCP server per instance in Client B

In the client application, add a stdio MCP server with this command, once per instance, with the three variables SN_INSTANCE, SN_USERNAME and SN_PASSWORD.

/opt/homebrew/bin/uv --directory ~/<client-b-folder> run server_single.py

Client B records each server in ~/Library/Application Support/<client-b>/integrations.json under mcp_servers. The env values are stored as placeholders of the form $MCP_ENV_<server-id>_SN_USERNAME, and the client substitutes the real value when it launches the process.

Step 4 · Confirm Client B started it

ps aux | grep <client-b-folder>

Script A and Script B side by side

flowchart TD
  A["Client starts the server process
with the env block from its config"] --> B["Environment now holds
SN_INSTANCE / SN_USERNAME / SN_PASSWORD"]
  B --> C["Script runs load_dotenv()"]
  C --> D{"Variable already set
in the environment?"}
  D -- "Yes" --> E["Environment value wins
.env is ignored for that variable"]
  D -- "No" --> F["Value is read from .env
if a .env file is found"]
  E --> G["os.getenv feeds ServiceNowClient"]
  F --> G
  G --> H{"Client id and secret
both set? Script A only"}
  H -- "Yes" --> I["OAuth password grant
POST /oauth_token.do"]
  H -- "No" --> J["Basic Auth
username and password"]
  classDef a fill:#e8f1ff,stroke:#3975c6,color:#132238;
  classDef g fill:#e8f7f1,stroke:#157a5a,color:#103e31;
  classDef y fill:#fff5dd,stroke:#9a6500,color:#5a3d00;
  class A,B,C,G a;
  class E,J g;
  class D,H,F,I y;
    

What this means in practice

• Both launchers pass the three variables in the process environment, so the project-folder .env is never consulted for them. python-dotenv does not override variables that are already set.
• The only .env in the project folder holds one instance and goes stale. It can be deleted without changing behaviour. Do not use it as the place to add new instances.
• The instance value may be a full URL such as https://<instance>.service-now.com, a bare name such as <instance>, which becomes the full URL, or a host name. The script normalises all three.
• Passwords are never written into the script. A search of Script A for hardcoded credentials and instance URLs found none.

sequenceDiagram
  autonumber
  actor U as You
  participant C as AI client
  participant S as server_single.py · FastMCP over stdio
  participant K as ServiceNowClient
  participant N as ServiceNow instance
  U->>C: Show me the last 5 failed flow logs
  C->>S: tools/call sn_query_flow_logs · JSON over stdin
  S->>K: table_get on sys_flow_log with query and limit
  K->>N: GET /api/now/table/sys_flow_log · Basic Auth · 30 s timeout
  N-->>K: 200 with a result array
  K-->>S: success true, plus the data payload
  S-->>C: JSON text string of records
  C-->>U: Summary written from the records
    

The pieces inside server_single.py

Three kinds of tool

Illustrative snippets

1. Reading the environment variables, which happens once, at import time:

import os
from dotenv import load_dotenv

load_dotenv()

# Basic Auth uses SN_INSTANCE / SN_USERNAME / SN_PASSWORD.
# For the optional OAuth password grant, also set SN_CLIENT_ID / SN_CLIENT_SECRET.
# When the client id and secret are both present, OAuth is used instead of Basic Auth.
client = ServiceNowClient(
    instance=os.getenv("SN_INSTANCE"),
    username=os.getenv("SN_USERNAME"),
    password=os.getenv("SN_PASSWORD"),
    client_id=os.getenv("SN_CLIENT_ID"),
    client_secret=os.getenv("SN_CLIENT_SECRET"),
)

mcp = FastMCP("servicenow-instance")
print("[OK] Connected", file=sys.stderr)

2. One representative tool definition and the helper almost every read tool calls:

@mcp.tool()
def sn_query(table: str, query: str = "", fields: str = "", limit: int = 20) -> str:
    """Query any table on the active instance."""
    return qh(table, query, fields, limit)


def qh(tbl: str, qry: str = "", flds: str = "", lmt: int = 20,
       ob: str = "-sys_created_on", dv: bool = True) -> str:
    """Quick helper for table queries."""
    fl = [f.strip() for f in flds.split(",")] if flds else None
    r = client.table_get(tbl, query=qry or None, fields=fl,
                         limit=min(lmt, 1000), order_by=ob,
                         display_value="true" if dv else "false")
    if r["success"]:
        return json.dumps({"count": len(r["data"].get("result", [])),
                           "records": r["data"].get("result", [])}, indent=2)
    return json.dumps({"error": r["error"]}, indent=2)

3. The Table API request helper:

def table_get(self, table: str, sys_id: str = None, query: str = None,
              fields: list = None, limit: int = 100, offset: int = 0,
              order_by: str = None, display_value: str = "false") -> dict:
    endpoint = (f"/api/now/table/{table}/{sys_id}" if sys_id
                else f"/api/now/table/{table}")
    params = {
        "sysparm_limit": limit,
        "sysparm_offset": offset,
        "sysparm_display_value": display_value,
        "sysparm_exclude_reference_link": "true",
    }
    if query:    params["sysparm_query"] = query
    if fields:   params["sysparm_fields"] = ",".join(fields)
    if order_by: params["sysparm_orderby"] = order_by
    return self._request("GET", endpoint, params=params)

4. The single _request method every verb funnels through, which is what produces the uniform response envelope:

def _request(self, method, endpoint, params=None, data=None) -> dict:
    url = f"{self.base_url}{endpoint}"
    try:
        response = self.session.request(method=method, url=url, params=params,
                                        json=data, timeout=self.timeout)
        return {
            "success": response.ok,
            "status_code": response.status_code,
            "data": response.json() if response.text else None,
            "error": None if response.ok
                     else f"HTTP {response.status_code}: {response.reason}",
        }
    except Exception as e:
        return {"success": False, "status_code": None, "data": None, "error": str(e)}

Every tool name starts with the same prefix on every instance. In the client, the full name adds a server prefix, for example mcp__servicenow-sn-<instance-b>__sn_query, and that server part is what tells you which instance answered.

Generic data access (8)

These work on any table. They are thin Table API wrappers.

Logs and diagnostics (9)

Read syslog, Flow Designer, generative AI logs and RAG index health.

AI agent inspection (15)

Read agents, tools, workers, triggers and execution history on the sn_aia_* tables.

AI agent authoring (19)

Create, change and delete agents, workflows, tools, triggers and parent-to-child mappings.

AI Worker management (8)

Create and change AI Workers and Worker Templates, and map users to workers.

RAG pipeline (1)

Build a complete RAG search pipeline and attach it to an agent. This one tool carries about 300 lines of logic.

Recommended changes

Platform baseline assumed here

• Both instances in this example run a recent Australia patch with the Model Context Protocol Server plugin (sn_mcp_server) and the client plugin (sn_mcp_client) installed.
• Each instance already had several provisioned MCP servers in sn_mcp_server_registry, for example sn_itsm_mcp_server.itsm_default, sn_hr_mcp_server.hr_default and sn_csm_mcp_server.csm_default.
• The Dev Program series this appendix follows assumes a recent Australia patch with the plugin installed, an OAuth Application Registry entry whose redirect URL is https://claude.ai/api/mcp/auth_callback, Token Format JWT and the useraccount scope. The authenticating user needs itil or an equivalent role on incident.

Which one to reach for

Source. This walkthrough follows the ServiceNow Dev Program series by Travis Toulson, namely Build MCP Tools in the MCP Server Console, Create the MCP Server Record in ServiceNow, Connect Claude to a ServiceNow MCP Server and Claude Reads and Updates a Real ServiceNow Incident, together with the written ServiceNow Community article Building an MCP Server on ServiceNow and Connecting Claude to It. Check the scripts below against the originals before using them on a customer instance.

flowchart TD
  U["You"] --> CL["AI client
custom connector"]
  CL -- "OAuth 2.0 consent
scope useraccount" --> OA["OAuth Application Registry
MCP connector entry, JWT tokens"]
  CL -- "HTTPS MCP calls
to the Server URL" --> MS["MCP Server record
Incident MCP Server"]
  MS --> T1["Tool: Get Incident"]
  MS --> T2["Tool: Update Incident"]
  T1 -- "GET /incident_api by number" --> API["Scripted REST API
incident_api"]
  T2 -- "POST /incident_api by number
validated by UpdateIncidentSchema" --> API
  API --> GR["GlideRecord on incident
runs as the consenting user"]
  classDef a fill:#e8f1ff,stroke:#3975c6,color:#132238;
  classDef b fill:#fff5dd,stroke:#9a6500,color:#5a3d00;
  classDef c fill:#f1eaff,stroke:#7b52b9,color:#2f1f4b;
  classDef d fill:#e8f7f1,stroke:#157a5a,color:#103e31;
  class U,CL a;
  class OA b;
  class MS,T1,T2 c;
  class API,GR d;
    

Step 1 · Check the instance and install the plugin

You need a recent Australia patch, the Now Assist Admin Console plugin (sn_nowassist_admin, listed as AI Admin Hub on newer instances) and the admin role. Install Model Context Protocol Server (sn_mcp_server) from All > System Applications > All Available Applications > All.

curl https://<instance>.service-now.com/sncapps/mcp-server/health

Step 2 · Create the Scripted REST API and the GET resource

Go to All > System Web Services > Scripted REST APIs. Create an API named Incident API with API ID incident_api and Default ACLs Scripted REST External Default. Add a resource Get Incident: method GET, relative path /{number}, the same default ACLs, with this script.

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
  var number = request.pathParams.number;
  if (!number) {
    response.setStatus(400);
    response.setBody({ message: "Incident number is required." });
    return;
  }
  var gr = new GlideRecord('incident');
  gr.addQuery('number', number);
  gr.query();
  if (gr.next()) {
    response.setStatus(200);
    response.setBody({
      sys_id: gr.getValue('sys_id'),
      number: gr.getValue('number'),
      short_description: gr.getValue('short_description'),
      description: gr.getValue('description'),
      state: gr.getValue('state'),
      urgency: gr.getValue('urgency'),
      priority: gr.getValue('priority'),
      assigned_to: gr.getDisplayValue('assigned_to'),
      assignment_group: gr.getDisplayValue('assignment_group'),
      opened_at: gr.getValue('opened_at'),
      caller_id: gr.getDisplayValue('caller_id')
    });
  } else {
    response.setStatus(404);
    response.setBody({ message: "Incident not found: " + number });
  }
})(request, response);

Step 3 · Add the POST resource and its OpenAPI schema

On the same API add a resource Update Incident: method POST, relative path /{number}, the same default ACLs, with this script.

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
  var number = request.pathParams.number;
  if (!number) {
    response.setStatus(400);
    response.setBody({ message: "Incident number is required." });
    return;
  }
  try {
    var params = request.body.data;
    var gr = new GlideRecord('incident');
    gr.addQuery('number', number);
    gr.query();
    if (!gr.next()) {
      response.setStatus(404);
      response.setBody({ message: "Incident not found: " + number });
      return;
    }
    for (var key in params) {
      if (params.hasOwnProperty(key)) {
        if (key === 'work_notes' || key === 'comments') {
          gr[key] = params[key];
        } else {
          gr.setValue(key, params[key]);
        }
      }
    }
    gr.update();
    response.setStatus(200);
    response.setBody({
      message: "Incident updated successfully.",
      number: gr.getValue('number'),
      sys_id: gr.getUniqueValue()
    });
  } catch (e) {
    response.setStatus(500);
    response.setBody({ message: "Error occurred: " + e.message });
  }
})(request, response);

In the API's Schemas related list create UpdateIncidentSchema, OpenAPI version 3.0.1, with this JSON, then link it to the POST resource through the Request Schema related list. This is what gives the tool its input fields.

{
  "type": "object",
  "description": "Fields to update on the incident. All fields are optional. Include only what you want to change.",
  "properties": {
    "short_description": { "type": "string", "description": "Brief summary of the incident.", "example": "User cannot log in to VPN" },
    "description": { "type": "string", "description": "Detailed description of the incident.", "example": "User reports being unable to connect to VPN since this morning." },
    "urgency": { "type": "string", "description": "Urgency code. 1=High, 2=Medium, 3=Low.", "example": "2" },
    "impact": { "type": "string", "description": "Impact code. 1=High, 2=Medium, 3=Low.", "example": "2" },
    "state": { "type": "string", "description": "Incident state code. 1=New, 2=In Progress, 6=Resolved, 7=Closed.", "example": "2" },
    "assignment_group": { "type": "string", "description": "sys_id or name of the group to assign the incident to.", "example": "Service Desk" },
    "assigned_to": { "type": "string", "description": "sys_id or username of the person to assign the incident to.", "example": "<username>" },
    "work_notes": { "type": "string", "description": "Internal notes to add to the incident work notes journal. Visible to agents only.", "example": "Investigated and escalated to network team." },
    "comments": { "type": "string", "description": "Customer-visible notes to add to the incident comments journal. Visible to the caller and agents.", "example": "We are investigating your issue and will update you shortly." }
  }
}

Step 4 · Register the OAuth client

Go to All > System OAuth > Application Registry and create a new entry. On the interceptor page choose [Deprecated UI] Create an OAuth API endpoint for external clients, which is still the right choice despite the label.

• Name: MCP connector entry
• Redirect URL: https://claude.ai/api/mcp/auth_callback, exactly, with no trailing slash
• Token Format: JWT, not the default Opaque
• Auth Scopes: add useraccount

Save, then copy the Client ID (<client-id>) and Client Secret (<client-secret>).

Step 5 · Create the two MCP tools

Go to All > Admin Center > MCP Server Console > Tools > Create Tool > REST API. In the endpoint search, type /x to filter to scoped endpoints.

• Select [GET] /x_snc_<scope>/incident_api/{number}. Label Get Incident. Description: Retrieves the details of a specific ServiceNow incident by incident number. Call this tool when the user wants to look up, check, or get information about a specific incident.
• Select [POST] /x_snc_<scope>/incident_api/{number}. Label Update Incident. Description: Updates fields on an existing ServiceNow incident by incident number. Call this tool when the user wants to change, modify, or update an incident. Pass only the fields you want to change along with the required incident number.

Step 6 · Create and activate the MCP server

In the console open Servers > Create Server. Label Incident MCP Server. Short description: Access and manage ServiceNow incidents by incident number. Use this server to retrieve incident details or update incident fields including urgency, state, assignment, and work notes. Click Add Tools, select both tools, then Create. Click Activate; if the button reads Deactivate it is already active.

Step 7 · Connect the AI client

In Claude.ai, go to the profile icon, then Settings > Connectors > Add > Add custom connector. Name it, for example ServiceNow Incident MCP. The Remote MCP Server URL is the Server URL, and the OAuth Client ID and Client Secret are the values from step 4. Click Add, then Connect. Sign in to ServiceNow and approve the consent screen for the connector with the useraccount scope.

Step 8 · Test a read and a write

Open a new chat with the connector enabled and use a test incident number.

Get the details of ServiceNow incident <incident-number>.

Update incident <incident-number>. Set urgency to High and add a work note
that says "Escalated to network team for investigation."

Appendix troubleshooting