MCP Setup & Configuration

MCP Setup & Configuration

Configuration Guide

This guide walks you through setting up and configuring MCP (Model Context Protocol) servers for use with Claude Code in the astro-basics project.

Prerequisites

Before setting up MCP servers, ensure you have:

• Claude Code CLI installed and configured
• Node.js 18+ (for JavaScript-based servers)
• Python 3.8+ (for Python-based servers)
• Git for cloning server repositories
• API Keys for external services (detailed below)

Installation Methods

NPM Packages

Install MCP servers as npm packages:

Install via NPM

# Core MCP servers
npm install -g @anthropic/mcp-server-filesystem
npm install -g @anthropic/mcp-server-github
npm install -g @anthropic/mcp-server-postgres

# Specialized servers
npm install -g @astrojs/mcp-server-docs
npm install -g @supabase/mcp-server
npm install -g @clerk/mcp-server

Source Installation

Clone and install from source:

Install from Source

# Create MCP servers directory
mkdir ~/.mcp-servers
cd ~/.mcp-servers

# Clone specific servers
git clone https://github.com/microsoft/playwright-mcp-server.git
git clone https://github.com/figma/figma-mcp-server.git
git clone https://github.com/netlify/netlify-mcp-server.git

# Install dependencies
cd playwright-mcp-server && npm install
cd ../figma-mcp-server && npm install
cd ../netlify-mcp-server && npm install

Docker

Run MCP servers in containers:

Docker Compose Setup

# Create docker-compose.yml
version: '3.8'
services:
mcp-playwright:
  image: mcpservers/playwright:latest
  ports:
    - "3001:3000"
  environment:
    - BROWSER_HEADLESS=true

mcp-supabase:
  image: mcpservers/supabase:latest
  ports:
    - "3002:3000"
  environment:
    - SUPABASE_URL=${SUPABASE_URL}
    - SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}

# Start containers
docker-compose up -d

Configuration File

Create a configuration file to register your MCP servers:

1. Create configuration directory:

   mkdir -p ~/.claude-code/mcp

2. Create server configuration (~/.claude-code/mcp/servers.json):

   {
     "servers": {
       "astro-docs": {
         "command": "npx",
         "args": ["@astrojs/mcp-server"],
         "description": "Astro framework documentation search"
       },
       "playwright": {
         "command": "node",
         "args": ["~/.mcp-servers/playwright-mcp-server/dist/index.js"],
         "description": "Browser automation and testing",
         "env": {
           "PLAYWRIGHT_BROWSERS_PATH": "/usr/bin"
         }
       },
       "supabase": {
         "command": "npx",
         "args": ["@supabase/mcp-server"],
         "description": "Database operations and project management",
         "env": {
           "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
         }
       },
       "context7": {
         "command": "npx",
         "args": ["@context7/mcp-server"],
         "description": "Library documentation retrieval"
       },
       "figma": {
         "command": "node",
         "args": ["~/.mcp-servers/figma-mcp-server/dist/index.js"],
         "description": "Design-to-code generation",
         "env": {
           "FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"
         }
       },
       "clerk": {
         "command": "npx",
         "args": ["@clerk/mcp-server"],
         "description": "Authentication and user management",
         "env": {
           "CLERK_SECRET_KEY": "${CLERK_SECRET_KEY}"
         }
       },
       "ide": {
         "command": "npx",
         "args": ["@vscode/mcp-server"],
         "description": "IDE integration and diagnostics"
       },
       "netlify": {
         "command": "node",
         "args": ["~/.mcp-servers/netlify-mcp-server/dist/index.js"],
         "description": "Deployment and hosting management",
         "env": {
           "NETLIFY_ACCESS_TOKEN": "${NETLIFY_ACCESS_TOKEN}"
         }
       },
       "web-tools": {
         "command": "npx",
         "args": ["@anthropic/mcp-server-web"],
         "description": "Web search and content fetching"
       },
       "mcp-generic": {
         "command": "npx",
         "args": ["@anthropic/mcp-server-filesystem", "--root", "./"],
         "description": "Generic MCP resource operations"
       }
     }
   }

3. Set file permissions:

   chmod 600 ~/.claude-code/mcp/servers.json

Environment Variables

Set up the required environment variables for authenticated services:

