Appearance
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_toolsenabled 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_KEYfor Step 8 (user withis_platform_admintrue) - [ ]
curlandpython3 -m json.tool(orjq) - [ ] 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 8Verify 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.toolExpected JSON shape
You should see fields matching GatewayStatusResponse:
enabled(boolean)health:operational,degraded, oroffline(offline when gateway disabled; degraded when any upstream server has statuserror)transport: string from persisted config (default creation usesstdio + SSE)default_scan_depth:light|standard|deep|maximumupstream_servers,connected_servers,active_agentstool_calls_today,pii_found_today(rolling 24h window from audit log)
Notes
- First access creates a default
mcp_gateway_configrow for yourorganization_idif 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.toolExpected: 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.toolStep 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.toolExpected: 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.toolExpected: { "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.toolThe 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.toolExpected: 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.tool3.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.toolExpected: {"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.tool4.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.toolExpected: 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.tool4.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
connectedand 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 examplemcp_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_todayandpii_found_todaymay increase after calls (24h window).
bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
"$GHOSTAI_BASE_URL/api/mcp/status" | python3 -m json.toolIf 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.toolEquivalent:
bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
"$GHOSTAI_BASE_URL/api/mcp/audit?period=24h" | python3 -m json.toolExpected: 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.tool6.3 Aggregate stats
bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
"$GHOSTAI_BASE_URL/api/mcp/audit/stats?period=30d" | python3 -m json.toolExpected: AuditStatsResponse:
total_callspii_found— sum ofpii_countin the windowtokenized— sum ofpii_countfor rows whereactionistokenizedblocked— count of rows whereactionisblocked
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/csvContent-Disposition: attachment; filename=mcp-audit-24h.csv
7.2 Preview first lines
bash
head -n 5 mcp-audit-24h.csvExpected 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.toolExpected 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.toolExpected: 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.toolExpected: 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.toolExpected: Array of { "organization_id", "organization_name", "calls_24h", "pii_found_24h", "servers" }.
Lab Checklist
| Step | Endpoint(s) | Success criterion |
|---|---|---|
| 1 | GET /api/mcp/status | 200, JSON matches gateway status schema |
| 2 | PUT /api/mcp/config | 200, default_scan_depth updated |
| 3 | POST, GET /api/mcp/servers | 201 create, GET lists server |
| 4 | GET, PUT /api/mcp/profiles, /api/mcp/profiles/{tool_name} | 200 upsert, risks valid |
| 5 | Chat + MCP tool | Audit/log counters move or tool outcome visible |
| 6 | GET /api/mcp/audit, GET /api/mcp/audit/stats | Rows + aggregates for allowed periods |
| 7 | GET /api/mcp/audit/export | CSV file with correct header |
| 8 | GET /api/mcp/platform/* | 200 with platform admin token |
Reference: Exact Route Map (from mcp_gateway.py)
| Method | Path |
|---|---|
| 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:
ScanDepthinsecurechat/backend/app/services/mcp_proxy.py - Audit persistence:
mcp_audit_loginserts insecurechat/backend/app/services/mcp_gateway_service.py - Tool catalog entries for upstream servers:
_get_mcp_upstream_toolsinsecurechat/backend/app/services/tool_registry.py