mcp-setup

Original source / Raw SKILL.md

---
name: mcp-setup
description: >
  Configure MCP (Model Context Protocol) servers for various IDEs. Includes
  setup, troubleshooting, and discovery management.
compatibility: All repositories with MCP integrations
metadata:
  version: "1.0.0"
  category: tooling
  tags:
    - mcp
    - ide-configuration
    - github-mcp
    - vscode
    - cursor
  triggers:
    - on-demand
---

# MCP Setup

Configuration and setup for MCP (Model Context Protocol) servers across different IDEs and tools.

## Overview

MCP server configurations are distributed to IDEs in different ways depending on the tool.

## Skill Contents

### Sections

- [Overview](#overview) (L24-L27)
- [IDE Configuration Paths](#ide-configuration-paths) (L48-L57)
- [Quick Reference](#quick-reference) (L58-L72)
- [References](#references) (L73-L80)
- [GitHub MCP Server](#github-mcp-server) (L81-L102)
- [Related](#related) (L103-L106)

### Available Resources

**📚 references/** - Detailed documentation
- [github mcp setup](references/github-mcp-setup.md)
- [ide configurations](references/ide-configurations.md)
- [troubleshooting](references/troubleshooting.md)

---

## IDE Configuration Paths

| IDE/Tool | Configuration File | Type |
|----------|-------------------|------|
| **Cursor** | `.cursor/mcp.json` | Repository-based |
| **VS Code** (GitHub Copilot) | `.vscode/mcp.json` | Repository-based |
| **Claude Code** | `.mcp.json` | Repository-based |
| **IntelliJ IDEA** (Copilot) | `~/.config/github-copilot/intellij/mcp.json` | User-based |
| **GitHub Copilot CLI** | `~/.copilot/mcp-config.json` | User-based |

## Quick Reference

### Automatic (Repository-based)

These IDEs automatically detect MCP configurations from the repository:
- Cursor
- VS Code (with GitHub Copilot)
- Claude Code

### Manual (User-based)

These tools require configuration in the user's home directory:
- IntelliJ IDEA (with GitHub Copilot)
- GitHub Copilot CLI

## References

| Reference | Content |
|-----------|---------|
| `references/ide-configurations.md` | Configuration paths for each IDE |
| `references/github-mcp-setup.md` | GitHub MCP server setup with Docker |
| `references/troubleshooting.md` | Common issues and solutions |

## GitHub MCP Server

The GitHub MCP server provides access to:
- Dependabot alerts
- Code security features
- Secret protection
- Security advisories
- Labels management
- Pull requests

### Prerequisites

1. **Docker** - Must be installed and running
2. **GITHUB_TOKEN** - Environment variable with your GitHub PAT
3. **Cloudflare CA Certificate** - Required for Bitso network TLS

### Readiness Check

```bash
./global/scripts/check-github-mcp-readiness.sh
```

## Related

- `java/commands/add-sonarqube-mcp-to-intellij-and-copilot-cli.md` - IntelliJ & CLI setup
- `global/scripts/check-github-mcp-readiness.sh` - GitHub MCP readiness script
<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Source: bitsoex/ai-code-instructions → global/skills/mcp-setup/SKILL.md -->
<!-- To modify, edit the source file and run the distribution workflow -->



---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/github-mcp-setup.md

```markdown
# GitHub MCP Server Setup

The GitHub MCP server runs via Docker and requires a GitHub Personal Access Token and Cloudflare CA certificates (for Bitso network).

## Contents

- [Prerequisites](#prerequisites) (L15-L20)
- [Cloudflare Certificate Setup](#cloudflare-certificate-setup) (L21-L79)
- [Readiness Check](#readiness-check) (L80-L87)
- [Manual Docker Setup (if needed)](#manual-docker-setup-if-needed) (L88-L99)
- [Server Configuration](#server-configuration) (L100-L111)
- [How Certificate Mounting Works](#how-certificate-mounting-works) (L112-L131)

---
## Prerequisites

1. **Docker** - Must be installed and running
2. **GITHUB_TOKEN** - Environment variable with your GitHub PAT
3. **Cloudflare CA Certificate** - Required for TLS verification through Bitso's network

## Cloudflare Certificate Setup

Bitso uses Cloudflare for network security, which requires custom CA certificates. Without these certificates, you'll see errors like:

```text
tls: failed to verify certificate: x509: certificate signed by unknown authority
```

### Automatic Setup (Recommended)

The readiness script will automatically search for existing Cloudflare certificates on your filesystem and copy them to the standard location:

```bash
./.cursor/scripts/check-github-mcp-readiness.sh
```

The script searches these locations for certificates:

1. Common locations first (faster): `~/Downloads`, `~/Desktop`, `~/Documents`, `/tmp`
2. Fallback: entire home directory (`~`) if not found in common locations

### Manual Setup (If Automatic Fails)

If the automatic search doesn't find certificates:

#### Option 1: Search filesystem manually

```bash
# Search for existing Cloudflare certificates anywhere on your system
find ~ -name '*cloudflare*certificate*.pem' 2>/dev/null

# Once found, create directory and copy
mkdir -p ~/cloudflare-certificates
cp /path/to/found/2025_cloudflare_ca_certificate.pem ~/cloudflare-certificates/
cp /path/to/found/2025_cloudflare_ca_certificate.crt ~/cloudflare-certificates/
```

#### Option 2: Download from Confluence

1. Download the Cloudflare CA certificates from:
   [Configure Cloudflare CA certificate to applications](https://bitsomx.atlassian.net/wiki/spaces/SEA/pages/4358963539/Configure+Cloudflare+CA+certificate+to+applications)

2. Copy to the standard location:

   ```bash
   mkdir -p ~/cloudflare-certificates
   cp ~/Downloads/2025_cloudflare_ca_certificate.pem ~/cloudflare-certificates/
   cp ~/Downloads/2025_cloudflare_ca_certificate.crt ~/cloudflare-certificates/
   ```

### Verify the Setup

```bash
ls -la ~/cloudflare-certificates/
# Should show:
# 2025_cloudflare_ca_certificate.pem
# 2025_cloudflare_ca_certificate.crt
```

## Readiness Check

Run the readiness script to verify your setup (includes certificate verification):

```bash
./global/scripts/check-github-mcp-readiness.sh
```

## Manual Docker Setup (if needed)

If the image is not available locally:

```bash
# Pull the image
docker pull ghcr.io/github/github-mcp-server:0.30.2

# If authentication is required
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
```

## Server Configuration

The GitHub MCP server is configured in read-only mode with lockdown enabled, providing access to:

- Context (current user)
- Dependabot alerts
- Code security features
- Secret protection
- Security advisories
- Labels management
- Pull requests

## How Certificate Mounting Works

The MCP configuration mounts the Cloudflare certificate into the Docker container:

```json
{
    "github": {
        "command": "docker",
        "args": [
            "run", "-i", "--rm",
            "-v", "~/cloudflare-certificates/2025_cloudflare_ca_certificate.pem:/etc/ssl/custom/cf-custom-ca.pem:ro",
            "-e", "SSL_CERT_FILE=/etc/ssl/custom/cf-custom-ca.pem",
            ...
        ]
    }
}
```

- `-v`: Mounts the local certificate file into the container (read-only)
- `-e SSL_CERT_FILE`: Tells the container to use this certificate for TLS verification
<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Source: bitsoex/ai-code-instructions → global/skills/mcp-setup/references/github-mcp-setup.md -->
<!-- To modify, edit the source file and run the distribution workflow -->


```

### references/ide-configurations.md

```markdown
# IDE Configurations

MCP server configurations for each IDE and tool.

## Repository-Based (Automatic)

These IDEs automatically detect and use MCP configurations from the repository.

### Cursor

**Configuration File:** `.cursor/mcp.json`

Cursor reads MCP configuration from the repository's `.cursor` directory.

### VS Code (with GitHub Copilot)

**Configuration File:** `.vscode/mcp.json`

VS Code with GitHub Copilot reads MCP configuration from the repository's `.vscode` directory.

### Claude Code

**Configuration File:** `.mcp.json`

Claude Code reads MCP configuration from the project root.

## User-Based (Manual)

These tools use configurations from the user's home directory and require manual setup.

### IntelliJ IDEA (with GitHub Copilot)

**Configuration File:** `~/.config/github-copilot/intellij/mcp.json`

For setup instructions, see:
`java/commands/add-sonarqube-mcp-to-intellij-and-copilot-cli.md`

### GitHub Copilot CLI

**Configuration File:** `~/.copilot/mcp-config.json`

For setup instructions, see:
`java/commands/add-sonarqube-mcp-to-intellij-and-copilot-cli.md`

## Configuration Format

All MCP configurations use the same JSON format:

```json
{
    "mcpServers": {
        "server-name": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "..."],
            "env": {
                "ENV_VAR": "value"
            }
        }
    }
}
```

## Common MCP Servers

| Server | Purpose |
|--------|---------|
| `github` | GitHub API access for PRs, security, etc. |
| `sonarqube` | SonarQube code quality analysis |
| `atlassian` | Jira and Confluence integration |
<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Source: bitsoex/ai-code-instructions → global/skills/mcp-setup/references/ide-configurations.md -->
<!-- To modify, edit the source file and run the distribution workflow -->


```

### references/troubleshooting.md

```markdown
# Troubleshooting

Common MCP configuration issues and solutions.

## Contents

- [Certificate Errors](#certificate-errors) (L14-L31)
- [Docker Issues](#docker-issues) (L32-L59)
- [Environment Variables](#environment-variables) (L60-L75)
- [IntelliJ/Copilot CLI Issues](#intellijcopilot-cli-issues) (L76-L86)
- [Readiness Checks](#readiness-checks) (L87-L99)

---
## Certificate Errors

### Error: TLS Certificate Verification Failed

```text
tls: failed to verify certificate: x509: certificate signed by unknown authority
```

**Solution**: Set up Cloudflare certificates:

```bash
mkdir -p ~/cloudflare-certificates
# Copy certificates from Downloads or find on filesystem
find ~ -name '*cloudflare*certificate*.pem' 2>/dev/null
```

See `references/github-mcp-setup.md` for detailed instructions.

## Docker Issues

### Error: Docker Image Not Found

```text
Unable to find image 'ghcr.io/github/github-mcp-server:0.30.2' locally
```

**Solution**: Pull the image manually:

```bash
docker pull ghcr.io/github/github-mcp-server:0.30.2
```

If authentication is required:

```bash
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
```

### Error: Docker Not Running

```text
Cannot connect to the Docker daemon
```

**Solution**: Start Docker Desktop or the Docker daemon.

## Environment Variables

### Error: GITHUB_TOKEN Not Set

```text
Error: GITHUB_TOKEN environment variable is required
```

**Solution**: Set the environment variable:

```bash
export GITHUB_TOKEN="your-github-pat"
```

Or add to your shell profile (`~/.zshrc` or `~/.bashrc`).

## IntelliJ/Copilot CLI Issues

### Error: MCP configuration not found

**Solution**: Ensure configuration is in the correct path:

- IntelliJ: `~/.config/github-copilot/intellij/mcp.json`
- Copilot CLI: `~/.copilot/mcp-config.json`

See `java/commands/add-sonarqube-mcp-to-intellij-and-copilot-cli.md` for setup.

## Readiness Checks

Run the readiness script to diagnose issues:

```bash
./global/scripts/check-github-mcp-readiness.sh
```

This validates:
- Docker is running
- GITHUB_TOKEN is set
- Cloudflare certificates are in place
- Docker image is available
<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Source: bitsoex/ai-code-instructions → global/skills/mcp-setup/references/troubleshooting.md -->
<!-- To modify, edit the source file and run the distribution workflow -->


```