v0.1.0 · E1 + E2 built

Carrier-native MCP servers + governance harness for Guidewire estates, Claude/Anthropic-first.

Architectural invariants

Carrier-vocabulary tools, not API verbs. Tool names are the question an underwriter / claims / billing operator would actually ask — never search_policies.
NO MOCKS. Real Guidewire Cloud API endpoints from day one. Dev-tier OAuth creds; tests/recordings/ hold provenance-stamped HTTP captures, never invented fixtures.
Three execution modes per tool. read_only · draft_only · approved_execute. E2 ships read-only; writes wait for harness E3.
No audit = no write. Hash-chain audit per tenant, tamper-resistant via three Postgres roles (writer / reader / verifier) per D-019.
Two-key idempotency. Harness gwh1: cache key (replay short-circuit) + Guidewire GW-DBTransaction-ID wire header (server-side fail-on-duplicate). Never the same value.

Legend

Agent host / entry
Built service / package
Persistence
External Guidewire API
Planned (E3 / E6–E9)

Guidewire MCP for Claude · Architecture

A pnpm monorepo of MCP servers and shared packages that lets agents talk to Guidewire estates (PolicyCenter, ClaimCenter, BillingCenter) in carrier vocabulary, with a governance harness gating writes. E1 foundation (6 packages) and E2 PolicyCenter (5 read-only tools) are built today; harness, write-tier servers, and customer-profile fork starter follow on the public 10-epic roadmap.

System topology

grounded in pnpm-workspace.yaml · packages/* · servers/* · scripts/smoke-reach.ts

Agent host

Claude Code · Claude Desktop · Anthropic API

MCP client · stdio · streamable HTTP

MCP Servers

policycenter-mcp

E2 · built · 5 carrier-vocabulary tools · 51 tests

claimcenter-mcp

E7 · planned

billingcenter-mcp

E8 · planned

producer-mcp

E9 · planned

events-mcp

E6 · query-only

harness E3 · planned
plan → policy → approval → execute → audit → rollback
gates all writes · library + CLI, not an MCP server

E1 Foundation packages · built

client-sdk

undici · two-key idempotency

auth

openid-client v5

schemas

Zod · v1.0 + v2.0

audit

Postgres + hash-chain

observability

OTel + pino + Sentry

mcp-runtime

stdio + HTTP transports

External & Storage

Guidewire Cloud API

PolicyCenter · Job · Account

Hub OAuth

openid · tenant-scoped tokens

Postgres

audit chain · hash-linked

OTLP + Sentry

user-configured · spans

Component details

policycenter-mcp (E2 · built)

Five carrier-vocabulary tools — names that an underwriter would actually say to a junior analyst, never search_policies.
Read-only across the board. No draft_only, no approved_execute until harness E3 lands and a customer profile selects them.
SDK transport-agnostic — both tsx src/cli.ts --transport stdio and --transport http --port 3030 are real entry points.
Imports the E1 foundation as workspace deps (workspace:*): mcp-runtime, schemas, client-sdk, auth, observability.

E1 foundation packages (built)

schemas — Zod for Plan/Approval/Execute/Audit + 9 profile-YAML schemas; v1.0 and v2.0 versioning per D-020 so customer profiles can pin a major.
client-sdk — undici HTTP. Two-key idempotency: gwh1: harness cache key + Guidewire GW-DBTransaction-ID wire header (P1 fix per librarian audit).
audit — Postgres + memory store. Hash-chain via computeEntryHash() with canonical serialization; migrations/0001_init.sql declares the three-role split (writer/reader/verifier) per D-019.
auth — openid-client v5; OAuth + structural JWT validation. Tokens are scoped per-tenant — never global.
observability — OTel + pino + Sentry. getObservability() factory; every public function in servers/* opens a span (CI-enforced from E1).
mcp-runtime — wraps @modelcontextprotocol/sdk; enforces carrier-vocabulary names + three-mode binding at registration time. SDK transport stays open.

Agent host + entry surface

MCP-only invocation — Claude Desktop / Claude Code / Cursor speak the protocol; the policycenter-mcp binary handles either stdio (local) or streamable HTTP (remote-ready) at :3030.
scripts/smoke-reach.ts is the dev verification path: hits the librarian's cataloged Cloud API endpoints with dev-tier OAuth creds (D-021) and confirms reachability before tools are bound.
Tool selection is itself a guard: carrier-vocab names mean an LLM picking by intent ("find submissions waiting on me") routes deterministically, instead of guessing API verbs.

External Guidewire surfaces (no mocks)

Guidewire Cloud API — PolicyCenter Job, Account, Policy, and Composite endpoints per the librarian knowledge base. Real tenant; real responses; tests/recordings/ captures hold provenance + MANIFEST.md.
Guidewire Hub OAuth — issuer for tenant-scoped access tokens consumed by auth. Refresh handled inside the SDK; no token leaves the process.
D-008 / D-021 enforcement: CI fails loudly if sandbox is unreachable. We never silently degrade to fixtures — that's how invented API shapes ship.
P1 librarian fix: GW-DBTransaction-ID is the wire header for Guidewire's server-side idempotency; never reuse the harness gwh1: cache key as the wire value.

Persistence + audit chain

Hash-chained, append-only. computeEntryHash() serializes canonically and links each entry to the previous; tampering breaks the chain on the next verifyChain() pass.
Role split per D-019: writer appends, reader reads, verifier re-hashes. The MCP server's connection string maps to writer; verifier runs as a separate compliance job.
Memory store is for tests + ephemeral demos. Production deployments mount a Postgres connection string at boot — no fallback.
tests/recordings/ is the persistence-of-truth for HTTP — provenance-stamped, never invented, scrubbed of PII before commit.

Planned (E3 · E6–E9)

E3 harness — library + CLI (NOT an MCP server, by design — recursive harness inside an MCP tool would break tool selection). Surface: plan / policy / approval / execute / audit / rollback; cache key prefix gwh1:.
E6 events-mcp — query-only against Guidewire App Events; webhook receiver + queue lives in a sibling worker, not the MCP server.
E7 claimcenter-mcp · E8 billingcenter-mcp + payments-mcp · E9 producer-mcp — same E1 foundation; payments split out for dual-control. Profiles select read_only / draft_only / approved_execute per tool.
Each future server lands behind: customer profile + harness gate + audit row + observability span. The CI architecture rules enforce this from E1 onward.

Decision references

D-008 — NO MOCKS rule. Real Guidewire Cloud endpoints from day one; CI fails loudly on sandbox unreachability instead of silently degrading to fixtures.
D-019 — Audit chain is tamper-resistant via three Postgres roles (writer / reader / verifier), not tamper-evident against a compromised harness DBA. Verifier is a separate compliance job.
D-020 — Profile schema is versioned. v1.0 = 9 YAMLs (MVP); v2.0 adds aggregation grouping (E2.5). Customer profiles pin a major version.
D-021 — Terminology fix: "sandbox" meant Guidewire-isolated tenant; what we actually need is dev-tier OAuth credentials + real Cloud API endpoints. First integration engagement brings their own tenant.
P1 — Librarian-audit fix on idempotency: the harness gwh1: cache key (replay short-circuit) is distinct from the Guidewire GW-DBTransaction-ID wire header (server-side fail-on-duplicate). Never reuse the same value across both.