MCP Project Configuration Skill

MCP Project Configuration

Guide for configuring MCP (Model Context Protocol) servers in projects.

Standard MCP Servers

Every project should include these MCP servers:

| Server | Type | Purpose | |--------|------|---------| | Linear | HTTP | Project/issue tracking | | GitHub | HTTP | Code management | | Chrome DevTools | stdio | Browser debugging | | Render | HTTP | Deployment management |

Configuration Files

.mcp.json (Project Root)

MCP server definitions with environment variable substitution:

{
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "headers": {
        "Authorization": "Bearer ${LINEAR_TOKEN_VAR}"
      }
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "render": {
      "type": "http",
      "url": "https://mcp.render.com/mcp",
      "headers": {
        "Authorization": "Bearer ${RENDER_TOKEN}"
      }
    }
  }
}

.claude/settings.json

Enable MCP servers for Claude Code:

{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["linear", "github", "chrome-devtools", "render"]
}

Linear Account Selection

When setting up Linear, ask which account to use:

Known Accounts

| Account | Token Variable | |---------|---------------| | Laser Focused | LASER_FOCUSED_LINEAR_TOKEN | | What If | WHAT_IF_LINEAR_TOKEN |

New Workspace

If neither account applies:

Ask user for the token environment variable name
User creates the token at https://linear.app/settings/api
User adds to their shell profile (~/.zshrc or ~/.bashrc)

Configuration

Replace LINEAR_TOKEN_VAR in .mcp.json with the chosen variable:

"linear": {
  "type": "http",
  "url": "https://mcp.linear.app/mcp",
  "headers": {
    "Authorization": "Bearer ${LASER_FOCUSED_LINEAR_TOKEN}"
  }
}

Token Environment Setup

Tokens should be stored in the user's shell profile, NOT in project files.

Where to Store Tokens

Add to ~/.zshrc or ~/.bashrc:

# Linear API Tokens
export LASER_FOCUSED_LINEAR_TOKEN="lin_api_..."
export WHAT_IF_LINEAR_TOKEN="lin_api_..."

# GitHub Personal Access Token
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_..."

# Render API Token
export RENDER_TOKEN="rnd_..."

Reload After Adding

source ~/.zshrc  # or ~/.bashrc

MCP Server Types

HTTP Servers

Use for hosted APIs with authentication:

{
  "type": "http",
  "url": "https://api.service.com/mcp",
  "headers": {
    "Authorization": "Bearer ${TOKEN_VAR}"
  }
}

stdio Servers (npx)

Use for local tools that run as processes:

{
  "command": "npx",
  "args": ["-y", "package-name@latest"]
}

stdio Servers (Local Binary)

Use for installed binaries:

{
  "command": "/path/to/binary",
  "args": ["--flag", "value"]
}

Setup Workflow

Step 1: Create .mcp.json

# In project root
touch .mcp.json

Step 2: Ask About Linear Account

"Which Linear workspace is this project for?"

Laser Focused (LASER_FOCUSED_LINEAR_TOKEN)
What If (WHAT_IF_LINEAR_TOKEN)
New workspace (provide token name)

Step 3: Configure All Servers

See mcp-templates.md for full templates.

Step 4: Create .claude/settings.json

mkdir -p .claude

Add settings to enable MCP servers.

Step 5: Verify

Start a new Claude Code session and verify MCP tools are available.

Adding Custom MCP Servers

To add a new MCP server:

Determine the server type (HTTP or stdio)
Get the URL or command
Identify required authentication
Add to .mcp.json
Add server name to enabledMcpjsonServers in settings.json

Troubleshooting

MCP Server Not Available

Check token is exported: echo $TOKEN_NAME
Verify .mcp.json syntax (valid JSON)
Check server is listed in settings.json
Restart Claude Code session

Authentication Failed

Verify token is valid (not expired)
Check token has required permissions
Ensure environment variable is set

HTTP Server Connection Failed

Check URL is correct
Verify network connectivity
Check if service is operational

For templates, see mcp-templates.md.

Agent Skills: MCP Project Configuration

Install this agent skill to your local

Skill Files