Inforcer README

Inforcer MCP Server

A Model Context Protocol (MCP) server that gives AI assistants structured, mostly read-only access to Inforcer Microsoft 365 baseline-governance data — tenants, baselines, alignment/drift, policies, secure scores, identity, audit logs, and report generation — plus two write actions to trigger an assessment run or queue a report.

Note: This project is maintained by Wyre Technology.

⚠ Community-sourced API

Inforcer does not (at time of writing) publish an official REST API specification. This server wraps the @wyre-technology/node-inforcer SDK, whose API surface is community-sourced from royklo/InforcerCommunity. Endpoints, field shapes, and behavior may change without notice. Treat results accordingly and verify anything load-bearing against the Inforcer portal.

Read-only scope

Every tool in this server is read-only EXCEPT two:

• inforcer_assessments_run — triggers an assessment run for a tenant.
• inforcer_reports_run — queues one or more report runs across one or more tenants.

Both are HIGH-IMPACT (not destructive): they kick off real work in Inforcer and are visible to operators. Both are annotated accordingly and ask for confirmation before running. Confirm with the user before invoking.

There are no create/update/delete tools for policies, tenants, or baselines — those operations are not exposed by the community API and are intentionally absent here.

Quick Start

Claude Code (CLI):

claude mcp add inforcer-mcp \
  -e INFORCER_REGION=us \
  -e INFORCER_API_KEY=your-api-key \
  -- npx -y github:WYRE-AI/inforcer-mcp

See Installation for Docker and from-source methods.

Features

• 🔌 MCP Protocol Compliance: Full support for MCP tools and prompts
• 🛡️ Governance Coverage (read-only): Tenants, baselines, alignment/drift, policies, Microsoft Secure Score, Entra ID identity, and the audit log
• 🔍 Decision-Tree Navigation: Start with inforcer_navigate to explore domains, then call domain-specific tools
• 🧭 Flexible Tenant Resolution: Most tools accept a tenant as a numeric Client Tenant ID, a tenant DNS name, an Azure AD GUID, or a friendly name — resolved automatically
• 🔒 Secure Authentication: Inf-Api-Key header auth, region-scoped
• 🌐 Dual Transport: stdio (local) and HTTP Streamable (gateway/Docker)
• 🐳 Docker Ready: Containerized deployment with HTTP transport and health checks
• 📊 Structured Logging: Configurable levels, credentials never logged

Table of Contents

• Installation
• Configuration
• Tenant identifiers
• Domains and tools
• Gateway connection
• Docker Deployment
• Development
• Testing
• Contributing
• License

Installation

Option 1: Claude Code (CLI)

claude mcp add inforcer-mcp \
  -e INFORCER_REGION=us \
  -e INFORCER_API_KEY=your-api-key \
  -- npx -y github:WYRE-AI/inforcer-mcp

Option 2: Docker

The image listens on 0.0.0.0 inside the container and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass a real S2S secret. In gateway mode the Inforcer region and API key arrive on each request as headers; they are not read from the environment.

docker build -t inforcer-mcp .
docker run \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  inforcer-mcp

Or pull the pre-built image:

docker run -d \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/inforcer-mcp:latest

Compose reads CONDUIT_S2S_SECRET from the project .env and refuses to start when that value is unset. Do not assign the variable on the command line: an empty shell value overrides .env.

docker compose up

Option 3: From Source

git clone https://github.com/WYRE-AI/inforcer-mcp.git
cd inforcer-mcp
export NODE_AUTH_TOKEN=$(gh auth token)   # to install @wyre-ai/* from GitHub Packages
npm ci
npm run build

Configuration

/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

Both INFORCER_REGION and INFORCER_API_KEY are required for any API call in stdio and AUTH_MODE=env. Tool discovery (tools/list) works without them; the first real call will error if either is missing.

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns HTTP 401 before vendor credentials are read.

