MCP for COIOps

Connect

1. Sign in to your org and open Settings → MCP keys (or use the demo key from npm run seed locally).
2. Create an org API key. Copy the coiops_… secret once — it is hashed at rest and never shown again.
3. Point your MCP client at POST https://coiops.com/api/mcp with Authorization: Bearer coiops_… (org API key). OAuth discovery stubs live at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server; API keys are the supported production path today.
4. Call tools/list then tools/call (JSON-RPC 2.0). Optional prompts/list, resources/list. Every call is org-isolated.
5. On writes, you may send Idempotency-Key for ingest_coi_pdf, request_updated_coi, and set_gate_status (per canonical docs/MCP.md).

Install snippets (HTTP MCP)

Paste into clients that support remote MCP over HTTP with custom headers. Replace the bearer token with your org key. Clients that only support stdio need a local bridge — we do not ship a separate npm wrapper in this repo.

Cursor / Claude Desktop / VS Code (when HTTP MCP is enabled)

{
  "mcpServers": {
    "coiops": {
      "url": "https://coiops.com/api/mcp",
      "headers": {
        "Authorization": "Bearer coiops_REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}

Smoke test: GET https://coiops.com/api/mcp returns the tool catalog JSON without auth; unauthenticated POST returns 401 with WWW-Authenticate including resource_metadata.

Tool catalog (this build)

• list_vendors

  List vendors for the authenticated org. Optional gate_status / query filter.

• get_vendor

  Vendor + latest certificate summary + gate + open deficiencies.

• upsert_vendor

  Create or update a vendor.

• ingest_coi_pdf

  Store the real COI PDF and run extraction. Queues needs_review. Does not invent a carrier or auto-clear the gate.

• check_requirements

  Score vendor against template (explicit → job → org default). Writes RequirementScore + Deficiencies. Document score only — not live carrier verify.

• list_expiring_cois

  Coverage lines expiring within N days.

• request_updated_coi

  Create a chase record and email a magic-link upload when Resend or SMTP is configured. If mail is unset, the chase is stored and not marked sent.

• block_vendor_if_noncompliant

  Confirm-gated: block vendor when latest score fail or coverage expired.

  Confirm-gated write — pass confirm:true.

• set_gate_status

  Set gate status. confirm required for cleared / override_cleared. Reason mandatory.

  Confirm-gated write — pass confirm:true.

• run_morning_compliance_brief

  Ops brief: blocked, expiring, unanswered chases, review queue.

• list_templates

  List requirement templates for the org.

• upsert_template

  Create or update a requirement template. confirm required when changing org-default template.

• export_compliance_pack

  Post-MVP: generate compliance pack download URL.

• sync_status_outbound

  Post-MVP: push gate status to external system.

Metering

Subscriptions stay asset-capped (vendors per plan). MCP tool calls are logged as billable units (reads = 1, writes = 5, heavy = 25). Write and automation tools require Pro ($29/mo, same Stripe price as in-app checkout). Free and waitlist orgs get read-only MCP within a small monthly unit cap.

• Free: 500 included units / month (read-heavy)
• Pro: 10,000 included units / month (writes included)
• Growth: 25,000 · Ops: 50,000

Per-tool weights in code: list_vendors=1, get_vendor=1, list_expiring_cois=1, run_morning_compliance_brief=25…

Rate limits & honesty

• Invalid or revoked keys return 401 with OAuth PRM header.
• Free org calling a write tool returns 402 with upgrade URL to /pricing.
• Monthly MCP unit cap returns 429 with Retry-After.
• Chase email uses Resend or SMTP when configured; otherwise the chase is stored and not marked sent.
• Hard per-tenant rate limits are not published yet — abuse protection may return 429 with retry guidance.