How to fix MCP authentication and permission errors

1# Common authentication error messages:
2
3# Missing credentials:
4# "Error: API_KEY environment variable is not set"
5# "Missing required configuration: GITHUB_PERSONAL_ACCESS_TOKEN"
6
7# Invalid credentials:
8# "401 Unauthorized"
9# "Invalid API key"
10# "Bad credentials"
11# "Authentication failed"
12
13# Insufficient permissions:
14# "403 Forbidden"
15# "Permission denied"
16# "Insufficient scopes. Required: repo, read:org"
17# "Resource not accessible by personal access token"
18
19# Check logs:
20tail -n 30 ~/Library/Logs/Claude/mcp*.log | grep -i -E "auth|401|403|key|token|permission"

1// Check your config matches the server's expected variable names
2
3// GitHub server expects:
4{
5  "env": {
6    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
7  }
8}
9// NOT: "GITHUB_TOKEN" or "GH_TOKEN" — the name must match exactly
10
11// Slack server expects:
12{
13  "env": {
14    "SLACK_BOT_TOKEN": "xoxb-xxxxxxxxxxxx",
15    "SLACK_TEAM_ID": "T01234567"
16  }
17}
18
19// Common pattern — check the server's documentation:
20// @modelcontextprotocol/server-github → GITHUB_PERSONAL_ACCESS_TOKEN
21// @modelcontextprotocol/server-slack → SLACK_BOT_TOKEN + SLACK_TEAM_ID
22// @modelcontextprotocol/server-brave-search → BRAVE_API_KEY

1# Test a GitHub token directly:
2curl -H "Authorization: token ghp_your_token_here" \
3  https://api.github.com/user
4# Should return your user profile JSON. 401 = invalid token.
5
6# Test a Brave Search API key:
7curl "https://api.search.brave.com/res/v1/web/search?q=test" \
8  -H "X-Subscription-Token: your-brave-key"
9# Should return search results. 401 = invalid key.
10
11# Check GitHub token permissions:
12curl -H "Authorization: token ghp_your_token_here" \
13  https://api.github.com/rate_limit
14# Shows rate limit info if token is valid

1# GitHub token scopes needed for the MCP GitHub server:
2# - repo (full repository access)
3# - read:org (read organization data)
4# - gist (optional, for gist operations)
5
6# To create a new GitHub token with correct scopes:
7# 1. Go to github.com/settings/tokens
8# 2. Click 'Generate new token (classic)'
9# 3. Select scopes: repo, read:org
10# 4. Generate and copy the token
11# 5. Update your MCP config env block
12
13# The error message often tells you what is needed:
14# "Insufficient scopes. Required: repo, read:org"
15# → Your token is missing those scopes

1// Add to your server's entry point
2async function validateCredentials() {
3  const apiKey = process.env.API_KEY;
4  if (!apiKey) {
5    console.error("ERROR: API_KEY environment variable is required.");
6    console.error("Add it to your MCP host config:");
7    console.error('  "env": { "API_KEY": "your-key-here" }');
8    process.exit(1);
9  }
10
11  // Optional: test the key with a lightweight API call
12  try {
13    const res = await fetch("https://api.example.com/ping", {
14      headers: { Authorization: `Bearer ${apiKey}` },
15    });
16    if (!res.ok) {
17      console.error(`ERROR: API key validation failed (${res.status})`);
18      console.error("Check that your API key is valid and not expired.");
19      process.exit(1);
20    }
21    console.error("API key validated successfully.");
22  } catch (error) {
23    console.error("WARNING: Could not validate API key:", error.message);
24  }
25}
26
27await validateCredentials();