# mcp-enterprise-connector

MCP (Model Context Protocol) server exposing ServiceNow, Jira, and PagerDuty as tools for Claude agents and any MCP-compatible AI client.

MCP is the dominant 2026 standard for AI-to-enterprise-tool connectivity — think "USB-C for AI agents." This connector gives any Claude agent the ability to create incidents, search tickets, acknowledge alerts, and query on-call schedules through a single unified interface.

## What It Does

- **9 enterprise tools** across 3 platforms exposed via the MCP protocol
- **ServiceNow**: create incidents, get incident details, update state/work notes
- **Jira**: search with JQL, get issue details, create issues (with ADF descriptions)
- **PagerDuty**: list incidents by status, acknowledge alerts, query on-call schedules
- **Demo client**: Claude agent that uses all 9 tools via tool_use to answer operational queries
- **Typed schemas**: every tool input is validated with Pydantic before hitting the API

## Architecture

```
demo_client.py          → Claude agent (tool_use loop)
    ↓ dispatch_tool()
src/server.py           → MCP server + tool dispatch router
    ├── src/servicenow_tools.py   → ServiceNow REST API v2 client
    ├── src/jira_tools.py         → Jira Cloud REST API v3 client (ADF)
    └── src/pagerduty_tools.py    → PagerDuty REST API v2 client
src/models.py           → Pydantic v2 input validation models
```

## Setup

```bash
pip install -r requirements.txt
cp .env.example .env
# Fill in your API credentials in .env
```

## Run the MCP Server

```bash
python main.py
```

The server runs over stdio and is compatible with Claude Desktop, the MCP CLI, and any MCP-enabled AI client.

## MCP Client Configuration (Claude Desktop)

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "enterprise": {
      "command": "python",
      "args": ["path/to/mcp-enterprise-connector/main.py"],
      "env": {
        "SNOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SNOW_USER": "...",
        "SNOW_PASS": "...",
        "JIRA_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "...",
        "JIRA_TOKEN": "...",
        "PAGERDUTY_API_KEY": "..."
      }
    }
  }
}
```

## Run the Demo Agent

```bash
python demo_client.py "List the current triggered PagerDuty incidents"
python demo_client.py "Create a high-urgency ServiceNow incident: Production database is unreachable"
python demo_client.py "Who is on-call for schedule SCHED001?"
python demo_client.py "Search Jira for open bugs in project OPS"
```

## Tools

| Tool | Platform | Description |
|------|----------|-------------|
| `snow_create_incident` | ServiceNow | Create incident, set urgency/category/assignment |
| `snow_get_incident` | ServiceNow | Get full incident details by number |
| `snow_update_incident` | ServiceNow | Update state or add work notes |
| `jira_search_issues` | Jira | Search with JQL, returns key/summary/status/assignee |
| `jira_get_issue` | Jira | Full issue details including description |
| `jira_create_issue` | Jira | Create Story/Bug/Task/Epic with ADF description |
| `pd_list_incidents` | PagerDuty | List by status (triggered/acknowledged/resolved) |
| `pd_acknowledge_incident` | PagerDuty | Acknowledge on behalf of a user |
| `pd_get_oncall` | PagerDuty | Current on-call user for a schedule |

## Run Tests

```bash
pytest tests/ -v
pytest tests/ --cov=src --cov-report=term-missing
```

## What I Learned

MCP separates tool *definition* from tool *execution* cleanly — the server declares what tools exist and their JSON schemas, and the AI client decides when and how to call them. The hardest part was making the dispatch layer testable without requiring a live MCP server: extracting `dispatch_tool()` as a pure function (clients in, dict out) made every routing path unit-testable with mock clients. Jira Cloud's ADF (Atlassian Document Format) requirement for description fields is a real gotcha — plain strings are silently rejected; you must structure the content as a `doc` node tree.

## Stack

Python · `mcp` (Anthropic MCP SDK) · `anthropic` · `requests` · `pydantic v2` · `python-dotenv` · `pytest`