procore-mcp

Enterprise-grade Model Context Protocol (MCP) server for Procore construction management, built on MCP 2.3+ (MCPServer) and engineered specifically for Claude Desktop, Claude Code, autonomous agent pipelines, and private Kubernetes VPC deployments.

Enterprise Documentation & Governance

procore-mcp is backed by institutional engineering artifacts, mathematical safety proofs, and enterprise commercial agreements:

• System Architecture Specification: Deep technical architecture, formal finite state machine (FSM) proofs, 3-tier dynamic context distillation, multi-vault resolution, and synthetic sandbox engine.

• Cloud-Native & Enterprise Deployment Guide: Production multi-stage Dockerfile, remote SSE protocol, enterprise Kubernetes manifests, and Helm 3 chart deployment.

• Formal Research Whitepaper: Mathematical state machine proof of Zero Terminal Reachability ($\text{ReachableStates}(MCP) \cap \text{Terminal} = \emptyset$), adversarial homoglyph invariance, and cryptographic HMAC-SHA256 audit log chaining.

• Enterprise Commercial Licensing & Services: Production commercial licenses, Turnkey Async Deployment Sprints, enterprise support retainers, multi-tenant DMSA credentials, and commercial legal indemnity.

• Security Policy & Vulnerability Reporting: Zero-leak credential policy, structural prompt injection immunity proof, secret masking, and responsible disclosure coordination (security@liamdgray.com).

Related MCP server: project-bridge

Live Demo Flight Recording

Watch the automated headless scenario execute against the zero-key Aegis Tower ($85.4M) synthetic sandbox, demonstrating context distillation, RFI creation, non-bypassable safety blocking, and cryptographic audit log chaining:

• Interactive HTML Viewer: Open docs/demo/index.html in any browser.

• Terminal Playback: asciinema play docs/demo/procore_mcp_demo.cast

• Automated Demo Runner: python3 scripts/record_demo.py --out-dir docs/demo

Architecture Overview

flowchart TD
    subgraph Clients["AI Clients & Host Environments"]
        CD["Claude Desktop"]
        CC["Claude Code / Agent CLI"]
        REMOTE["Remote Web Agents / VPC Clients"]
    end

    subgraph Server["procore-mcp Server (MCP 2.3+ MCPServer)"]
        TRANS["Transport Router\n(stdio / sse / streamable-http)"]
        SG["Safety Gate Engine\n(assert_write_permitted)"]
        PD["3-Tier Token Compression\n(compact: -94.3% / std: -89.5% / exec: -91.5%)"]
        VAULT["Zero-Trust Multi-Vault\n(1Password / AWS SM / HashiCorp)"]
        AUTH["DMSA Autonomous Auth\n(Auto-Refreshing Client Credentials)"]
        AL["HMAC-SHA256 Flight Recorder\n(Cryptographic Hash Chain)"]
        HTTP["Procore API Client\n(Rate Limiting & Retries)"]
        SANDBOX["Aegis Tower Demo Sandbox\n(Zero-Key In-Memory Engine)"]
    end

    subgraph External["Upstream Services"]
        API["Procore REST API v1.0\n(api.procore.com)"]
        MOCK["OpenAPI 3.0 Mock Server\n(localhost:8080)"]
    end

    CD -->|stdio / JSON-RPC| TRANS
    CC -->|stdio / JSON-RPC| TRANS
    REMOTE -->|HTTP / SSE (:8000)| TRANS
    TRANS --> SG
    SG -->|Mutations Guardrail| AL
    AL --> HTTP
    TRANS -->|Queries| HTTP
    VAULT --> AUTH
    AUTH -->|Bearer Token| HTTP
    HTTP -->|Live Mode| API
    HTTP -->|Mock Mode| MOCK
    HTTP -->|Demo Mode| SANDBOX
    HTTP --> PD
    PD -->|Distilled Semantic Context| TRANS

Key Enterprise Capabilities

1. MCP 2.3+ Standard (MCPServer): Built natively on the latest Linux Foundation Model Context Protocol SDK, supporting stdio, network sse, and streamable-http transports.

2. DMSA Autonomous Machine-to-Machine Auth: Zero browser redirects or OAuth callback servers required. Utilizes Developer Managed Service Account (DMSA) client credentials with transparent, proactive token rotation before expiration.

3. Safety Gate Invariants & Draft-Only Mutations: Read-only by default. When --allow-writes is explicitly enabled, mutations are restricted to draft state (status: "draft"). Any transition to terminal or authoritative statuses (issued, approved, executed, closed) is rejected with a SafetyInvariantViolation.

4. Dynamic 3-Tier Context Compression (-89.5% to -94.4%): Configurable distillation tiers (compact, standard, executive) reduce token overhead up to 94.35%, preserving Claude's context window and preventing context bloat.