Environment Setup

# Create environment file
cat > ~/.claude-code/mcp/.env << 'EOF'
# Supabase Configuration
SUPABASE_ACCESS_TOKEN=sb_your_access_token_here
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your_anon_key_here

# Clerk Configuration
CLERK_SECRET_KEY=sk_test_your_secret_key_here
CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

# Figma Configuration
FIGMA_ACCESS_TOKEN=figd_your_access_token_here

# Netlify Configuration
NETLIFY_ACCESS_TOKEN=netlify_your_access_token_here

# GitHub Configuration (if using)
GITHUB_TOKEN=ghp_your_personal_access_token_here
EOF

# Secure the environment file
chmod 600 ~/.claude-code/mcp/.env

API Keys & Authentication

Supabase

Required for database operations

1. Go to Supabase Dashboard
2. Select your project
3. Go to Settings > API
4. Copy the URL and anon/public key
5. For management operations, create an access token:
   • Go to Account > Access Tokens
   • Click Generate new token
   • Copy the token

Tip

The anon key is safe for client-side use, but the access token should be kept secure.

Clerk

Required for authentication management

1. Go to Clerk Dashboard
2. Select your application
3. Go to Developers > API Keys
4. Copy the Secret Key (starts with sk_)
5. Optionally copy the Publishable Key (starts with pk_)

Caution

Never expose your secret key in client-side code or public repositories.

Figma

Required for design-to-code features

1. Go to Figma Account Settings
2. Scroll to Personal access tokens
3. Click Generate new token
4. Give it a descriptive name (e.g., “MCP Server Access”)
5. Copy the token (starts with figd_)

Note

Figma tokens provide access to all files you can view. Use team tokens for organization-wide access.

Netlify

Required for deployment operations

1. Go to Netlify User Settings
2. Scroll to Personal access tokens
3. Click New access token
4. Give it a descriptive name
5. Copy the generated token

Tip

Netlify tokens inherit your account permissions. Ensure your account has access to the sites you want to manage.

Verification & Testing

Test your MCP server configuration:

1. Check server status:

   claude-code mcp list

2. Test individual servers:

   # Test Astro docs search
   claude-code mcp test astro-docs --function search_astro_docs --args '{"query": "components"}'
   
   # Test Supabase connection
   claude-code mcp test supabase --function list_projects
   
   # Test Playwright browser
   claude-code mcp test playwright --function browser_navigate --args '{"url": "https://example.com"}'

3. Verify authentication:

   # This should return your projects/resources
   claude-code mcp test supabase --function list_projects
   claude-code mcp test clerk --function get_user_count
   claude-code mcp test netlify --function get_sites

Common Configuration Issues

Path Issues

Problem: Server command not found

Solution: Use full paths or ensure executables are in PATH

{
  "command": "/usr/local/bin/node",
  "args": ["/full/path/to/server/dist/index.js"]
}

Environment Variables

Problem: Environment variables not loading

Solution: Check file permissions and syntax

# Check permissions (should be 600)
ls -la ~/.claude-code/mcp/.env

# Test variable loading
source ~/.claude-code/mcp/.env && echo $SUPABASE_ACCESS_TOKEN

Port Conflicts

Problem: Server port already in use

Solution: Change server port or stop conflicting service

# Find what's using the port
lsof -i :3000

# Use different port
"env": {
  "PORT": "3001"
}

Network Issues

Problem: Cannot connect to external APIs

Solution: Check firewall and network settings

# Test API connectivity
curl -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
     https://api.supabase.com/v1/projects

# Check DNS resolution
nslookup api.supabase.com

Security Best Practices

• Environment Files: Keep .env files out of version control
• File Permissions: Set restrictive permissions (600) on config files
• Token Rotation: Regularly rotate API tokens and access keys
• Least Privilege: Use tokens with minimal required permissions
• Monitoring: Monitor server logs for unauthorized access attempts

Next Steps

With MCP servers configured, explore:

• Server Documentation - Detailed guides for each server
• Usage Examples - Real-world implementation scenarios
• Troubleshooting - Solutions to common problems

Advanced Configuration

For advanced scenarios, see:

• Custom server development
• Load balancing multiple server instances
• Server monitoring and logging
• Integration with CI/CD pipelines