MCP IT Ops Server

A safe, read-only Model Context Protocol (MCP) server for IT operations. It gives an AI client structured access to local runbooks, simulated device and incident data, and tightly allowlisted diagnostics—without giving the model permission to change infrastructure.

This is the second project in an IT-operations portfolio. It is designed to become the controlled tool layer for it-incident-triage-agent, while remaining independently useful with any compatible MCP client.

Portfolio status: working MVP. All bundled infrastructure and business data are simulated. No LLM API key is required.

Verified with MCP Inspector

The server connects over Streamable HTTP and exposes its tools and resources to the official MCP Inspector.

Local verification: connected to http://127.0.0.1:3100/mcp with successful initialize, tool discovery, and resource discovery requests.

Why this project matters

Modern AI applications increasingly need a standard, inspectable way to discover tools and context. MCP provides that boundary. This project applies it to a practical IT operations problem and makes safety visible in the architecture:

• seven focused, structured tools instead of unrestricted shell access;

• three local resources for runbooks, assets, and knowledge articles;

• Streamable HTTP for hosted clients and stdio for local desktop clients;

• exact destination allowlists, timeouts, no redirect following, and no write-capable operations;

• human approval remains in the incident-triage application before any future action layer;

• JSONL audit events record every tool invocation;

• optional bearer authentication, DNS rebinding protection, request size limits, and rate limiting.

Related MCP server: Zendesk MCP Server

Architecture

flowchart LR
    Client["MCP client / AI agent"] -->|"stdio or Streamable HTTP"| Gateway["MCP transport + security gateway"]
    Gateway --> Server["MCP server factory"]
    Server --> Tools["7 read-only tools"]
    Server --> Resources["3 local resources"]
    Tools --> Policy["Exact allowlist + protocol safeguards"]
    Policy --> Diagnostics["DNS / HTTP HEAD / TCP connect"]
    Tools --> Data["Simulated JSON data"]
    Resources --> Data
    Tools --> Audit["JSONL audit trail"]
    Diagnostics --> Audit

Each HTTP request or stdio connection gets a fresh MCP server instance. The same tools and resources are registered for both transports, keeping the behavior consistent and easy to test.

MCP capabilities

Tools

Every tool advertises MCP annotations for read-only, non-destructive, idempotent behavior and returns both human-readable text and structuredContent.

Resources

Structured output example

{
  "status": "success",
  "source": "local-runbook-library",
  "count": 1,
  "matches": [
    {
      "id": "rb-dns-001",
      "title": "DNS resolution failure",
      "relevanceScore": 2
    }
  ]
}

The live Inspector test returned the expected DNS runbook as structured content:

Blocked and invalid operations also return stable JSON errors, for example:

{
  "tool": "check_port",
  "target": "localhost:22",
  "status": "blocked",
  "reason": "Port is not on the explicit diagnostic allowlist."
}

The safety test below confirms that TCP port 22 is rejected before any connection is attempted:

Stack choice

• TypeScript and Node.js 20+ provide readable code, strong editor feedback, and a small learning surface for a first protocol server.

• Official MCP TypeScript SDK v2 implements the current stable MCP protocol line without an unnecessary model-provider dependency.

• Zod v4 validates tool inputs at the protocol boundary.

• Express 5 hosts the remote endpoint with the official MCP adapter’s Host and Origin protections.

• Node’s built-in test runner keeps tests portable and avoids a large testing framework.

• Local JSON files make the demo deterministic, reviewable, and safe before any real integration is attempted.

Quick start on Windows

Prerequisites: Node.js 20 or newer and PowerShell.

git clone https://github.com/m3yyyyy/mcp-it-ops-server.git
Set-Location .\mcp-it-ops-server
npm.cmd install
Copy-Item .env.example .env
npm.cmd test
npm.cmd run dev

Open http://127.0.0.1:3100/health. A healthy response looks like:

{"status":"ok","mode":"read-only","timestamp":"..."}

The MCP Streamable HTTP endpoint is http://127.0.0.1:3100/mcp. The root URL returns a small capability and policy summary.

Local stdio transport

Build once and point an MCP-capable desktop client at the compiled entry file:

npm.cmd run build
npm.cmd run start:stdio

Example client configuration—replace the path with your own absolute project path:

{
  "mcpServers": {
    "it-ops-local": {
      "command": "node",
      "args": [
        "C:\\path\\to\\mcp-it-ops-server\\dist\\stdio.js"
      ]
    }
  }
}

The stdio process writes protocol messages only to standard output; diagnostics and errors go to standard error.

Configuration

Copy .env.example as a reference and set environment variables in your shell or hosting platform. Node does not automatically load .env in this project.

When MCP_HOST is not loopback, startup fails unless MCP_ALLOWED_HOSTS is explicitly set. Use exact hostnames; wildcards and network ranges are intentionally unsupported.

