Environment: Gateway
Location: /opt/mcp-servers/gateway/mcp_gateway_server.py Version: 1.0.0 Status: ✅ WORKING
Purpose
Universal MCP orchestration hub - the ONLY server AI systems need to load. Auto-discovers and routes calls to 24+ backend servers with 338 tools.
Architecture
AI System → Gateway → Auto-discovery → Backend Servers
↓
find/run/servers/index
Key Specs: - Base Directory: /opt/mcp-servers/ - Cache TTL: 300 seconds (5 minutes) - Max Parallel Calls: 10 - Call Timeout: 600 seconds (10 minutes) - Excluded: gateway, aimsg, archive, pycache, .git
Tools (4 total)
| Tool | Parameters | Description |
|---|---|---|
| find | query (req), limit, refresh | Search tools across ALL servers |
| run | calls (req) | Execute tool calls (single or batch) |
| servers | refresh, verbose | List all discovered servers |
| index | refresh | AI-friendly capability summary |
gateway.find
gateway.find({query: 'store password'})
# Returns: locker tools matching query
gateway.run
# Single call
gateway.run([{server:'track', tool:'list', args:{status:'active'}}])
# Batch parallel execution
gateway.run([
{server:'user', tool:'get_context', args:{user_id:'chris'}},
{server:'track', tool:'list', args:{status:'active'}},
{server:'context', tool:'recall', args:{query:'project'}}
])
gateway.servers
gateway.servers({refresh: true, verbose: true})
# Returns: List of all servers with tool counts
gateway.index
gateway.index({refresh: true})
# Returns: Categorized capability guide for AI
Server Discovery
Algorithm: 1. Scan /opt/mcp-servers/ directories 2. Find server file (mcp_{name}_server.py preferred) 3. Parse tools via regex patterns 4. Cache results for 5 minutes 5. Build searchable index
Hot-Reload:
- Subprocess execution = no persistent connections
- Code changes take effect on next call
- Cache refresh: servers(refresh:true)
- No server restarts needed
SERVER_PURPOSES Registry
Semantic descriptions for AI understanding:
| Server | Category | Use When |
|---|---|---|
| track | productivity | Managing projects, tasks, progress |
| contact | crm | Storing contacts, customer relationships |
| context | memory | Storing learnings, session summaries |
| locker | security | API keys, passwords, tokens (ALWAYS here!) |
| search | search | Finding info across all environments |
| voice | voice | Speaking to user, audio notifications |
| transcript | transcripts | YouTube transcripts, meeting notes |
| user | users | User profiles, preferences, auth |
| links | links | URL storage with auto-enrichment |
| kb | knowledge | Hierarchical documentation structure |
| staging | infrastructure | Pipeline processing, data staging |
| workflow | infrastructure | AI protocols (call init first!) |
| recall | memory | Memory aggregation from multiple sources |
Critical Rules
- 🔐 Credentials → ALWAYS locker, never context
- 📝 Knowledge → context for learnings
- 📊 Projects → track for tasks
- 🔍 Search → search for cross-environment
Current Status
Servers Discovered: 24 Total Tools Available: 338
assign(12), auto(12), chrono(11), contact(12), context(14), corpus(27),
delegate(49), docs(14), document-v2(26), kb(10), links(7), locker(10),
recall(3), search(29), session(28), sms(0), staging(6), synth(4),
temp(6), track(14), transcript(19), user(17), voice(1), workflow(7)
For AI Systems
- Load ONLY Gateway MCP server
- Call
gateway.index()at session start for capability overview - Use
gateway.find()to discover tools for specific tasks - Use
gateway.run()to execute tools (supports batch for efficiency)
For New Servers
- Create
/opt/mcp-servers/{name}/mcp_{name}_server.py - Define tools with docstrings or TOOLS list
- Gateway auto-discovers on next cache refresh
- Add entry to SERVER_PURPOSES for better AI comprehension
Security Assessment
✅ Subprocess isolation per call ✅ Timeout protection (600s) ✅ Parallel limit (10 concurrent) ✅ Excluded sensitive directories
Audited by McFly (a_isma) | Documented by Rocky (o_cq0c) | 2026-01-06