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

[Chris112]

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

Remote MCPs are only available on Claude Code currently

[auggie246]

Unable to get the above working using PAT with proper scope
claude mcp add -t http github-remote https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer YOUR_GITHUB_TOKEN"

/mcp will show github-remote with a failed status.

│ Github-remote MCP Server                                                                        │
│                                                                                                 │
│ Status: ✘ failed                                                                                │
│ URL: https://api.githubcopilot.com/mcp/                                                         │
│                                                                                                 │
│ Error: Dynamic client registration failed: HTTP 404

[MicroBenz]

@auggie246 I got the same for cursor

2025-06-26 14:56:36.344 [error] user-github: No server info found
2025-06-26 14:56:39.969 [error] user-github: Client error for command Dynamic client registration failed: HTTP 404
2025-06-26 14:56:39.970 [info] user-github: Client closed for command
2025-06-26 14:56:39.972 [error] user-github: Error connecting to streamableHttp server, falling back to SSE: Dynamic client registration failed: HTTP 404
2025-06-26 14:56:39.972 [error] user-github: Error connecting to streamableHttp server, falling back to SSE: Dynamic client registration failed: HTTP 404
2025-06-26 14:56:39.972 [info] user-github: Connecting to SSE server
2025-06-26 14:56:43.640 [error] user-github: Client error for command Dynamic client registration failed: HTTP 404
2025-06-26 14:56:43.641 [error] user-github: Error connecting to SSE server after fallback: Dynamic client registration failed: HTTP 404
2025-06-26 14:56:43.642 [info] user-github: Client closed for command

Using Cursor on macOS

[tino]

Unable to get the above working using PAT with proper scope
claude mcp add -t http github-remote https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer YOUR_GITHUB_TOKEN"

I'm able to do so. However, I want this added to the project, and thus can't include the PAT.

Trying the option @nehalecky posted with 1Password (but then with pass):
claude mcp add -t http github-remote https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer $(pass tokens/github-mcp-token)" fails. Relevant debug log:

[DEBUG] MCP server "github": HTTP Connection error: {"url":"https://api.githubcopilot.com/mcp/","error":"Error POSTing to endpoint (HTTP 400): bad request: Authorization header is badly formatted\n","stack":"Error: Error POSTing to endpoint (HTTP 400): bad request: Authorization header is badly formatted\n\n    at $a1.send (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:1344:25035)\n    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)"}

So I guess that kind of interpolation doesn't work. I also tried ${GITHUB_PAT} and had it in the env, but same problem.

[tommaso-moro]

@nehalecky thank you for sharing this. We have updated our docs since you reported this issue, so I am closing this for now, but please let us know if you think this is still not fully addressed.