5. Zero-Trust Multi-Vault Resolution: Resolves credentials transparently from 1Password (op://...), AWS Secrets Manager (arn:aws:secretsmanager:...), HashiCorp Vault (vault://...), or environment variables with strict zero-leak in-memory string masking.

6. Zero-Key Synthetic Construction Sandbox (--demo): Instant in-memory simulation of the $85.4M Aegis Tower project (24 RFIs, 16 submittals, 11 change events, 10 cost codes) for zero-risk testing and demonstrations without a Procore subscription.

7. OpenAPI 3.0 Conforming Mock HTTP Server: Standalone HTTP mock server (procore-mcp mock-server --port 8080) implementing official Procore REST endpoints with rate limit headers and JSON schemas.

8. Cryptographic HMAC-SHA256 Flight Recorder CLI: Real-time tamper-evident audit logging with Rich terminal visualization tools:

   • procore-mcp audit verify <log>: Verifies mathematical hash chain integrity.

   • procore-mcp audit inspect <log>: Displays styled event inspection tables.

9. Production Cloud-Native & Kubernetes Ready: Hardened non-root Docker container (python:3.12-slim, UID 10001) and production-tested Helm 3 charts (deploy/helm/procore-mcp/).

Quickstart & Installation

Option 1: Claude Desktop (claude_desktop_config.json)

Add procore-mcp to your Claude Desktop configuration file:

{
  "mcpServers": {
    "procore": {
      "command": "uvx",
      "args": ["procore-mcp"],
      "env": {
        "PROCORE_CLIENT_ID": "your_procore_dmsa_client_id",
        "PROCORE_CLIENT_SECRET": "your_procore_dmsa_client_secret",
        "PROCORE_BASE_URL": "https://api.procore.com",
        "PROCORE_ALLOW_WRITES": "false"
      }
    }
  }
}

Option 2: Instant Zero-Key Demo Mode (No Procore Account Required)

Test immediately using the in-memory synthetic construction sandbox:

{
  "mcpServers": {
    "procore-demo": {
      "command": "uvx",
      "args": ["procore-mcp", "--demo"]
    }
  }
}

Option 3: Remote Network SSE Container (Docker / Podman)

Run the server as a centralized service accessible over network SSE:

# Run with Docker
docker run -d --name procore-mcp \
  -p 8000:8000 \
  -v procore_audit:/data \
  -e PROCORE_CLIENT_ID="your_client_id" \
  -e PROCORE_CLIENT_SECRET="your_client_secret" \
  ghcr.io/liam-gray/procore-mcp:latest \
  --transport sse --host 0.0.0.0 --port 8000

Connect Claude Desktop to the remote SSE endpoint:

{
  "mcpServers": {
    "procore-remote": {
      "url": "http://your-server-host:8000/sse"
    }
  }
}

Option 4: Enterprise Kubernetes (Helm 3)

Deploy to private VPC Kubernetes clusters using the official Helm chart:

# Deploy with Helm
helm install procore-mcp deploy/helm/procore-mcp/ \
  --set env.demoMode=false \
  --set secrets.clientId="your_client_id" \
  --set secrets.clientSecret="your_client_secret"

# Or apply raw manifests directly
kubectl apply -f deploy/k8s/

CLI Commands & Subcommands

Running the Server

# Standard I/O mode (default for Claude Desktop / Claude Code)
procore-mcp

# Demo mode (synthetic Aegis Tower project)
procore-mcp --demo

# Remote Server-Sent Events (SSE) mode
procore-mcp --transport sse --host 0.0.0.0 --port 8000

Cryptographic Flight Recorder CLI

# Verify HMAC-SHA256 hash chain integrity
procore-mcp audit verify /data/procore_audit.jsonl

# Inspect audit log events with visual dashboard
procore-mcp audit inspect /data/procore_audit.jsonl --limit 20

# Filter exclusively for security-blocked invariant events
procore-mcp audit inspect /data/procore_audit.jsonl --blocked-only

OpenAPI 3.0 Mock HTTP Server

# Start standalone Procore REST API v1.0 mock server
procore-mcp mock-server --port 8080 --host 0.0.0.0

Tool Reference (18 Allowlisted Tools)

Core Project Tools

Operations Tools

Financial & Cost Tools

Local Development & Quality Gate

This project adheres to strict Test-Driven Development (TDD) and static analysis.

# Run complete test suite and static analysis (Ruff, Mypy Strict, Pytest)
./run_checks.sh

All 448 tests run deterministically without external network access or real Procore API credentials.

Licensing & Commercial Procurement

procore-mcp is licensed under the Business Source License 1.1 (BSL 1.1):

• Non-Production & Evaluation: Free of charge for local development, research, and non-production testing.

• Production Commercial Use: Production deployment requires an Enterprise Commercial License from Liam D Gray Labs (tiered by active project volume and organizational scale).

• Turnkey Async Deployment Sprints: Fixed-scope implementation statements of work (SOW) for dedicated VPC, private Kubernetes cluster, and enterprise ERP cost-code integration.

• Open Source Transition: The codebase automatically transitions to the Apache License 2.0 on October 4, 2028.

For terms, entitlements, and procurement inquiries, review COMMERCIAL.md or contact procurement@liamdgray.com.