# ServiceNow MCP Server on Azure Container Apps

This project hosts a Model Context Protocol (MCP) server that exposes ServiceNow ticket, knowledge base, and service catalog data over Streamable HTTP.

## Tools exposed

| MCP tool | Purpose |
| --- | --- |
| `servicenow_search_tickets` | Search `incident`, `problem`, `change_request`, `sc_request`, or `sc_task` records. |
| `servicenow_get_ticket` | Read one ticket by `sys_id`. |
| `servicenow_search_knowledge` | Search published `kb_knowledge` articles. |
| `servicenow_list_catalog_items` | Search active `sc_cat_item` catalog items. |
| `servicenow_get_catalog_item` | Read one catalog item by `sys_id`. |

## Local setup

1. Install dependencies:

   ```powershell
   npm install
   ```

2. Copy `.env.example` to `.env` and set your ServiceNow instance and credentials:

   ```powershell
   Copy-Item .env.example .env
   ```

3. Start the server:

   ```powershell
   npm run dev
   ```

4. The MCP endpoint is:

   ```text
   http://localhost:3000/mcp
   ```

## ServiceNow permissions

Use a dedicated ServiceNow integration account or OAuth app with least-privilege read access to:

- `incident`
- `problem`
- `change_request`
- `sc_request`
- `sc_task`
- `kb_knowledge`
- `sc_cat_item`

For production, prefer OAuth bearer tokens or a ServiceNow OAuth client flow over basic auth.

## Deploy to Azure Container Apps

Set these variables first:

```powershell
$RESOURCE_GROUP = "rg-servicenow-mcp"
$LOCATION = "centralindia"
$ACR_NAME = "acrsnowmcp$((Get-Random -Maximum 99999))"
$ENV_NAME = "cae-servicenow-mcp"
$APP_NAME = "servicenow-mcp"
$IMAGE_NAME = "servicenow-mcp-server:0.1.0"
$SERVICENOW_URL = "https://your-instance.service-now.com"
$SERVICENOW_USERNAME = "your-integration-user"
$SERVICENOW_PASSWORD = "your-password"
```

Create Azure resources and build the image:

```powershell
az group create --name $RESOURCE_GROUP --location $LOCATION
az acr create --resource-group $RESOURCE_GROUP --name $ACR_NAME --sku Basic --admin-enabled true
az acr build --registry $ACR_NAME --image $IMAGE_NAME .
az containerapp env create --name $ENV_NAME --resource-group $RESOURCE_GROUP --location $LOCATION
```

Deploy the container app:

```powershell
$ACR_LOGIN_SERVER = az acr show --name $ACR_NAME --query loginServer -o tsv
$ACR_USERNAME = az acr credential show --name $ACR_NAME --query username -o tsv
$ACR_PASSWORD = az acr credential show --name $ACR_NAME --query "passwords[0].value" -o tsv

az containerapp create `
  --name $APP_NAME `
  --resource-group $RESOURCE_GROUP `
  --environment $ENV_NAME `
  --image "$ACR_LOGIN_SERVER/$IMAGE_NAME" `
  --target-port 3000 `
  --ingress external `
  --registry-server $ACR_LOGIN_SERVER `
  --registry-username $ACR_USERNAME `
  --registry-password $ACR_PASSWORD `
  --secrets `
    servicenow-url=$SERVICENOW_URL `
    servicenow-username=$SERVICENOW_USERNAME `
    servicenow-password=$SERVICENOW_PASSWORD `
  --env-vars `
    SERVICENOW_INSTANCE_URL=secretref:servicenow-url `
    SERVICENOW_USERNAME=secretref:servicenow-username `
    SERVICENOW_PASSWORD=secretref:servicenow-password
```

Get the public MCP URL:

```powershell
$FQDN = az containerapp show --name $APP_NAME --resource-group $RESOURCE_GROUP --query properties.configuration.ingress.fqdn -o tsv
"https://$FQDN/mcp"
```

Health check:

```powershell
curl.exe "https://$FQDN/healthz"
```

## Use OAuth token instead of basic auth

Replace the username/password secret and environment variable lines with:

```powershell
--secrets servicenow-url=$SERVICENOW_URL servicenow-oauth-token=$SERVICENOW_OAUTH_TOKEN `
--env-vars SERVICENOW_INSTANCE_URL=secretref:servicenow-url SERVICENOW_OAUTH_TOKEN=secretref:servicenow-oauth-token
```

## Production hardening

- Put Azure API Management or an authenticated ingress in front of the MCP endpoint.
- Restrict Container Apps ingress to your corporate network where possible.
- Use Azure Key Vault secret references for ServiceNow credentials.
- Create a dedicated ServiceNow integration user with read-only ACLs.
- Add log analytics alerts for repeated ServiceNow API failures.