Add comprehensive GitHub MCP Server configuration and access control specification

[Copilot]

Provides complete W3C-style specification for GitHub MCP server configuration, documenting all 9 existing configuration fields and introducing 3 new access control extensions for repository scoping, role-based permissions, and public/private boundaries at the MCP Gateway layer.

Configuration Fields

Existing GitHub MCP Server Features (Complete Documentation)

mode - Deployment mode selection

tools:
  github:
    mode: "remote"    # Recommended: Hosted service (fast, automatic updates)
    mode: "local"     # Docker-based (specific versions, air-gapped)

Mode Comparison:

• Remote: Hosted at https://api.githubcopilot.com/mcp/, fast initialization, no Docker required
• Local: Docker container, slower startup, version pinning, air-gapped support

toolsets - Toolset-based tool selection (recommended)

tools:
  github:
    toolsets: [default]           # Recommended default toolsets
    toolsets: [repos, issues]     # Specific toolsets only
    toolsets: [all]               # All available toolsets

tools - Individual tool filtering (alternative)

tools:
  github:
    tools:
      - "get_repository"
      - "get_file_contents"
      - "list_issues"

read-only - Write operation restrictions

tools:
  github:
    read-only: true     # Default: only read operations allowed (security)
    read-only: false    # Enable write operations

github-token - Custom authentication token

tools:
  github:
    github-token: "${{ secrets.CUSTOM_GITHUB_PAT }}"

version - Docker image pinning (local mode only)

tools:
  github:
    mode: "local"
    version: "v1.2.3"   # Pin to specific version

args - Docker runtime arguments (local mode only)

tools:
  github:
    mode: "local"
    args: ["--network", "host", "--memory", "2g"]

lockdown - Repository isolation

tools:
  github:
    lockdown: true      # Only triggering repository accessible
    lockdown: false     # All token-accessible repositories available
    # Omitted: Auto-detect based on repo visibility (private=true, public=false)

app - GitHub App authentication

tools:
  github:
    app:
      app-id: "${{ vars.GITHUB_APP_ID }}"
      private-key: "${{ secrets.GITHUB_APP_PRIVATE_KEY }}"
      owner: "myorg"
      repositories: ["repo1", "repo2"]

Access Control Extensions (This Specification)

repos - Repository scoping with wildcards

tools:
  github:
    repos:
      - "myorg/frontend"      # Exact match
      - "myorg/*"             # Owner wildcard
      - "*/infrastructure"    # Name wildcard

roles - Permission-based filtering

tools:
  github:
    roles:
      - "write"
      - "admin"
      - "maintain"

private-repos - Visibility enforcement

tools:
  github:
    private-repos: false  # Public repos only

Specification Structure

