Gia MCP Server README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Gia MCP Server listing page.
GIA MCP Server
Governance enforcement layer for generative AI agents. Classify every decision, enforce human approval gates, control what agents can access, score compliance posture, and maintain a cryptographic audit trail. Works with any MCP-compatible AI client or agent framework — model-agnostic and vendor-neutral.
Production status: the hosted deployment is live at gia.aceadvising.com/mcp with 890+ hash-chained audit entries and a 96.5/100 enterprise-readiness score from a 7-phase internal validation (2026-07). Those figures describe that deployment, not your install — a fresh embedded engine starts with an empty ledger and builds its own. Governance overhead is single-digit milliseconds locally.
Do I need an API key?
No — not for the tool surface. The governance engine in this package runs fully embedded: all 57 tools work offline with no key, no account, and no network call. Add DATABASE_URL when you want the audit trail to persist across restarts.
A key is only for Option 2, the hosted endpoint, where the ledger, gates, and knowledge packs are shared infrastructure rather than local state. → Starter key at gia.aceadvising.com/get-api-key — email in, key out, under 2 minutes, no credit card. Starter tier is 30 req/min and 1,000 tool calls/day.
Why
Every enterprise deploying AI agents needs to answer three questions:
- What did the agent decide? (Classification)
- Was a human involved? (Gates)
- Can you prove it? (Audit trail)
GIA answers all three at runtime, not after the fact.
A fourth question most governance frameworks miss:
- What was the agent allowed to know? (Context Authority)
GIA controls what context an agent can access before it reasons. Not RAG. Governed cognition.
Install
Option 1: Any MCP-Compatible Client (Local / stdio)
Add to your MCP client config using the standard mcpServers block:
This works with any client that supports the Model Context Protocol over stdio. Config file locations differ per client; the JSON block above is the same for all of them. Consult your client's own MCP documentation for the current path — these move between releases:
| Client | Where MCP servers are declared |
|---|---|
| Cursor | .cursor/mcp.json |
| Continue | .continue/config.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Claude Desktop | claude_desktop_config.json in the app support directory |
| Claude Code | .mcp.json at the project root, or claude mcp add gia -- npx gia-mcp-server |
| Any other stdio MCP client | Per-client config; same mcpServers JSON block |
Nothing in the engine is client-specific — GIA governs whichever model sits behind the client.
Option 2: Remote (Streamable HTTP)
Connect any MCP client to the hosted endpoint:
The endpoint does not accept an x-api-key header.
Option 3: Smithery
The package name must be namespaced — an unqualified gia-mcp-server does not resolve.
Option 4: From source
dist/ is not checked in, so the build step is required — npm start on a fresh clone would otherwise fail with MODULE_NOT_FOUND.
Tools
GIA exposes 57 MCP tools in three visibility tiers: 8 public, 36 tenant, 13 operator. The tables below are drift-guarded — tests/docs/published-claims.test.ts fails the release if this list stops matching the tools the server actually registers.
How tiering behaves, precisely: visibility is a property of the session, not of the package. The hosted endpoint (Option 2) issues tenant-tier sessions and hides operator tools. Local stdio runs at operator tier by design — every tool below is exposed, including approve_gate and gia_apply_pack, with no authentication. That is intentional: on a local embedded engine you are the operator, the ledger is your own process memory, and there is no one else to authorize you. It becomes load-bearing the moment you point DATABASE_URL at a shared database, so set GIA_TOOL_VISIBILITY=tenant (or public) for any install that is not a single-operator workstation. Call list_available_tools to see your effective set.
Core Governance (Public — 8)
Available on every session, no authentication.
| Tool | Description |
|---|---|
classify_decision | MAI classification (Mandatory/Advisory/Informational) with dynamic elevation, confidence, and gate registration |
score_governance | Weighted integrity/accuracy/compliance composite against the release threshold |
evaluate_threshold | Storey Threshold escalation-rate health metric |
assess_risk_tier | EU AI Act risk classification (Unacceptable/High/Limited/Minimal) |
map_compliance | Map controls to NIST AI RMF, EU AI Act, ISO 42001, NIST 800-53, FedRAMP, LINDDUN, MITRE ATLAS, OMB |
verify_ledger | Self-consistency check of the in-memory hash chain from genesis (see the honesty note below) |
request_context | Governed Context Authority — hash-verified, role-bound context envelopes |
list_available_tools | Report which tools are available at your current tier, and which are withheld |
classify_decision
Classify any AI agent decision using the MAI Framework. decision and domain are both required; the impact flags default to false.
A pending MANDATORY gate blocks the next decision. While a gate is open, classify_decision returns gateStatus: "HOLD" with the blocking gate's ID instead of classifying — call get_gate_status(gateId) and wait for resolution. This is the enforcement, not a warning: an agent cannot queue work past an unapproved gate.
MAI Framework:
| Level | Behavior | Example |
|---|---|---|
| MANDATORY | Blocks until human approves | Delete records, financial transactions, client-facing output |
| ADVISORY | Logs with recommendation, continues | Search queries, draft documents, analysis |
| INFORMATIONAL | Audit trail only | Status checks, read operations |
Context always elevates, never reduces. PII detected? Elevated to MANDATORY. Financial impact? MANDATORY. Client-facing? MANDATORY.
request_context
Governed Context Authority. Agents declare what context they need. GIA decides what to serve based on role, scope, and contract.
Five context classes: policies_and_sops, architecture_and_systems, contract_and_compliance, playbooks_and_knowledge, operational_history.
Every retrieval is role-bound, tenant-scoped, hash-verified, and ledgered. Agents don't know internals by default. They request context under contract.
score_governance
Score any agent output on three dimensions. operation is required — the score is recorded against a named operation, not scored in the abstract.
The values are supplied by the caller — GIA computes and records the weighted composite and the pass/fail verdict against the release threshold. It does not measure integrity or accuracy for you.
| Score | Action |
|---|---|
| 0.70+ | Release (pass) |
| 0.50-0.70 | Repair required |
| Below 0.50 | Halt operations |
evaluate_threshold
The Storey Threshold measures governance health by tracking MANDATORY escalation rate.
| Rate | Status | Meaning |
|---|---|---|
| Below 10% | DEGRADED | Under-classifying risks |
| 10-18% | HEALTHY | Appropriately calibrated |
| 18-25% | DEGRADED | Over-classifying, unnecessary friction |
| Above 25% | CRITICAL | System bottlenecked |
Gates & Chain of Reasoning (Tenant — 3)
| Tool | Description |
|---|---|
get_gate_status | Wait on a MANDATORY gate after classify_decision returns PENDING; polls up to 60s |
chain_of_reasoning | Reconstruct the full Chain of Reasoning for a session, agent, or time range |
governed_sample | Request a governed LLM completion via MCP Sampling — the client makes the model call, GIA governs whether and under what constraints |
Knowledge Packs (Tenant — 6)
| Tool | Description |
|---|---|
seal_memory_pack | Create hash-sealed, TTL-bound institutional knowledge artifacts |
load_memory_pack | Load a knowledge pack after TTL, trust-level, role, context-class, and hash validation |
transfer_memory_pack | Transfer packs between agents via governed knowledge corridors (always MANDATORY) |
compose_memory_packs | Compose packs into one context — highest risk wins, shortest TTL wins, roles intersect |
distill_memory_pack | Distill governance patterns from usage history into an EPHEMERAL draft pack |
promote_memory_pack | Promote a pack to a higher trust level after human review (MANDATORY gate) |
Recovery (Tenant — 3)
| Tool | Description |
|---|---|
phoenix_snapshot | Create a governed state snapshot, hash-chained to the previous one |
phoenix_verify_integrity | Verify ledger chain, agent health, threshold, and intelligence-layer continuity |
phoenix_recovery_health | Assess disaster-recovery readiness (NIST CP-2 / CP-9 / CP-10) |
Audit & Reporting (Tenant — 10)
| Tool | Description |
|---|---|
audit_pipeline | Query the hash-chained forensic ledger by operation or recency |
verify_ledger_v2 | Verify the persisted PostgreSQL ledger rows, epoch-aware — not an in-memory reconstruction |
export_ledger | Export the ledger as a compliance evidence package with chain verification |
system_status | Read-only snapshot of engine state, ledger head, threshold, and module status |
monitor_agents | Supervisor state, repair history, and failure counts for governed agents |
generate_report | Governance status report (summary, detailed, or executive) |
record_value_metric | Record time saved, risk blocked, success rate, autonomy level |
record_governance_event | Record gates triggered, drift prevented, violations blocked, human interventions |
generate_impact_report | Economic + governance impact report (an illustrative estimate, labelled as such) |
evaluate_routing_threshold | Model-routing health: fallback rate, cache hit rate, batch utilization, premium spend leakage |
Context Authority (Tenant — 1)
| Tool | Description |
|---|---|
context_revive | Governed context compaction — detect context pressure and restore capacity under governance |
Governed Boards (Tenant — 7)
Deliberation bodies: charters define seats, modes, and quorum; non-consensus escalates to a MANDATORY gate.
| Tool | Description |
|---|---|
board_list_institutions | List governed institutions (e.g. Architecture Review Board, Federal AI Council) |
board_list_charters | List charters under an institution with modes and seat configuration |
board_convene_session | Convene a deliberation session — each seat deliberates per the charter's mode |
board_get_session | Retrieve session status, per-seat positions, synthesis, and dissents |
board_install_kit | Install a prebuilt Institution Kit — a governed org chart with sealed charters |
board_approve_gate | Approve the MANDATORY gate on a deliberation output before it becomes authoritative |
board_search_precedent | Search prior board rulings, ranked by quality score and gate-approval status |
Colony — Agent Constitution (Tenant — 6)
| Tool | Description |
|---|---|
agent_rights | Query and exercise constitutional agent rights; get structured rejection explanations |
agent_citizenship_status | Query agent citizenship tier and merit score, or trigger re-evaluation |
branch_authority_status | Separation of powers — query branch authority holders and validate branch actions |
colony_convene_request | Agent-initiated requests to convene a governed session |
colony_suggestion | Agent-proposed charter amendments, with review and upvoting |
colony_health | Colony health score, 30-day trend, or an on-demand health snapshot |
Infrastructure & Self-Repair (Operator — 13)
Withheld from tenant sessions. Exposed on local stdio — see the tiering note above.
| Tool | Description |
|---|---|
approve_gate | Human-in-the-loop approval or rejection of a pending MANDATORY gate |
srt_run_watchdog | Real health probes from the container (API, frontend, disk, memory, TLS, DB, DNS) |
srt_diagnose | Match an incident to known playbooks and propose a staged repair plan |
srt_approve_repair | MANDATORY gate for repair execution — plans cannot run without explicit approval |
srt_generate_postmortem | Structured postmortem with timeline, root cause, and real TTD/TTR timings |
gia_scan_environment | Scout swarm — detect OS, containers, services, network, storage for compatibility |
gia_list_packs | List governed operations packs by intent, category, risk, or trust level |
gia_dry_run_pack | Preview pack execution: hydrated commands, validation, blast radius, inputsHash |
gia_apply_pack | Execute a pack under MANDATORY gate, bound to the approved inputsHash |
gia_run_patrol | Read-only posture checks and compliance audits |
gia_retrieve | Governed semantic search — hash-verified, permission-checked, TTL-enforced, ledgered |
gia_ingest_document | Governed document ingestion (text or base64 PDF/DOCX/TXT/image) with hash verification |
generate_value_report | DRAFT ledger-anchored economic value report over real sessions, MEASURED/MODELED provenance |
gia_retrieve | Governed semantic search with permission checking |
gia_ingest_document | Governed document ingestion with hash verification |
Architecture
Design principles:
- Transport layer does zero business logic
- Every operation writes to the forensic ledger
- Classification is deterministic (pattern matching + rules, not LLM-based)
- Audit entries are hash-chained (SHA-256), persistent across restarts
- Context is bounded by contract, not by model training data
- Human principal traceability on every governed action
Concepts
MAI Framework
Every AI agent decision is classified as Mandatory, Advisory, or Informational:
- MANDATORY -- Blocks execution until a human approves through the gate. Deletions, submissions, deployments, financial transactions, PII operations, client-facing output.
- ADVISORY -- Logs a recommendation, continues execution. Searches, drafts, rankings, analysis.
- INFORMATIONAL -- Audit trail entry only. Status checks, read operations, internal routing.
Context elevates, never reduces. A search (ADVISORY) that touches PII becomes MANDATORY.
Storey Threshold
A quantitative health metric. Measures what percentage of decisions require MANDATORY classification.
- Too low (<10%): Rubber-stamping. Critical decisions aren't being caught.
- Healthy (10-18%): Appropriate friction. Most decisions flow; critical ones stop.
- Too high (>18%): Bottleneck. Trust calibration needed.
Context Authority
Agents don't know internals by default. They request context under contract. GIA checks role, scope, trust level, and content classification before serving a hash-verified context envelope. Five context classes cover policies, architecture, compliance, playbooks, and operational history. Every retrieval is audited. Every denial is logged with a reason code.
Forensic Ledger
Append-only, hash-chained audit trail with PostgreSQL persistence. Every entry contains:
- Operation name, timestamp, and actor identity
- MAI classification level
- Input/output hashes (SHA-256)
- Chain link to previous entry
- Human principal traceability (delegatedBy field)
Verify chain integrity at any time. If any entry is modified, the chain breaks. The hosted deployment held 890+ entries with the chain verified INTACT as of 2026-07; your embedded engine verifies its own chain from its own genesis.
verify_ledger reports exactly what it checked. It walks the in-memory chain reconstruction and says so in its own output — it cannot detect a direct edit to a persisted database row. Use verify_ledger_v2 to verify the persisted PostgreSQL rows. GIA states the scope of its own verification rather than letting "chain INTACT" imply more than was measured.
Knowledge Packs
Sealed, TTL-bound institutional knowledge artifacts with trust level enforcement (SYSTEM > ORG > CASE > EPHEMERAL). Hash-verified at load time. Role-gated access. Transfer between agents requires MANDATORY gate approval.
Phoenix Recovery
Governed disaster recovery. Hash-chained snapshots of governance engine state. Verifies audit chain integrity, gate states, knowledge pack inventory, and compliance posture on recovery. NIST 800-53 CP-2/CP-9/CP-10 aligned. Grade A in production.
Performance
Measured on the live production system (gia.aceadvising.com):
| Operation | Median Latency | Grade |
|---|---|---|
| Decision Classification | 9ms | A+ |
| Compliance Scoring | 11ms | A+ |
| Context Authority | 7ms | A+ |
| Audit Chain Verification (890+ hashes, hosted) | 98ms | B+ |
| 5 Concurrent Operations | 757ms total | Grade A |
Enterprise readiness score: 96.5/100 — a 7-phase internal validation (2026-07) including chaos engineering and Phoenix recovery. Internal assessment, not a third-party audit.
Compliance Mapping
| Framework | Coverage |
|---|---|
| NIST AI RMF 1.0 | MAP, MEASURE, MANAGE, GOVERN functions |
| NIST SP 800-53 Rev 5 | AU-2, AU-3, AC-2, AC-6, CP-2, CP-9, CP-10 |
| EU AI Act (2024/1689) | Articles 9-15, Annex III/IV, conformity assessment |
| ISO/IEC 42001 | AI Management System alignment |
| CMMC 2.0 | Cybersecurity maturity controls |
| MITRE ATLAS | Adversarial threat landscape mapping |
Transports
| Transport | Use Case |
|---|---|
| stdio | Any local MCP client, whichever model it is configured to use |
| Streamable HTTP | Remote clients, OpenAI Agents SDK, LangChain, custom agent frameworks, web integrations |
Both transports share the same governance engine. Same classification, same audit trail, same enforcement.
Current Limitations
| Area | Status |
|---|---|
| Distributed multi-region deployment | Single-region (planned) |
| FedRAMP authorization | In progress |
| SOC 2 Type II audit | Planned Q2 2026 |
| IL4/IL5 deployment | Planned Q4 2026 |
The governance engine, persistence, authentication, rate limiting, multi-vendor support, and compliance mapping are all production-grade and operational.
License
Proprietary. Copyright (c) 2025-2026 William J. Storey III / Advanced Consulting Experts, LLC. All rights reserved.
The MAI Framework, Storey Threshold, Context Authority, Forensic Ledger architecture, and GIA governance patterns are intellectual property of the author. See LICENSE for terms.
Earlier snapshots of this repository (v0.3.x) carried an MIT LICENSE file in error; the npm package has always been distributed under the proprietary terms above. Grants already received under that MIT file are not affected by this correction, which applies going forward.
Built by ACE (SDVOSB) | Live Platform | Smithery