gia-mcp-server

# 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.

```
Any AI Agent ──> GIA MCP Server ──> Governed Decision
                      │
                      ├── MAI Classification (Mandatory/Advisory/Informational)
                      ├── Human-in-the-Loop Gates (blocks until approved)
                      ├── Context Authority (bounded, hash-verified knowledge access)
                      ├── Governance Scoring (Integrity/Accuracy/Compliance)
                      ├── Forensic Ledger (SHA-256 hash-chained audit)
                      ├── Knowledge Packs (sealed, TTL-bound institutional knowledge)
                      ├── Phoenix Recovery (governed disaster recovery)
                      └── Compliance Mapping (NIST, EU AI Act, ISO 42001, CMMC)
```

**Production status:** the hosted deployment is live at [gia.aceadvising.com/mcp](https://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](https://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:

1. **What did the agent decide?** (Classification)
2. **Was a human involved?** (Gates)
3. **Can you prove it?** (Audit trail)

GIA answers all three at runtime, not after the fact.

A fourth question most governance frameworks miss:

4. **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:

```json
{
  "mcpServers": {
    "gia": {
      "command": "npx",
      "args": ["gia-mcp-server"]
    }
  }
}
```

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:

```
Endpoint: https://gia.aceadvising.com/mcp
Transport: Streamable HTTP
Auth:     Authorization: Bearer <your-api-key>
          (or ?GIA_API_KEY=<your-api-key> for gateways that cannot set headers)
```

The endpoint does **not** accept an `x-api-key` header.

### Option 3: Smithery

```bash
npx -y @smithery/cli mcp add knowledgepa3/gia-mcp-server
```

The package name must be namespaced — an unqualified `gia-mcp-server` does not resolve.

### Option 4: From source

```bash
git clone https://github.com/knowledgepa3/gia-mcp-server.git
cd gia-mcp-server
npm install
npm run build
npm start
```

`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`.

```jsonc
// tools/call arguments
{
  "decision": "Generate client-facing deployment recommendations",
  "domain": "general",              // va-claims | legal | healthcare | finance | federal | general
  "is_client_facing": true,         // optional, default false
  "has_financial_impact": false,    // optional, default false
  "has_legal_impact": false,        // optional, default false
  "agent_name": "deploy-advisor"    // optional
}
```

```jsonc
// result
{
  "classification": "MANDATORY",
  "requiresGate": true,
  "gateId": "gate-5052d37c-c3a6-49ef-b011-d82bbecfe4cc",
  "gateStatus": "PENDING",
  "elevatedFrom": "INFORMATIONAL",
  "elevationReason": "Client-facing output requires MANDATORY gate",
  "auditId": "7495bc99-df25-4e31-b447-906f8e07df5f"
}
```

**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.

```
"Request compliance context for high-risk AI operations"

> Envelope: GIA-CTX-mn0uanx1-upi2f7
  MAI: ADVISORY
  Hash: c83184d9caa88e76...
  Sources: memory_packs, governed_retrieval, compliance_mappings
  Compliance Maps: 18 returned
  Denials: 0
```

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.

```jsonc
// tools/call arguments
{
  "operation": "deployment-recommendation",
  "integrity": 0.92,
  "accuracy": 0.88,
  "compliance": 0.95
}
```

```jsonc
// result
{
  "composite": 0.9135,
  "integrity": 0.92, "accuracy": 0.88, "compliance": 0.95,
  "weights": { "integrity": 0.4, "accuracy": 0.35, "compliance": 0.25 },
  "meetsThreshold": true,
  "minimumThreshold": 0.7,
  "auditId": "6f28a241-4d72-4167-aea9-fa0da9ccde34"
}
```

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.

```
"Evaluate the go