GitHub Actions MCP Configuration

Expert knowledge for configuring MCP (Model Context Protocol) servers in GitHub Actions workflows, including tool permissions and multi-server coordination.

Core Expertise

MCP Server Configuration

• Single and multi-server setups
• Environment variable management
• Server initialization and validation
• Tool permission patterns

Tool Access Control

• Allowed and disallowed tool patterns
• Command-specific permissions
• Security boundaries and restrictions
• Language-specific tool configurations

MCP Server Configuration

Single MCP Server (Node.js)

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --mcp-config '{"mcpServers":{"github":{"command":"node","args":["/path/to/server.js"]}}}'

Multiple MCP Servers with Secrets

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --mcp-config '{
        "mcpServers": {
          "github": {
            "command": "node",
            "args": ["./github-mcp/dist/index.js"],
            "env": {"GITHUB_TOKEN": "${{ secrets.GITHUB_TOKEN }}"}
          },
          "postgres": {
            "command": "uvx",
            "args": ["mcp-server-postgres", "--connection-string", "${{ secrets.DB_URL }}"]
          }
        }
      }'

Python MCP Server with uv

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --mcp-config '{
        "mcpServers": {
          "data-processor": {
            "command": "uvx",
            "args": ["--from", "my-mcp-package", "run-server"],
            "env": {
              "API_KEY": "${{ secrets.API_KEY }}"
            }
          }
        }
      }'

Tool Access Control

Allow Specific Bash Commands

claude_args: |
  --allowedTools 'Bash(npm:*)' 'Bash(pytest:*)' 'Bash(cargo:*)'

Enable GitHub Actions Access

permissions:
  actions: read  # Required for CI/CD tools

claude_args: |
  --allowedTools 'Bash(gh run:*)' 'Bash(gh workflow:*)'

Allow Test and Lint Commands

claude_args: |
  --allowedTools 'Bash(npm test:*)' 'Bash(npm run lint:*)' 'Bash(pre-commit:*)'

Allow Build Commands with Restrictions

claude_args: |
  --allowedTools 'Bash(make:*)' 'Bash(docker build:*)'
  --disallowedTools 'Bash(docker push:*)' 'Bash(rm -rf:*)'

Block Dangerous Operations

claude_args: |
  --allowedTools 'Bash(docker build:*)'
  --disallowedTools 'Bash(docker push:*)' 'Bash(rm -rf:*)' 'Bash(curl:*)' 'Bash(wget:*)'

Tool Permission Reference

Always Enabled (No Configuration Needed)

• Read, Write, Edit, Glob, Grep - File operations
• mcp__github - GitHub operations
• Basic Claude Code tools

Language-Specific Tool Patterns

Build and Deployment Tools

MCP Server Best Practices

Configuration

• Always use GitHub secrets for sensitive credentials
• Validate MCP server availability before workflow execution
• Use environment variables for dynamic configuration
• Document required secrets in repository README
• Test MCP servers locally before deploying to CI

Error Handling

# Verify server availability
- run: node ./mcp-server/index.js --version

# Check environment variables
- run: env | grep API_KEY

# Test server locally
- run: |
    cd mcp-server
    npm install
    npm test

Security

• Never hardcode credentials in MCP configuration
• Use minimal required permissions for tools
• Validate server command paths
• Restrict network access when possible
• Audit MCP server dependencies

Environment-Specific Configuration

Development Environment

# development.yml
- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --max-turns 20
      --allowedTools 'Bash(npm:*)' 'Bash(git:*)'

Production Environment

# production.yml
- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --max-turns 10
      --allowedTools 'Bash(npm test:*)' 'Bash(npm run lint:*)'
      --disallowedTools 'Bash(npm publish:*)'

Multi-Repository Setup

Organization-Wide Template

# .github/workflows/claude-template.yml
name: Claude Code Template

on:
  workflow_call:
    secrets:
      ANTHROPIC_API_KEY:
        required: true
      MCP_SECRETS:
        required: false

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v5
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: |
            --mcp-config '${{ secrets.MCP_SECRETS }}'

Troubleshooting

MCP Server Errors

# Verify server availability
node ./mcp-server/index.js --version

# Check environment variables
env | grep API_KEY

# Test server locally
cd mcp-server && npm install && npm test

Tool Access Issues

# Enable specific tools
claude_args: |
  --allowedTools 'Bash(npm:*)' 'Bash(git:*)'

# Check tool syntax
# Correct: 'Bash(npm:*)'
# Wrong:   'Bash(npm *)'

# Verify additional_permissions
additional_permissions:
  actions: read

Configuration Validation

# Validate workflow syntax
actionlint .github/workflows/claude.yml

# Test locally (with act)
act -j claude

# Check workflow logs
gh run list --workflow=claude.yml

Quick Reference

Configuration Options

Required Secrets

For authentication methods and security best practices, see the github-actions-auth-security skill. For workflow design patterns, see the claude-code-github-workflows skill.