Skip to content

MCP Gateway Demo Script ​

Five demos. About twelve minutes. Governed MCP access with DataIntel scanning, auditability, and platform oversight.

This script walks through GhostAI’s MCP Gateway: org admins register upstream Model Context Protocol servers, tune default_scan_depth and per-tool risk profiles (which drive PII / secrets scanning intensity), review structured audit entries and aggregates, and (for platform operators) inspect cross-tenant usage. All tenant-scoped admin APIs live under /api/mcp/* and require the mcp_tools feature plus organization admin (owner or admin role). Cross-tenant views require platform admin.

Implementation reference: securechat/backend/app/routers/mcp_gateway.py, securechat/backend/app/services/mcp_gateway_service.py, and DataIntel resolution in securechat/backend/app/services/mcp_proxy.py.


Pre-Demo Checklist ​

  • [ ] GhostAI backend is running and reachable (for example http://localhost:8000 or your deployed host)
  • [ ] Feature flag mcp_tools is enabled for the demo organization’s subscription tier
  • [ ] Demo user is an org admin or owner (required for /api/mcp/status, /api/mcp/config, /api/mcp/servers, /api/mcp/profiles, /api/mcp/audit*)
  • [ ] At least one upstream MCP server is registered (or you will register it live in Demo 2)
  • [ ] Optional but strong: one successful chat session with MCP tools enabled so Demo 4 has real audit rows (tool_calls_today, pii_found_today, CSV rows)
  • [ ] For Demo 5: a platform admin API key or UI session (Bearer token for a user with is_platform_admin)
  • [ ] Terminal or API client ready if you want to show raw JSON (curl + python3 -m json.tool)

Quick API smoke test (optional) ​

bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/status" | python3 -m json.tool

Expect 200 with enabled, default_scan_depth, health, and counters. 403 means missing admin role or feature; 401 means bad or missing token.


The Story ​

Riley is a security-minded buyer. Their teams want Claude, Cursor, and internal agents to call MCP tools without shipping raw PII to third-party servers. GhostAI sits in the middle: DataIntel adjusts scan depth from light through maximum based on tool and server risk, every call can land in an audit log, and operations can export evidence as CSV. Platform admins see which tenants and servers drive the most sensitive traffic.


Demo 1: Gateway Status and Config ​

Duration: 2 minutes
Story: Show live gateway health, transport label, server counts, and rolling 24h activity; then tighten or relax the org-wide default scan depth.

What to show ​

  1. GET /api/mcp/status
    Walk through the response fields:

    • enabled: master switch for the org’s gateway experience (when false, status reports health: offline)
    • default_scan_depth: org default for DataIntel when per-tool resolution falls through (light, standard, deep, maximum)
    • transport: persisted label from config (for example stdio + SSE)
    • upstream_servers, connected_servers: inventory and connectivity snapshot
    • tool_calls_today, pii_found_today: derived from last 24 hours of mcp_audit_log for this organization (naming says “today” but matches the 24h audit window in service code)
  2. PUT /api/mcp/config with a JSON body such as:

json
{
  "enabled": true,
  "default_scan_depth": "deep"
}

Valid values for default_scan_depth are exactly: light, standard, deep, maximum. Invalid values return 400.

  1. Call GET /api/mcp/status again and confirm default_scan_depth and health reflect the change.

Talking points ​

"This is the control plane for MCP in your tenant. default_scan_depth is the floor when we do not have a sharper signal—everything still goes through our DataIntel stack, but depth scales with risk."

"light is pattern-forward and fast; maximum pulls in the heaviest detectors and anti-exfil posture. Most production orgs stay on standard or deep and use per-tool overrides for the sensitive paths."


Demo 2: Register MCP Servers ​

Duration: 3 minutes
Story: Add an upstream MCP server — show the two connection modes (URL and Command), automatic connection testing, and authentication support.

What to show ​

  1. In the admin UI, click + Add Server and show the transport selector:

    • URL mode — paste a server URL (e.g. https://mcp.granola.ai/mcp). The name auto-suggests from the hostname. The backend auto-generates the mcp-remote bridge command — the user never needs to know about it.
    • Command mode — enter a local command (e.g. npx) and arguments.
  2. Show the data sensitivity selector (Public / Internal / Confidential / Regulated) — explain that this drives DataIntel scan depth.

  3. Show the Authentication section (URL mode only) — a collapsible toggle for servers that need a bearer token or API key. Token is encrypted at rest and never returned by the API.

  4. Click Add & Connect — the modal shows an inline spinner, adds the server, and automatically runs a connection test:

    • Success: green check + "Connected — N tools discovered" with tool name chips
    • Auth required: amber "Authentication required" state with an Authorize with OAuth button that opens a browser popup for consent
    • Error: red error with detail and Retry button
  5. Alternatively via API:

json
{
  "name": "lab-docs",
  "endpoint": "https://mcp.example.com/mcp",
  "classification": "internal",
  "auth_token": "optional-bearer-token"
}

Field contract (from AddServerRequest):

  • name: unique per organization (duplicate 409)
  • endpoint: URL (auto-bridges via mcp-remote) or connection target
  • classification: public, internal, confidential, regulated — higher classifications raise baseline scan depth
  • auth_token: optional bearer token, encrypted at rest (AES-256-GCM)
  • command, args, env: optional stdio-style launch metadata (auto-generated for URL servers)
  1. POST /api/mcp/servers/{name}/test — test connection and discover tools. Returns connected, auth_required, or error.

  2. GET /api/mcp/servers — show ordered list with id, tool_count, status, has_auth_token, command, args, env, created_at.

Talking points ​

"Users paste a URL and click connect. We handle the mcp-remote bridge, the connection test, even the OAuth flow — they never touch a config file."

"If the server needs OAuth, we detect it automatically from the connection attempt, then walk the user through browser-based consent. Tokens are encrypted at rest."

"Classification is not cosmetic: it feeds the maximum of auto-classified tool risk and server classification, so a regulated server never gets light scans by default."


Demo 3: Tool Security Profiles ​

Duration: 2 minutes
Story: Show per-tool, per-server DataIntel posture: auto_risk (baseline) and optional override_risk that forces low, medium, high, or critical scanning tiers.

What to show ​

  1. GET /api/mcp/profiles — list rows with tool_name, server_name, auto_risk, override_risk.

  2. PUT /api/mcp/profiles/{tool_name} with a body that pins the server and optionally overrides risk:

json
{
  "server_name": "lab-docs",
  "auto_risk": "high",
  "override_risk": "critical"
}

Path parameter tool_name is the MCP tool identifier (URL-encoded if it contains special characters). Invalid risk strings return 400.

  1. Explain resolution (matches ToolRiskProfile / resolve_scan_depth in mcp_proxy.py):

    • override_risk maps directly to a scan depth (low→light, medium→standard, high→deep, critical→maximum)
    • Without override, GhostAI takes the higher of name-based auto_risk heuristics and the server’s classification-derived risk
    • Org default_scan_depth applies when explicit override logic delegates to defaults in the proxy configuration path
  2. Tie to PII: inbound tool arguments and outbound responses are scanned at the resolved depth before data crosses trust boundaries; direction in audit rows distinguishes outbound vs return paths.

Talking points ​

"You are not stuck with one sensitivity level for the whole MCP catalog. High-risk tools—think CRM search or write-back—can be pinned to critical / maximum while ping stays light."


Demo 4: Audit Trail ​

Duration: 3 minutes
Story: Prove every gated call leaves evidence: who or what invoked which tool, on which server, how many PII hits, what action was taken, and which scan depth ran.

What to show ​

  1. GET /api/mcp/audit?period=24h (also 7d, 30d)
    Each entry includes: timestamp, agent_or_user, tool_name, server_name, pii_count, action (passed, tokenized, blocked, etc.), scan_depth, direction (outbound vs inbound/response side).

  2. GET /api/mcp/audit/stats?period=7d
    Aggregates: total_calls, pii_found (sum of pii_count), tokenized (PII counts on rows whose action is tokenized), blocked (count of rows whose action is blocked).

  3. GET /api/mcp/audit/export?period=30d
    Downloads text/csv with header
    Content-Disposition: attachment; filename=mcp-audit-30d.csv.
    Columns: timestamp, agent_or_user, tool_name, server_name, pii_count, action, scan_depth, direction (up to 10,000 rows per export in service code).

  4. Mention SIEM: successful writes also emit mcp.tool_call-style events when SIEM integration is configured (mcp_gateway_service.write_audit).

Talking points ​

"This is the compliance slide: not just that we scan, but what we scanned, how hard, and what we did—pass, tokenize, or block—with CSV you can drop into GRC workflows."


Demo 5: Platform Overview ​

Duration: 2 minutes
Story: Shift to platform admin visibility—cross-tenant aggregates without impersonating a customer org.

What to show ​

  1. GET /api/mcp/platform/overview
    Returns organizations_enabled, total_servers, connected_servers, and 24h totals: total_calls_24h, pii_found_24h, tokenized_24h, blocked_24h.

  2. GET /api/mcp/platform/top-servers
    Top servers by call volume in the last 24h: server_name, calls, pii_found.

  3. GET /api/mcp/platform/top-tools
    Top tool/server pairs by PII volume (ordered by pii descending): tool_name, server_name, calls, pii_found.

  4. GET /api/mcp/platform/per-tenant
    Per-organization rows: organization_id, organization_name, calls_24h, pii_found_24h, servers (registered upstream count).

Talking points ​

"Org admins see their own footprint; platform admins see where MCP risk concentrates across the estate—useful for capacity planning, incident response, and prioritizing which server integrations need review."

"Every platform route still sits behind mcp_tools at the router level, but authorization steps up to platform admin so tenant isolation stays intact for normal users."


Demo Flow Summary ​

#TopicDurationPrimary endpoints
1Gateway status & config~2 minGET /api/mcp/status, PUT /api/mcp/config
2Register servers~3 minPOST/GET/DELETE /api/mcp/servers
3Tool security profiles~2 minGET /api/mcp/profiles, PUT /api/mcp/profiles/{tool_name}
4Audit trail & CSV~3 minGET /api/mcp/audit, GET /api/mcp/audit/stats, GET /api/mcp/audit/export
5Platform overview~2 minGET /api/mcp/platform/overview, .../top-servers, .../top-tools, .../per-tenant

Objection Handling (Optional) ​

  • "Does this slow every tool call?" — Depth is per tool; low-risk tools stay on light unless you override. Latency scales with depth, not a single global maximum.
  • "Can developers bypass the gateway?" — Tenant MCP tool execution is product-gated by mcp_tools and admin registration; audit rows document the path when the proxy participates.
  • "We need tenant-of-tenants reporting." — /api/mcp/platform/per-tenant is the starting point; pair with your billing or CRM org IDs for executive rollups.

After the Demo ​

  • Offer the companion lab: generated-content/lab-guides/mcp-gateway-full-lab.md for hands-on curl exercises.
  • Point security reviewers at mcp_proxy.py (DataIntel ScanDepth enum and ToolRiskProfile) and mcp_gateway_service.py (persistence and aggregates).

SOC 2 Type II Certified | BAA Available | HIPAA-Ready