• Format: W3C-style with RFC 2119 conformance (49 requirement keywords)
• Conformance: Two levels (Basic: exact matching, Complete: full feature set)
• Security Model: Three-layer enforcement (compilation validation, gateway middleware, audit logging)
• Testing: 40 compliance tests (T-rejig docs #1 to T-Remove Gemini engine and all references from codebase #40)
• Integration: Extends MCP Gateway schema, follows Safe Inputs pattern
• Documentation: Complete coverage of all 9 existing GitHub MCP server fields + 3 new access control fields

Architecture

Access control enforced at gateway middleware layer:

1. Tool selection filters available MCP tools (via toolsets or tools)
2. Agent invokes tool with repository parameter
3. Extract repository identifier from tool parameters
4. Match against repos patterns (OR logic)
5. Verify user role via GitHub API against roles
6. Check repository visibility against private-repos
7. Allow/deny with structured audit logging

Key Principle: Tool selection determines what operations are possible; access control determines where operations are permitted.

File

specs/github-mcp-access-control-specification.md (2,026 lines)

• 10 core technical sections
• Section 4.2: Complete documentation of all 9 GitHub MCP server configuration fields:
  1. mode - Remote vs local deployment
  2. toolsets - Toolset-based tool selection
  3. tools - Individual tool filtering
  4. read-only - Write operation restrictions
  5. github-token - Custom authentication
  6. version - Docker image pinning (local mode)
  7. args - Docker runtime arguments (local mode)
  8. lockdown - Repository isolation
  9. app - GitHub App authentication
• Section 4.4: Access control fields (repos, roles, private-repos)
• Section 4.5: Relationship between tool selection and access control
• Section 4.6: Configuration validation
• 3 appendices (examples, error messages, security considerations)
• 11 configuration examples covering all features and common use cases:
  • A.1-A.7: Basic access control patterns
  • A.8: Local mode with version pinning
  • A.9: Read-only mode with defense-in-depth security
  • A.10: Lockdown mode for repository isolation
  • A.11: GitHub App authentication with fine-grained permissions
• Complete threat model and mitigation strategies

Custom agent used: w3c-specification-writer
AI technical specification writer following W3C conventions and best practices for formal specifications

Original prompt

Generate a w3c style specification of a GitHub MCP server of the MCP gateway specification

• allows defining allowed-repos to scope repo accessible by the GitHub MCP (supports wildcards)

  • allowed-repos: string array

• allows restricting items to user/owner role (eg only import issues with role writer or above)

  • allowed-roles: string array

• enforces public / private rules/boundaries (private off)

  • allow-private-repos: true

Similar to safe inputs in terms of integration in the MCP gateway

Custom agent used: w3c-specification-writer
AI technical specification writer following W3C conventions and best practices for formal specifications

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[pelikhan]

@copilot add support for existing GitHub tool features : toolsets and tools

[Copilot]

@copilot add support for existing GitHub tool features : toolsets and tools

Added comprehensive documentation for toolsets and tools fields in commit 7e6f581.

Changes:

• Section 4.2.1: Documents toolsets field (existing GitHub MCP feature)
• Section 4.2.2: Documents tools field (also known as allowed)
• Section 4.4: Explains relationship between tool selection and access control
• Appendix A.7: Example demonstrating tools field usage

The specification now clarifies how tool selection (toolsets/tools) and access control (allowed-repos, allowed-roles, allow-private-repos) work together:

• Tool selection controls what operations are possible
• Access control controls where operations are permitted

[pelikhan]

@copilot rename allowed-repos to repos, allowed-roles to roles,

[Copilot]

@copilot rename allowed-repos to repos, allowed-roles to roles,

Renamed fields in commit de21a52:

• allowed-repos → repos
• allowed-roles → roles

Updated throughout the specification including examples, error messages, test descriptions, compliance checklist, and change log.

[pelikhan]

@copilot rename allow-private-repos to private-repos

[pelikhan]

@copilot add remote vs local mode for completion

[Copilot]

@copilot rename allow-private-repos to private-repos

Renamed field in commit 42cedc1:

• allow-private-repos → private-repos

Updated throughout the specification including examples, error messages, test descriptions, compliance checklist, and change log.

[Copilot]

@copilot add remote vs local mode for completion

Added mode field documentation in commit 016b136.

Changes:

• Section 4.2.1: Documents mode field with remote vs local deployment options
• Comparison table showing deployment characteristics, authentication differences, and use cases
• Best practices for mode selection (remote recommended for production)
• Example A.8: Local mode configuration example

Mode options:

• "remote" (default): Hosted service, fast initialization, automatic updates
• "local": Docker-based, version pinning, air-gapped support

[pelikhan]

@copilot review specification and current tools.github implementation to spot missed features (some features are new like repos/role).

[Copilot]

@copilot review specification and current tools.github implementation to spot missed features (some features are new like repos/role).

Reviewed implementation in pkg/workflow/tools_types.go and pkg/workflow/mcp_github_config.go. Found and added 6 missing features in commit 03a3c66:

Added Documentation:

1. read-only (4.2.4) - Write operation restrictions (default: true)
2. github-token (4.2.5) - Custom authentication token
3. version (4.2.6) - Docker image pinning for local mode
4. args (4.2.7) - Docker runtime arguments for local mode
5. lockdown (4.2.8) - Repository isolation (auto-detected by repo visibility)
6. app (4.2.9) - GitHub App authentication with fields: app-id, private-key, owner, repositories

Added Examples:

• A.9: Read-only mode with access control (defense-in-depth security)
• A.10: Lockdown mode for single repository (repository isolation)
• A.11: GitHub App authentication with access control (fine-grained permissions)

The specification now documents all 9 GitHub MCP server configuration fields with 11 comprehensive examples.