Mobile AI App Gateway (POC)

Note: This project code was created with Cursor using Codex 5.3.

API gateway for a mobile AI agent. It connects the mobile app to:

• remote MCP servers (Meraki and Catalyst)
• AWS Bedrock for AI-generated insights
• inventory and operational data endpoints exposed by MCP tools

This gateway can be used by mobile apps, websites, chatbots, and messaging apps. It returns JSON-formatted data and AI insights.

Core API endpoints:

• GET /api/v1/health
• GET /api/v1/platforms
• POST /api/v1/query

The gateway is designed to return inventory plus concise, high-impact AI insights to the mobile app. It uses remote MCP servers via streamable HTTP(S) transport.

Core code files

• app/api_gateway.py - FastAPI endpoints and request orchestration.
• app/mcp_transport_client.py - MCP streamable HTTP(S) client for tool calls.
• app/ai_insights.py - AI insights integration (AWS Bedrock wrapper).

Quick start

Target platform: macOS/Linux shell environments.

1. Create env file:

cp environment.env.example environment.env

Set API key config in environment.env:

• API_KEY_HEADER_NAME=x-api-key
• API_KEYS=<your-strong-key> (comma-separated list supported)

2. Install dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Create local TLS certs:

make certs

4. Run API (module-based startup):

make up

make up now:

• stops any existing API process on 3040
• starts this gateway API on 3040

To stop API on port 3040:

make down

API endpoints:

• https://localhost:3040/api/v1/health
• https://localhost:3040/api/v1/platforms
• https://localhost:3040/api/v1/query

Authentication:

• GET /api/v1/health is open (no API key)
• GET /api/v1/platforms and POST /api/v1/query require API key header

Bedrock behavior:

• Bedrock insights are enabled by default via USE_BEDROCK=true in environment.env.example.
• If Bedrock credentials/model are unavailable, set USE_BEDROCK=false for local fallback insights.

MCP prerequisites (remote streamable HTTP(S))

mobile_ai_app_gateway expects:

• MERAKI_MCP_URL=https://<mcp-server-host>:8001/mcp
• CATALYST_MCP_URL=https://<mcp-server-host>:8000/mcp
• MCP_API_KEY=<shared-mcp-server-key> (sent as X-API-Key to both remote MCP servers)
• MCP_VERIFY_TLS=false for self-signed certs (POC), or set MCP_CA_CERT and keep verify enabled.

Quick endpoint checks

make status

Authenticated smoke test (/api/v1/platforms):

curl -k -H "x-api-key: <your-api-key>" https://127.0.0.1:3040/api/v1/platforms

POST /api/v1/query uses a strict single-source request contract:

• source: meraki or catalyst (single value only)
• scope: exactly one selector field matching the selected source:
  • Meraki: {"meraki_organization":"OrgName"}
  • Catalyst: {"catalyst_cluster":"ClusterName"}
• choose one query style:
  • api_endpoint (POC-first; maximum flexibility)
  • entity (mapped endpoint routing)
• optional params for endpoint query parameters
  • Pagination params such as perPage are optional.
  • For small lab environments, you can omit pagination params and use API defaults.
• prompt: optional text from the mobile app to steer Bedrock insights style/content
• By default, Bedrock insights are tuned for critical/high-impact findings only (short output).
• include_raw=true: returns raw payloads from underlying MCP calls
• GET /api/v1/platforms remains the inventory endpoint for catalyst clusters and meraki organizations

Supported entity values when using entity mode:

• devices (catalyst, meraki)
• site_overview (catalyst)
• device_health (catalyst)
• client_health (catalyst)
• compliance_summary (catalyst)
• compliance_detail (catalyst)
• issues (catalyst)
• meraki_alerts (meraki)

POC api_endpoint mode examples:

• Any endpoint path can be provided for the selected source in POC mode.
• Gateway executes endpoint queries with GET only.

curl -k -H "Content-Type: application/json" -X POST https://127.0.0.1:3040/api/v1/query \
  -H "x-api-key: <your-api-key>" \
  -d '{"channel":"mobile","source":"catalyst","scope":{"catalyst_cluster":"ClusterA"},"api_endpoint":"/dna/intent/api/v1/issues","include_raw":true,"include_insights":true}'

curl -k -H "Content-Type: application/json" -X POST https://127.0.0.1:3040/api/v1/query \
  -H "x-api-key: <your-api-key>" \
  -d '{"channel":"mobile","source":"meraki","scope":{"meraki_organization":"Lab"},"api_endpoint":"/organizations/{organizationId}/assurance/alerts","params":{"perPage":30},"include_raw":true,"include_insights":true}'

Entity-mode examples:

• entity: supported values:
  • devices (catalyst, meraki)
  • site_overview (catalyst)
  • device_health (catalyst)
  • client_health (catalyst)
  • compliance_summary (catalyst)
  • compliance_detail (catalyst)
  • issues (catalyst)
  • meraki_alerts (meraki) Example:

curl -k -H "Content-Type: application/json" -X POST https://127.0.0.1:3040/api/v1/query \
  -H "x-api-key: <your-api-key>" \
  -d '{"channel":"mobile","entity":"meraki_alerts","source":"meraki","scope":{"meraki_organization":"Lab"},"prompt":"Highlight only critical actions for mobile NOC users.","include_raw":true,"include_insights":true}'

Catalyst example:

curl -k -H "Content-Type: application/json" -X POST https://127.0.0.1:3040/api/v1/query \
  -H "x-api-key: <your-api-key>" \
  -d '{"channel":"mobile","entity":"issues","source":"catalyst","scope":{"catalyst_cluster":"ClusterA"},"include_raw":false,"include_insights":true}'

Scope and publishing notes

• This project is a PoC/demo and is not production-hardened.
• Do not commit environment.env; keep secrets only in local env files or a secret manager.
• This public repo intentionally uses environment.env.example as the safe template.

License

This repository is distributed under the terms in LICENSE (Cisco Sample Code License 1.1). See NOTICE for copyright information.