Skip to content

MCP Gateway Full Lab ​

Eight steps. About thirty-five minutes. From empty config to audited, profiled MCP traffic.

This lab exercises the MCP Gateway admin API implemented in securechat/backend/app/routers/mcp_gateway.py. All routes are prefixed with /api/mcp. The router applies Depends(require_feature("mcp_tools")) globally, so your organization’s subscription must include mcp_tools. Tenant-scoped endpoints require require_admin (org owner or admin). Platform endpoints require require_platform_admin.


Prerequisites ​

Before starting, ensure you have:

  • [ ] GhostAI backend running (local example: http://localhost:8000)
  • [ ] Feature mcp_tools enabled for your organization
  • [ ] Org admin API key: GHOSTAI_API_KEY (Bearer token for a user with role admin or owner)
  • [ ] Optional separate platform admin API key: GHOSTAI_PLATFORM_API_KEY for Step 8 (user with is_platform_admin true)
  • [ ] curl and python3 -m json.tool (or jq)
  • [ ] For Step 5: ability to open GhostAI chat in a browser with the same user (or another user in the same org) and enable tools

Environment variables ​

bash
export GHOSTAI_BASE_URL="http://localhost:8000"
export GHOSTAI_API_KEY="gst_..."                    # org admin
export GHOSTAI_PLATFORM_API_KEY="gst_..."           # optional; platform admin for Step 8

Verify feature and auth ​

bash
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/status"

Expected: 200.
403 — not org admin, no org membership context, or feature disabled.
401 — invalid token.


Step 1: Check Gateway Status ​

Duration: 3 minutes
Goal: Confirm the gateway row exists for your org and capture baseline enabled, default_scan_depth, and health-derived fields.

Request ​

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

Expected JSON shape ​

You should see fields matching GatewayStatusResponse:

  • enabled (boolean)
  • health: operational, degraded, or offline (offline when gateway disabled; degraded when any upstream server has status error)
  • transport: string from persisted config (default creation uses stdio + SSE)
  • default_scan_depth: light | standard | deep | maximum
  • upstream_servers, connected_servers, active_agents
  • tool_calls_today, pii_found_today (rolling 24h window from audit log)

Notes ​

  • First access creates a default mcp_gateway_config row for your organization_id if none exists (mcp_gateway_service.get_or_create_config).

Step 2: Configure the Gateway ​

Duration: 4 minutes
Goal: Set enabled and org-wide default_scan_depth; verify via status.

2.1 Enable gateway and set depth to deep ​

bash
curl -s -X PUT "$GHOSTAI_BASE_URL/api/mcp/config" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "default_scan_depth": "deep"
  }' | python3 -m json.tool

Expected: 200 with full GatewayStatusResponse body (same shape as Step 1). Confirm default_scan_depth is deep and health is not offline.

2.2 Invalid depth (sanity check) ​

bash
curl -s -o /dev/null -w "%{http_code}\n" \
  -X PUT "$GHOSTAI_BASE_URL/api/mcp/config" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_scan_depth": "paranoid"}'

Expected: 400 — only light, standard, deep, maximum are accepted.

2.3 Optional: set maximum for a high-assurance segment ​

bash
curl -s -X PUT "$GHOSTAI_BASE_URL/api/mcp/config" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_scan_depth": "maximum"}' | python3 -m json.tool

Step 3: Register an Upstream MCP Server ​

Duration: 5 minutes
Goal: Create a server record with name, endpoint, classification, and optional command / args / env; list servers.

Replace the endpoint and command/args values with targets valid in your environment. The lab uses illustrative values.

3.1 Create server ​

bash
curl -s -X POST "$GHOSTAI_BASE_URL/api/mcp/servers" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lab-filesystem",
    "endpoint": "http://127.0.0.1:8811/sse",
    "classification": "internal",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/mcp-lab"],
    "env": {
      "NODE_ENV": "production"
    }
  }' | python3 -m json.tool

Expected: 201 with UpstreamServerResponse: id, name, endpoint, classification, tool_count (initially 0), status (disconnected until tested), command, args, env, has_auth_token, created_at.

URL Auto-Bridge

When endpoint is an HTTP(S) URL and no command is specified, the backend auto-generates command: "npx" and args: ["-y", "mcp-remote", endpoint]. You don't need to know about mcp-remote.

3.2 Test the connection ​

bash
curl -s -X POST "$GHOSTAI_BASE_URL/api/mcp/servers/lab-filesystem/test" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" | python3 -m json.tool