CONDUIT_S2S_SECRET must already be in the environment. The example reads that variable inside the process. It does not pass the secret as a command argument.

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | node -e 'const {createHmac}=require("node:crypto"); const chunks=[]; process.stdin.on("data",(c)=>chunks.push(c)); process.stdin.on("end",()=>{ const secret=process.env.CONDUIT_S2S_SECRET; if(!secret){ console.error("CONDUIT_S2S_SECRET is not set"); process.exit(1); } process.stdout.write(createHmac("sha256", secret).update(Buffer.concat(chunks)).digest("hex")); });')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H 'X-Inforcer-Region: us' \
  -H "X-Inforcer-API-Key: $INFORCER_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

In AUTH_MODE=gateway, /mcp also requires X-Inforcer-Region and X-Inforcer-API-Key. Those headers are the only credential source for the request. With AUTH_MODE=env, the signed request uses INFORCER_REGION and INFORCER_API_KEY from the environment.

Tenant identifiers

Inforcer's tenant-scoped routes use an integer Client Tenant ID — which is NOT the same as the Azure AD tenant GUID (msTenantId). To make tools easy to use, the tenant argument accepts any of:

• a numeric Client Tenant ID (e.g. 42),
• a tenant DNS name (e.g. contoso.onmicrosoft.com),
• an Azure AD tenant GUID (msTenantId), or
• a friendly name (e.g. Contoso).

Names/DNS/GUIDs are resolved to the numeric Client Tenant ID via the SDK's resolveTenantId before each tenant-scoped call. If a name matches more than one tenant, the call fails with a clear "ambiguous" error — pass the numeric Client Tenant ID instead. Use inforcer_tenants_resolve to see exactly which Client Tenant ID an input maps to.

Domains and tools

The server uses decision-tree navigation. Start with inforcer_navigate to pick a domain, or call any tool directly. All tools are read-only except inforcer_assessments_run and inforcer_reports_run.

inforcer_reports_run queues asynchronously — poll the run with inforcer_reports_run_status until isTerminal: true, then fetch each output with inforcer_reports_download_output (returns base64-encoded file content).

Gateway connection

When hosted behind the WYRE MCP Gateway, set AUTH_MODE=gateway and MCP_TRANSPORT=http. In this mode the server is stateless (a fresh MCP server + transport per request) and reads credentials from per-request HTTP headers injected by the gateway. A request missing either header gets HTTP 401 and does not fall back to INFORCER_REGION or INFORCER_API_KEY.

The container image defaults to MCP_TRANSPORT=http and AUTH_MODE=gateway. /health always returns 200, does not require authentication, and does not read vendor credentials.

Docker Deployment

See docker-compose.yml. The checked-in Compose service is gateway mode. It publishes 127.0.0.1:8080:8080, requires CONDUIT_S2S_SECRET, and does not set INFORCER_REGION, INFORCER_API_KEY, or env_file.

cp .env.example .env
# Set CONDUIT_S2S_SECRET in .env (openssl rand -hex 32). Leave INFORCER_* empty
# for the gateway service; those credentials arrive as request headers.
# Compose loads .env itself. Do not prefix the command with a shell assignment.
docker compose up -d

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses INFORCER_REGION and INFORCER_API_KEY. It is separate from the gateway Compose service:

docker run \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e INFORCER_REGION=us \
  -e INFORCER_API_KEY=your-key \
  -p 127.0.0.1:8080:8080 \
  inforcer-mcp

Local HTTP without a secret is development-only. It binds 127.0.0.1 only and logs a warning. A non-loopback MCP_HTTP_HOST is ignored and the override is logged:

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Development

export NODE_AUTH_TOKEN=$(gh auth token)
npm ci
npm run build       # Build the project
npm run dev         # Watch mode
npm run test        # Run tests
npm run lint        # Type-check
npm run clean       # Remove dist/

# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Testing

npm test            # Run test suite
npm run test:watch  # Watch mode

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache 2.0 — Copyright WYRE Technology