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)

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Server Type Patterns

stdio Servers (Local Process):

{
  "filesystem": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"],
    "env": {}
  }
}

SSE Servers (Remote HTTP):

{
  "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:

{
  "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:

{
  "github": {
    "type": "stdio",
    "command": "github-mcp-server",
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

Never hardcode tokens in configuration files.

3. Specify Exact Package Versions:

{
  "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

{
  "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

# 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
• GitHub Copilot MCP Configuration
• CIA `.github/copilot-mcp-config.json`