mcp-gateway-configuration

# MCP Gateway Configuration Skill ## Purpose This skill provides guidance for configuring MCP (Model Context Protocol) gateways for the CIA platform. It covers multi-server integration, tool routing, security configuration, and access control to enable secure and efficient AI-assisted development workflows. ## When to Use This Skill Apply this skill when: - ✅ Setting up or modifying `.github/copilot-mcp-config.json` - ✅ Adding new MCP servers to the gateway - ✅ Configuring tool routing between MCP servers - ✅ Setting up access control for MCP tools - ✅ Troubleshooting MCP connectivity issues - ✅ Reviewing MCP configuration for security - ✅ Integrating new data sources via MCP Do NOT use for: - ❌ MCP security hardening (use mcp-gateway-security) - ❌ General API gateway configuration (different pattern) - ❌ Application-level API design (use service layer patterns) ## MCP Architecture Overview ``` ┌─────────────────────────────────────────────┐ │ GitHub Copilot │ │ (AI Assistant Client) │ └──────────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ MCP Gateway Layer │ │ ┌─────────────────────────────────────┐ │ │ │ copilot-mcp-config.json │ │ │ │ - Server definitions │ │ │ │ - Tool routing rules │ │ │ │ - Access control policies │ │ │ └─────────────────────────────────────┘ │ └──────┬──────────┬──────────┬────────────────┘ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ GitHub │ │ Filesystem│ │ Playwright│ │ MCP │ │ MCP │ │ MCP │ │ Server │ │ Server │ │ Server │ └──────────┘ └──────────┘ └──────────┘ ``` ## Configuration Structure ### Base Configuration (`copilot-mcp-config.json`) ```json { "mcpServers": { "server-name": { "type": "stdio", "command": "command-to-run", "args": ["arg1", "arg2"], "env": { "ENV_VAR": "value" } } } } ``` ### Server Type Patterns **stdio Servers (Local Process):** ```json { "filesystem": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"], "env": {} } } ``` **SSE Servers (Remote HTTP):** ```json { "remote-server": { "type": "sse", "url": "https://mcp-server.example.com/sse", "headers": { "Authorization": "Bearer ${MCP_TOKEN}" } } } ``` ## CIA Platform MCP Servers ### Required Servers | Server | Purpose | Tools Provided | |---|---|---| | **github** | Repository operations | Issues, PRs, code search, Actions | | **filesystem** | Local file operations | Read, write, search files | | **playwright** | Browser automation | UI testing, screenshots | ### Configuration Best Practices **1. Minimize Filesystem Access:** ```json { "filesystem": { "type": "stdio", "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/home/runner/work/cia/cia" ] } } ``` Only expose the project root — never expose `/`, `/home`, or parent directories. **2. Use Environment Variables for Secrets:** ```json { "github": { "type": "stdio", "command": "github-mcp-server", "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } } } ``` Never hardcode tokens in configuration files. **3. Specify Exact Package Versions:** ```json { "args": ["-y", "@modelcontextprotocol/server-filesystem@1.2.3"] } ``` Pin versions to prevent supply chain attacks. ## Tool Routing ### Routing Principles 1. **Least Privilege** — Each server should only expose tools needed for its purpose 2. **Separation of Concerns** — Different servers for different capabilities 3. **Fail-Safe Defaults** — Tools should default to read-only when possible 4. **Audit Trail** — All tool invocations should be logged ### Tool Categories | Category | Server | Example Tools | |---|---|---| | Code Management | github | create_pull_request, push_files | | Code Analysis | github | search_code, get_file_contents | | File Operations | filesystem | read_file, write_file, search | | UI Testing | playwright | navigate, click, screenshot | | Issue Management | github | create_issue, list_issues | | CI/CD | github | list_workflows, get_job_logs | ## Access Control Configuration ### Server-Level Access Control ```json { "mcpServers": { "filesystem": { "type": "stdio", "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/home/runner/work/cia/cia" ], "env": { "ALLOWED_OPERATIONS": "read,write,search" } } } } ``` ### Directory Restrictions Allowed directories should follow the principle of least privilege: ``` ✅ /home/runner/work/cia/cia — Project root ✅ /home/runner/work/cia/cia/src — Source code ✅ /home/runner/work/cia/cia/.github — CI/CD configuration ❌ /home/runner — Too broad ❌ /etc — System configuration ❌ /tmp — Temporary files (security risk) ``` ## Troubleshooting ### Common Issues | Issue | Symptom | Resolution | |---|---|---| | Server not starting | "Failed to connect" error | Check command path and args | | Permission denied | Tool call fails | Verify filesystem paths and permissions | | Token expired | Authentication errors | Refresh environment variables | | Version mismatch | Unexpected tool behavior | Pin and update package versions | | Timeout | Tool call hangs | Check network connectivity for SSE servers | ### Diagnostic Commands ```bash # Verify MCP config syntax cat .github/copilot-mcp-config.json | python3 -m json.tool # Check if MCP server binary is available which github-mcp-server # Test filesystem server npx -y @modelcontextprotocol/server-filesystem --help # Check environment variables env | grep -i mcp env | grep -i github_token ``` ## Configuration Validation Checklist ``` □ JSON syntax is valid □ All server commands exist and are executable □ Environment variables are properly referenced (not hardcoded) □ Filesystem paths follow least privilege □ Package versions are pinned □ No secrets in configuration file □ Configuration is committed to repository □ Server definitions match documented architecture □ Access control rules are documented ``` ## ISMS Alignment | Configuration Area | ISO 27001 | NIST CSF | CIS Controls | |---|---|---|---| | Access Control | A.8.3 | PR.AC-4 | CIS 6.1 | | Secret Management | A.8.24 | PR.DS-1 | CIS 3.11 | | Configuration Mgmt | A.8.9 | PR.IP-1 | CIS 4.1 | | Audit Logging | A.8.15 | DE.AE-3 | CIS 8.2 | | Change Control | A.8.32 | PR.IP-3 | CIS 4.2 | ## References - [Model Context Protocol Specification](https://modelcontextprotocol.io/) - [GitHub Copilot MCP Configuration](https://docs.github.com/en/copilot/customizing-copilot/extending-the-capabilities-of-github-copilot-in-your-organization) - [CIA `.github/copilot-mcp-config.json`](../copilot-mcp-config.json)