ServiceNow Cowork Automation API

ServiceNow Cowork Automation API

FastAPI + MCP-compatible backend for Microsoft 365 Copilot Cowork ServiceNow incident automation.

What this backend does

• Receives ServiceNow new-incident webhooks.
• Deduplicates automation jobs.
• Queues jobs to Azure Service Bus when enabled.
• Exposes controlled /api/cowork/* APIs for Cowork plugin/MCP use.
• Exposes a remote MCP-compatible /mcp JSON-RPC endpoint.
• Applies backend policy checks before ServiceNow or Microsoft Graph actions.
• Searches/classifies ServiceNow KB articles.
• Performs eligible Microsoft Entra ID password reset/profile update through Graph.
• Writes job, policy, KB, and audit records.
• Never returns or logs temporary passwords.

Local setup

python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
copy .env.example .env
uvicorn app.main:app --reload

Test

pytest -q
pytest --cov=app

Required environment variables

See .env.example.

For local/dev, keep:

SERVICE_BUS_ENABLED=false
GRAPH_ENABLED=false
DATABASE_URL=sqlite+aiosqlite:///./cowork.db

For Azure, set DATABASE_URL, ServiceNow credentials, Graph settings, and Service Bus settings in App Service/Function App configuration or Key Vault references.

REST examples

Health:

curl http://localhost:8000/health

Webhook:

curl -X POST http://localhost:8000/api/servicenow/webhook/incidents ^
  -H "Content-Type: application/json" ^
  -H "x-api-key: local-test-key" ^
  -d "{\"sys_id\":\"inc-1\",\"number\":\"INC0010001\",\"state\":\"New\",\"category\":\"access\",\"priority\":\"3\",\"short_description\":\"forgot password\"}"

Analyze:

curl -X POST http://localhost:8000/api/cowork/incidents/analyze ^
  -H "Content-Type: application/json" ^
  -H "x-api-key: local-test-key" ^
  -d "{\"incident_sys_id\":\"inc-1\",\"authenticated_user_upn\":\"user@contoso.com\"}"

MCP initialize:

curl -X POST http://localhost:8000/mcp ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}"

List MCP tools:

curl -X POST http://localhost:8000/mcp ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"

Safety model

Cowork should mainly call:

• analyze_incident
• run_incident_automation
• get_automation_job_status

The backend remains the final trust boundary for identity, policy, VIP/admin/security exclusions, KB safety classification, and Graph actions.