Add client-specific setup guides with detailed PAT permissions

[nehalecky]

TL;DR

Users need clear, client-specific setup instructions with explicit GitHub token permissions. Currently, setting up the remote GitHub MCP server requires guessing which of 35+ token scopes to select and figuring out different client syntax. This issue proposes adding comprehensive setup guides for Claude Code CLI, Claude Desktop, and Cursor, plus a detailed permission mapping that connects security goals to specific GitHub scopes.

---

Related Work

This proposal complements existing PR #498 which adds basic Claude Code local setup. However, #498 only covers local Docker setup and doesn't address:

1. Remote MCP server setup (the new hosted option)
2. Detailed token permissions (which scopes to grant/deny)
3. Multiple client support (Cursor, Claude Desktop)
4. Security best practices (1Password, token naming)

Our proposal can either:

• Complement add "Usage with Claude Code" section to README.md #498 by adding remote setup + security guidance
• Supersede add "Usage with Claude Code" section to README.md #498 by providing comprehensive coverage of all scenarios

---

Problem Statement

Following the successful merge of #514 which added PAT configuration examples, there's still a gap in documentation for client-specific setup instructions. Users currently need to:

1. Guess which GitHub token scopes to select from 35+ available options
2. Figure out client-specific syntax (different flags, formats)
3. Understand security implications without clear guidance

As noted in this comment on #514, users coming from Claude Code would particularly benefit from specific permission mappings that connect the security approach to actual GitHub token scopes.

This is especially challenging when different MCP servers (like Hugging Face) provide comprehensive client-specific setup instructions, setting user expectations.

Current Issues This Would Address

• Unable to authenticate with Remote Github MCP server #525: Users struggling with Cursor authentication setup
• Question for the upcoming remote server: how will authentication work? #503: Questions about authentication methods
• Authenticate with gh cli or re-use already authenticated #441: Requests for better auth integration
• General confusion about PAT scope selection (as seen in Add a Remote MCP configuration example that employs a PAT #514 comments)

Proposed Solution

Add comprehensive client-specific setup documentation that includes:

1. Client Setup Instructions

Similar to Hugging Face's approach, provide setup instructions for popular clients:

Claude Code (CLI)

# Using GitHub PAT
claude mcp add -t http github-remote https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer YOUR_GITHUB_TOKEN"

# Using 1Password integration
claude mcp add -t http github-remote https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer $(op read 'op://Private/github-mcp-token/token')"

Claude Desktop

{
  "mcpServers": {
    "github-remote": {
      "url": "https://api.githubcopilot.com/mcp/",
      "authorization_token": "YOUR_GITHUB_TOKEN"
    }
  }
}

Cursor

{
  "mcpServers": {
    "github-remote": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      }
    }
  }
}

2. MCP Server Naming Convention

We propose establishing a naming convention for MCP servers:

• Format: [provider]-[location] (e.g., github-remote, github-local)
• Benefits:
  • Clear distinction between remote and local servers
  • Prevents naming conflicts when using both
  • Consistent with other MCP integrations
  • The mcp prefix is implicit in the context

3. Detailed PAT Permissions Guide

Map high-level goals to specific GitHub scopes, addressing the need identified in #514 (comment):

Required Scopes ✅

• repo: Full repository access (code, issues, PRs)
• workflow: Update GitHub Actions workflows
• user: Read user profile information
• notifications: Access and manage notifications

Recommended Scopes 🟡

• write:org: Manage organization membership
• project: Full project board access
• gist: Create and manage code snippets
• write:packages: Upload packages to GitHub Registry
• admin:repo_hook: Manage repository webhooks

Explicitly NOT Granted 🔴

• delete_repo: Prevents accidental repository deletion
• delete:packages: Protects package dependencies
• admin:public_key: Avoids SSH key compromise
• admin:gpg_key: Prevents GPG key management issues
• codespace: No Codespaces access needed
• security_events: Security scanning not required
• read:audit_log: Sensitive audit logs excluded

4. Security Best Practices

• Token Naming: Use pattern mcp-github-[client]-[date]
• Expiration: Set to 90 days maximum
• Storage: Use password managers or secret management tools
• Rotation: Quarterly token rotation recommended

Benefits

1. Reduces setup friction - Users can get started quickly
2. Improves security - Clear guidance on minimal permissions
3. Prevents over-permissioning - Explicit "do not grant" list
4. Matches user expectations - Similar to other MCP providers
5. Helps Claude Code users - Specific guidance for CLI setup
6. Clear naming conventions - Avoid confusion between local/remote servers

Implementation

Could be added as:

• New section in README.md under "Setup Instructions"
• Separate docs/client-setup.md file
• Or integrated into existing documentation structure

References

• Community-tested setup from Add a Remote MCP configuration example that employs a PAT #514
• Specific need for permission mapping identified in #514 (comment)
• Security model discussed in various issues
• Pattern established by other MCP providers
• Related local setup work in PR add "Usage with Claude Code" section to README.md #498

Would love feedback on this approach and happy to submit a PR once we align on the structure!

[pchalasani]

{
"mcpServers": {
"github-remote": {
"url": "https://api.githubcopilot.com/mcp/",
"authorization_token": "YOUR_GITHUB_TOKEN"
}
}
}

Is this currently the way to use the remote server with claude desktop? Doesn't seem to work