Expected: { "status": "connected", "tools_discovered": N, "tool_names": [...] } — or "error" with a detail message. If the server requires OAuth, you'll see "status": "auth_required" with "oauth_server".

3.3 Add a URL-mode server (optional) ​

Register a URL-based MCP server to see the auto-bridge in action:

bash
curl -s -X POST "$GHOSTAI_BASE_URL/api/mcp/servers" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example-remote",
    "endpoint": "https://mcp.example.com/mcp",
    "classification": "internal"
  }' | python3 -m json.tool

The response will show "command": "npx" and "args": ["-y", "mcp-remote", "https://mcp.example.com/mcp"] — auto-generated from the URL.

3.4 Add a server with authentication (optional) ​

For servers requiring a bearer token:

bash
curl -s -X POST "$GHOSTAI_BASE_URL/api/mcp/servers" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lab-authed",
    "endpoint": "https://mcp.example.com/mcp",
    "classification": "confidential",
    "auth_token": "your-api-key-here"
  }' | python3 -m json.tool

Expected: 201 with "has_auth_token": true. The raw token is never returned.

3.5 List servers ​

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

3.3 Duplicate name (optional) ​

Repeat the POST with the same name.

Expected: 409 — Server 'lab-filesystem' already exists.

Cleanup note ​

To remove the server later:

bash
curl -s -X DELETE \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/servers/lab-filesystem" | python3 -m json.tool

Expected: {"status":"deleted","name":"lab-filesystem"}


Step 4: Set Tool Security Profiles ​

Duration: 5 minutes
Goal: Upsert a per-tool, per-server profile with auto_risk and optional override_risk.

Profiles apply to MCP tool names as seen at execution time (for example read_file from the filesystem server). Adjust tool_name to match a tool your stack actually exposes.

4.1 List existing profiles ​

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

4.2 Upsert profile for a tool ​

bash
curl -s -X PUT "$GHOSTAI_BASE_URL/api/mcp/profiles/read_file" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "lab-filesystem",
    "auto_risk": "medium",
    "override_risk": "critical"
  }' | python3 -m json.tool

Expected: 200 with ScanProfileResponse: id, tool_name, server_name, auto_risk, override_risk.

4.3 Clear override (optional) ​

Send override_risk": null to rely on auto classification vs server classification again:

bash
curl -s -X PUT "$GHOSTAI_BASE_URL/api/mcp/profiles/read_file" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "lab-filesystem",
    "auto_risk": "high",
    "override_risk": null
  }' | python3 -m json.tool

4.4 Invalid risk ​

bash
curl -s -o /dev/null -w "%{http_code}\n" \
  -X PUT "$GHOSTAI_BASE_URL/api/mcp/profiles/read_file" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_name": "lab-filesystem", "auto_risk": "extreme"}'

Expected: 400.


Step 5: Invoke a Tool Through Chat (PII Scanning) ​

Duration: 8 minutes
Goal: Drive at least one MCP tool call from GhostAI chat so the gateway proxy can scan arguments/responses and write mcp_audit_log rows you will read in Step 6.

5.1 Preconditions ​

  • Gateway enabled (Step 2).
  • Upstream server registered (Step 3); your agent connector or GhostAI runtime should mark the server connected and discover tools when that path is active in your deployment.
  • In the chat UI, open the tools picker and enable the upstream bundle for your server. In the tool catalog, upstream entries use ids of the form mcp_upstream.<server_name> (for example mcp_upstream.lab-filesystem). Enable that tool id if it appears in your session’s available tools list.

5.2 Prompt idea (example) ​

Send a message that causes the model to call an MCP tool, ideally with synthetic PII you are allowed to use in a lab (for example a fake SSN or phone number) so you can later see non-zero pii_count or tokenized / blocked actions in audit:

Use the lab-filesystem MCP server to read /tmp/mcp-lab/README.txt. 
For testing, also echo back this reference id: 078-05-1120 (fake lab id, not real PII).

5.3 What to observe ​

  • In chat: normal tool execution or a blocked / sanitized outcome depending on policy.
  • In /api/mcp/status: tool_calls_today and pii_found_today may increase after calls (24h window).
bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/status" | python3 -m json.tool

If no audit rows appear, confirm mcp_tools is on, the server is connected, the tool was enabled for the request, and your deployment wires write_audit on the execution path you are using.


Step 6: Audit Trail ​

Duration: 5 minutes
Goal: List recent audit entries and pull aggregate stats for 24h, 7d, and 30d.

6.1 List audit (default period 24h) ​

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

Equivalent:

bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/audit?period=24h" | python3 -m json.tool