Security design

The default configuration is local-first and fail-closed:

1. The HTTP server binds only to 127.0.0.1.

2. Tool inputs are schema validated.

3. A target must exactly match MCP_ALLOWED_TARGETS.

4. TCP ports must exactly match MCP_ALLOWED_PORTS.

5. HTTP checks require HTTPS, except http://localhost during development.

6. URL credentials are rejected, redirects are not followed, and requests time out quickly.

7. No tool can run a shell command, scan a subnet, write a file outside the audit trail, restart a service, modify DNS, or change an account.

8. Every tool call produces an audit event unless audit is explicitly disabled for an isolated test.

MCP_API_KEY is a simple demo control. For a production remote server, add OAuth 2.1 or identity-aware authorization, secret rotation, per-principal policies, durable centralized audit storage, and network egress controls. See SECURITY.md for the reporting and data-handling policy.

Audit trail

Audit events are appended as JSON Lines and excluded from Git:

{
  "id": "d6ff2bf1-...",
  "timestamp": "2026-08-28T09:00:00.000Z",
  "tool": "lookup_runbook",
  "target": "DNS hostname failure",
  "outcome": "success",
  "durationMs": 3
}

The audit log stores tool metadata, not credentials or full HTTP response bodies.

Docker

docker compose up --build

The image runs as the unprivileged node user. Compose enables a read-only root filesystem, prevents privilege escalation, and mounts only data/ for local sample data and audit output.

Before hosting remotely, set the deployed hostname in both MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS, set a strong MCP_API_KEY, and narrow the diagnostic target and port lists. render.yaml provides a portfolio-demo starting point; local operation remains the default.

Verification

npm.cmd run lint
npm.cmd test
npm.cmd run build

The test suite covers:

• exact hostname and port allowlists;

• HTTPS and credential-bearing URL rules;

• prevention of network access for blocked inputs;

• runbook ranking and local asset retrieval;

• sample data availability;

• fresh MCP server creation.

CI runs type-checking, all tests, and a production build on pushes and pull requests.

Project structure

mcp-it-ops-server/
├── data/                    # Fictional runbooks, assets, incidents, knowledge base
├── docs/screenshots/        # Portfolio screenshot assets
├── src/
│   ├── audit.ts             # JSONL audit events
│   ├── config.ts            # Environment configuration and safe defaults
│   ├── data.ts              # Local retrieval and ranking
│   ├── diagnostics.ts       # DNS, HTTP HEAD, and TCP checks
│   ├── http.ts              # Streamable HTTP entry point
│   ├── safeguards.ts        # Destination and protocol policy
│   ├── security.ts          # Bearer auth and rate limiting
│   ├── server.ts            # MCP tools and resources
│   └── stdio.ts             # Local desktop-client entry point
├── tests/                   # Fast, network-independent unit tests
├── Dockerfile
├── docker-compose.yml
└── render.yaml

Connecting the incident-triage agent

The planned integration keeps the approval gate in the existing application:

sequenceDiagram
    participant User
    participant Triage as Incident Triage Agent
    participant MCP as MCP IT Ops Server
    User->>Triage: Submit incident
    Triage->>User: Present classified plan
    User->>Triage: Approve read-only diagnostics
    Triage->>MCP: Call approved diagnostic/retrieval tools
    MCP-->>Triage: Structured results + audit IDs
    Triage-->>User: Update timeline and findings

No automatic remediation should be added to this server. If a future action service is created, it should be a separate, more strongly authenticated boundary with explicit human approval, narrower permissions, idempotency keys, and rollback procedures.

Roadmap

• Stable MCP v2 tools and resources

• Local stdio and Streamable HTTP transports

• Structured outputs and errors

• Allowlists, bearer auth, rate limits, and audit events

• Tests, Docker, CI, and sample data

• Capture real MCP Inspector screenshots

• Add an MCP client adapter to it-incident-triage-agent

• Add OAuth and per-user authorization for remote use

• Persist audits to an append-only database or log service

• Add OpenTelemetry traces and service metrics

• Add signed runbook versions and approval metadata

Resume-ready description

Project: MCP IT Ops Server — TypeScript, Node.js, Model Context Protocol, Express, Docker

Built a secure, read-only MCP server that exposes structured IT diagnostics and local runbook, asset, and incident retrieval to AI clients. Implemented dual stdio and Streamable HTTP transports, exact network allowlists, input validation, bearer authentication, rate limiting, audit logging, Docker hardening, automated tests, and CI. Designed the system as an approval-gated tool layer for an incident-triage application without granting autonomous infrastructure access.

References

• Model Context Protocol specification

• Official MCP TypeScript SDK

• MCP security best practices

License

MIT