Expected: Array of AuditEntryResponse objects with timestamp, agent_or_user, tool_name, server_name, pii_count, action, scan_depth, direction. Listing is limited to 100 rows per request in service code (newest first).

6.2 Seven-day window ​

bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/audit?period=7d" | python3 -m json.tool

6.3 Aggregate stats ​

bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/audit/stats?period=30d" | python3 -m json.tool

Expected: AuditStatsResponse:

  • total_calls
  • pii_found — sum of pii_count in the window
  • tokenized — sum of pii_count for rows where action is tokenized
  • blocked — count of rows where action is blocked

6.4 Invalid period ​

bash
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/audit?period=1y"

Expected: 400 — allowed values are 24h, 7d, 30d only.


Step 7: Export Audit CSV ​

Duration: 3 minutes
Goal: Download CSV for the same periods as the list endpoint.

7.1 Export last 24 hours ​

bash
curl -s -D - -o mcp-audit-24h.csv \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/audit/export?period=24h"

Inspect headers for:

  • Content-Type: text/csv
  • Content-Disposition: attachment; filename=mcp-audit-24h.csv

7.2 Preview first lines ​

bash
head -n 5 mcp-audit-24h.csv

Expected header row:

timestamp,agent_or_user,tool_name,server_name,pii_count,action,scan_depth,direction

The export includes up to 10,000 rows per call (export_audit_csv in mcp_gateway_service.py).


Step 8: Platform Overview (Cross-Tenant) ​

Duration: 5 minutes
Goal: Use platform admin credentials to read aggregate MCP usage across all organizations.

Use GHOSTAI_PLATFORM_API_KEY (Bearer for a platform admin user). If you only have an org admin key, expect 403 on these routes.

8.1 Overview ​

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

Expected keys: organizations_enabled, total_servers, connected_servers, total_calls_24h, pii_found_24h, tokenized_24h, blocked_24h.

8.2 Top servers by call volume (24h) ​

bash
curl -s -H "Authorization: Bearer $GHOSTAI_PLATFORM_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/platform/top-servers" | python3 -m json.tool

Expected: Array of { "server_name", "calls", "pii_found" }.

8.3 Top tools by PII volume (24h) ​

bash
curl -s -H "Authorization: Bearer $GHOSTAI_PLATFORM_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/platform/top-tools" | python3 -m json.tool

Expected: Array of { "tool_name", "server_name", "calls", "pii_found" }.

8.4 Per-tenant breakdown (24h) ​

bash
curl -s -H "Authorization: Bearer $GHOSTAI_PLATFORM_API_KEY" \
  "$GHOSTAI_BASE_URL/api/mcp/platform/per-tenant" | python3 -m json.tool

Expected: Array of { "organization_id", "organization_name", "calls_24h", "pii_found_24h", "servers" }.


Lab Checklist ​

StepEndpoint(s)Success criterion
1GET /api/mcp/status200, JSON matches gateway status schema
2PUT /api/mcp/config200, default_scan_depth updated
3POST, GET /api/mcp/servers201 create, GET lists server
4GET, PUT /api/mcp/profiles, /api/mcp/profiles/{tool_name}200 upsert, risks valid
5Chat + MCP toolAudit/log counters move or tool outcome visible
6GET /api/mcp/audit, GET /api/mcp/audit/statsRows + aggregates for allowed periods
7GET /api/mcp/audit/exportCSV file with correct header
8GET /api/mcp/platform/*200 with platform admin token

Reference: Exact Route Map (from mcp_gateway.py) ​

MethodPath
GET/api/mcp/status
PUT/api/mcp/config
GET/api/mcp/servers
POST/api/mcp/servers
DELETE/api/mcp/servers/{server_name}
POST/api/mcp/servers/{server_name}/test
POST/api/mcp/servers/{server_name}/authorize
GET/api/mcp/oauth/callback
GET/api/mcp/profiles
PUT/api/mcp/profiles/{tool_name}
GET/api/mcp/audit
GET/api/mcp/audit/stats
GET/api/mcp/audit/export
GET/api/mcp/platform/overview
GET/api/mcp/platform/top-servers
GET/api/mcp/platform/top-tools
GET/api/mcp/platform/per-tenant

Further Reading ​

  • DataIntel scan depths: ScanDepth in securechat/backend/app/services/mcp_proxy.py
  • Audit persistence: mcp_audit_log inserts in securechat/backend/app/services/mcp_gateway_service.py
  • Tool catalog entries for upstream servers: _get_mcp_upstream_tools in securechat/backend/app/services/tool_registry.py

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