MCP Server Management Guide¶

Comprehensive guide to managing Model Context Protocol (MCP) servers with SkillMeat, including setup, deployment, monitoring, and troubleshooting.

Overview¶

Model Context Protocol (MCP) servers extend Claude's capabilities by providing access to tools, resources, and information systems. SkillMeat enables you to manage MCP servers alongside your other artifacts with a unified interface, automatic deployment to Claude Desktop, and comprehensive health monitoring.

What This Guide Covers¶

Getting Started: Prerequisites and initial setup
Adding MCP Servers: How to register servers in your collection
Deployment: Deploying servers to Claude Desktop with dry-run and rollback
Environment Variables: Managing configuration and secrets securely
Health Monitoring: Checking server status and diagnosing issues
Web UI: Using the web interface for MCP management
CLI Commands: Command-line reference for all operations
Troubleshooting: Common issues and solutions
FAQ: Frequently asked questions

Prerequisites¶

Before managing MCP servers with SkillMeat, ensure you have:

SkillMeat installed and configured (version 2.0.0+)
Claude Desktop installed (for deployment targets)
Python 3.9+ (for SkillMeat runtime)
Git installed (for cloning repositories)
GitHub token (recommended, for private MCP server repositories)

Optional¶

ripgrep (rg) - For fast log searching during troubleshooting
jq - For command-line JSON processing of API responses

Check Your Setup¶

# Verify SkillMeat installation
skillmeat version

# Verify SkillMeat configuration
skillmeat config list

# Check Claude Desktop is installed
# macOS/Linux
ls ~/Library/Application\ Support/Claude/claude_desktop_config.json 2>/dev/null || \
  ls ~/.config/Claude/claude_desktop_config.json 2>/dev/null

# Windows (in PowerShell)
Test-Path "$env:APPDATA\Claude\claude_desktop_config.json"

Getting Started¶

Step 1: Initialize Your Collection¶

# Initialize default collection
skillmeat collection init default

# Verify collection exists
skillmeat collection list
# Output:
# Collections:
# - default (created 2024-01-15)

Step 2: Set GitHub Token (Optional but Recommended)¶

For better rate limits and access to private MCP repositories:

# Set GitHub token
skillmeat config set github-token ghp_your_token_here

# Verify token is set
skillmeat config get github-token
# Output: github-token = ****

Step 3: Test Your Setup¶

# List MCP servers (empty initially)
skillmeat mcp list

# You should see:
# No MCP servers in collection

Adding MCP Servers¶

Available MCP Servers¶

Popular MCP servers you can add:

Server	Repository	Purpose
Filesystem	`anthropics/mcp-filesystem`	File system access with sandboxing
GitHub	`anthropics/mcp-github`	GitHub repository operations
Git	`anthropics/mcp-git`	Git version control operations
Database	`anthropics/mcp-database`	SQL database operations
Google Drive	`anthropics/mcp-google-drive`	Google Drive file management
Slack	`anthropics/mcp-slack`	Slack workspace integration

Add a Server via CLI¶

Basic Addition (No Environment Variables)¶

# Add filesystem server with default settings
skillmeat mcp add filesystem anthropics/mcp-filesystem

# Verify server was added
skillmeat mcp list
# Output:
# MCP Servers:
# - filesystem (anthropics/mcp-filesystem, not_installed)

Addition with Environment Variables¶

# Add GitHub server with authentication
skillmeat mcp add github anthropics/mcp-github \
  --env GITHUB_TOKEN="your_github_token" \
  --env GITHUB_API_URL="https://api.github.com"

# Add filesystem server with root path
skillmeat mcp add filesystem anthropics/mcp-filesystem \
  --env ROOT_PATH="/home/user/projects" \
  --version v1.5.0

Addition with Description¶

# Add with description for documentation
skillmeat mcp add database anthropics/mcp-database \
  --description "Access to project SQLite database" \
  --env DB_URL="sqlite:////home/user/.skillmeat/project.db"

View Server Details¶

# Show detailed information about a server
skillmeat mcp show filesystem

# Output shows:
# Name: filesystem
# Repository: anthropics/mcp-filesystem
# Version: latest
# Status: not_installed
# Environment Variables:
#   ROOT_PATH=/home/user/projects
# Description: File system access with sandboxing
# Installed At: -
# Last Updated: -

Add Via Web UI¶

Navigate to http://localhost:8000 (or your SkillMeat server URL)
Click MCP Servers in the sidebar
Click Add Server button
Fill in:
Name: Unique identifier (e.g., filesystem)
Repository: GitHub path (e.g., anthropics/mcp-filesystem)
Version: Tag, branch, or latest (default: latest)
Description: What this server does
Environment Variables: Add as key-value pairs
Click Save

Deploying to Claude Desktop¶

Understanding Deployment¶

Deployment registers your MCP servers in Claude Desktop's claude_desktop_config.json, making them available to Claude. SkillMeat handles:

Platform-specific configuration paths (macOS, Windows, Linux)
Automatic backup of existing configuration
Environment variable injection
Atomic updates (all-or-nothing)
Rollback on failure

Deploy a Single Server¶

Dry-Run (Preview Changes)¶

Before deploying, preview what will change:

# Show what would be deployed without making changes
skillmeat mcp deploy filesystem --dry-run

# Output:
# DRY RUN: Would deploy server 'filesystem'
#
# Changes to apply:
#   Settings file: ~/.config/Claude/claude_desktop_config.json
#   Backup: ~/.config/Claude/backup_2024-01-15_14-30.json
#   New entry:
#     "filesystem": {
#       "command": "node",
#       "args": ["/path/to/mcp-filesystem/dist/index.js"],
#       "env": {
#         "ROOT_PATH": "/home/user/projects"
#       }
#     }

Full Deployment¶

# Deploy filesystem server to Claude Desktop
skillmeat mcp deploy filesystem

# Output shows:
# Deploying filesystem...
# ✓ Backup created at ~/.config/Claude/backup_2024-01-15_14-30.json
# ✓ Configuration updated
# ✓ Server 'filesystem' deployed successfully
#
# Server status: installed
# Next: Restart Claude Desktop or use 'mcp health' to check status

Deploy Multiple Servers¶

# Deploy all servers in collection
skillmeat mcp deploy --all

# Deploy specific servers
skillmeat mcp deploy filesystem github database

# Deploy with custom dry-run check
skillmeat mcp deploy --all --dry-run

Deployment With Verification¶

# Deploy and verify health status
skillmeat mcp deploy filesystem && skillmeat mcp health filesystem

# Deploy all and get full report
skillmeat mcp deploy --all && skillmeat mcp health --all

Backup and Restore¶

Automatic Backups¶

SkillMeat automatically creates backups before deployment:

# Backups are stored in:
# macOS: ~/Library/Application Support/Claude/
# Linux: ~/.config/Claude/
# Windows: %APPDATA%\Claude\

# List recent backups
ls -lt ~/.config/Claude/backup_*.json | head -5

Manual Backup¶

# Create manual backup before risky changes
skillmeat mcp backup

# Output:
# Backup created: ~/.config/Claude/manual_backup_2024-01-15.json

Restore from Backup¶

# Restore from most recent backup
skillmeat mcp restore

# Restore from specific backup
skillmeat mcp restore ~/.config/Claude/backup_2024-01-15_14-30.json

# Output:
# Restored configuration from backup
# ✓ Previous state restored successfully

Managing Environment Variables¶

Understanding Environment Variables¶

Environment variables configure MCP servers with: - Credentials: API tokens, database URLs - Paths: File system roots, working directories - Options: Debug modes, timeout values - Secrets: Passwords, private keys

Add Environment Variables¶

Via CLI¶

# Add single variable
skillmeat mcp env set filesystem ROOT_PATH "/home/user/projects"

# Add multiple variables
skillmeat mcp env set github \
  GITHUB_TOKEN "ghp_xxx" \
  GITHUB_API_URL "https://api.github.com"

# Verify variables set
skillmeat mcp env get github
# Output:
# Environment Variables for 'github':
# - GITHUB_TOKEN = ****
# - GITHUB_API_URL = https://api.github.com

Update Existing Variable¶

# Change an existing variable
skillmeat mcp env set filesystem ROOT_PATH "/new/path"

# Clear a variable
skillmeat mcp env unset filesystem ROOT_PATH

Via Web UI¶

Open MCP Servers → select server → Edit
Scroll to Environment Variables section
Click Add Variable
Enter key and value
Click Save

Sensitive Variables (Secrets)¶

Best Practices¶

Use .env files for local development:

# .env file (add to .gitignore!)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
DATABASE_PASSWORD=secure_password

Load from environment:

# Set in shell profile
export SKILLMEAT_GITHUB_TOKEN="$GITHUB_TOKEN"

# SkillMeat automatically loads SKILLMEAT_* variables
skillmeat mcp env set github GITHUB_TOKEN \
  "$(echo $SKILLMEAT_GITHUB_TOKEN)"

Use secrets management (production):
HashiCorp Vault
AWS Secrets Manager
1Password CLI
GitHub Secrets (for CI/CD)

Never Store Secrets in Configuration¶

# DON'T do this - secrets exposed in version control
skillmeat mcp env set github GITHUB_TOKEN "ghp_xxx"  # ✗ BAD

# Instead, load from environment
export GITHUB_TOKEN="ghp_xxx"
skillmeat mcp env set github GITHUB_TOKEN "$GITHUB_TOKEN"  # ✓ GOOD

# Or use .env files
source .env && \
  skillmeat mcp env set github GITHUB_TOKEN "$GITHUB_TOKEN"

Multi-Environment Setup¶

For different configurations per environment:

# Development environment
skillmeat mcp env set filesystem ROOT_PATH "/home/user/dev-projects"

# Production environment (separate collection)
skillmeat collection init production
skillmeat mcp add filesystem anthropics/mcp-filesystem \
  --collection production
skillmeat mcp env set filesystem ROOT_PATH "/var/projects" \
  --collection production

Health Monitoring¶

Check Single Server Health¶

# Check filesystem server health
skillmeat mcp health filesystem

# Output shows:
# Server: filesystem
# Status: healthy
# Deployed: yes
# Last Seen: 2024-01-15 14:25:32 UTC
# Error Count: 0
# Warning Count: 0
# Recent Errors: none
# Recent Warnings: none

Check All Servers¶

# Check health of all servers
skillmeat mcp health --all

# Output:
# MCP Server Health Report
# ========================
#
# filesystem        | healthy    | deployed | Last seen: 14:25:32 UTC
# github            | healthy    | deployed | Last seen: 14:20:15 UTC
# database          | unhealthy  | deployed | Last seen: 1h ago
#
# Summary: 2 healthy, 1 unhealthy

Understanding Health Status¶

Status	Meaning	Action
healthy	Server running normally, no issues	None needed
degraded	Server running but with warnings	Monitor for issues
unhealthy	Server deployed but not working	See troubleshooting
unknown	Cannot determine status	Restart server or check logs
not_deployed	Server in collection but not deployed	Deploy server first

Watch Health Status (Continuous Monitoring)¶

# Watch server health every 10 seconds
skillmeat mcp health filesystem --watch

# Watch all servers
skillmeat mcp health --all --watch

Health Status Caching¶

By default, health checks are cached for 60 seconds to avoid excessive log parsing:

# Force fresh health check (ignore cache)
skillmeat mcp health filesystem --force

# Disable caching for this check
skillmeat mcp health --all --no-cache

Web UI Guide¶

Accessing the Web Interface¶

Start SkillMeat server:

skillmeat web start
# Server running at http://localhost:8000

Open browser to http://localhost:8000

Authenticate with API token:

# Generate API token
skillmeat token create

# Copy token and paste in web UI login

MCP Servers Dashboard¶

The MCP Servers section provides:

Overview Panel: - Total servers: count of all servers - Healthy: count of servers with healthy status - Unhealthy: count with issues - Quick actions: Deploy All, Check Health, Backup

Server List Table: - Server name and description - Current status with color indicator - Last deployment time - Environment variables count - Quick action buttons (Edit, Deploy, Health, Remove)

Adding Servers via Web UI¶

Click MCP Servers → Add Server
Fill in server details:
Name: Unique identifier
Repository: GitHub path (e.g., anthropics/mcp-filesystem)
Version: Tag or branch
Description: Human-readable purpose
Add environment variables:
Click Add Variable
Enter key and value
Mark as sensitive if needed (hidden from UI)
Click Save

Deploying from Web UI¶

Select server or click Deploy All
Review Deployment Preview:
Shows configuration changes
Displays environment variables
Shows backup location
Optional: Enable Dry Run first
Click Deploy
Monitor deployment status in log

Health Check from Web UI¶

Click Health button next to server
View detailed health report:
Current status
Last seen time
Recent errors (if any)
Recent warnings (if any)
Optional: Click View Logs to see detailed logs

Configuration Management¶

In Settings → MCP Configuration:

Default Backup Location: Where backups are stored
Health Check Interval: How often to check health
Log Retention: How long to keep health logs
Cache Duration: How long to cache health results
Auto-Deploy on Add: Automatically deploy servers when added

Troubleshooting¶

Server Won't Deploy¶

Symptoms: Deployment fails or hangs

Common Causes and Solutions:

Network issues

# Check network connectivity
ping github.com

# Test GitHub access
git ls-remote https://github.com/anthropics/mcp-filesystem

Invalid repository

# Verify repository exists and is accessible
skillmeat mcp show filesystem

# Try to clone manually
git clone https://github.com/anthropics/mcp-filesystem /tmp/test-mcp

Missing GitHub token

# Check if token is set
skillmeat config get github-token

# Set token if missing
skillmeat config set github-token "ghp_xxx"

Insufficient disk space

# Check available space
df -h ~

# Clean up old backups
rm ~/.config/Claude/backup_*.json

Server Deployed But Not Working¶

Symptoms: Server is deployed but Claude can't use it

Solutions:

Restart Claude Desktop

# Close Claude completely
# On macOS: killall Claude
# Reopen Claude Desktop

Check server configuration

# View deployed configuration
skillmeat mcp show filesystem --deployed

# Verify command and arguments are correct
cat ~/.config/Claude/claude_desktop_config.json | jq '.mcpServers.filesystem'

Check server logs

# View recent server logs
skillmeat mcp logs filesystem

# Show last 50 lines
skillmeat mcp logs filesystem --tail 50

# Search logs for errors
skillmeat mcp logs filesystem | grep -i error

Verify environment variables

# List variables for server
skillmeat mcp env get filesystem

# Verify paths exist
ls -l ~/projects  # If ROOT_PATH=~/projects

Health Check Shows Unhealthy¶

Symptoms: Server reports unhealthy status

Diagnosis Steps:

Check detailed health report

skillmeat mcp health filesystem --verbose

# Shows:
# - Error messages
# - Warning messages
# - Last seen timestamp
# - Error count and patterns

Review server logs

# Get logs in JSON format for analysis
skillmeat mcp logs filesystem --format json | jq '.[] | select(.level == "ERROR")'

Check if server is running

# Check process status
ps aux | grep mcp

# Check port availability (if applicable)
lsof -i :3000  # If server uses port 3000

Test server manually

# Try to run server directly
cd ~/.skillmeat/servers/filesystem
npm start
# Look for error messages

Deployment Rollback Needed¶

If something goes wrong after deployment:

# Automatic rollback
skillmeat mcp restore

# Or restore specific backup
skillmeat mcp restore ~/.config/Claude/backup_2024-01-15_14-30.json

# Verify restored state
skillmeat mcp list
skillmeat mcp health --all

Claude Desktop Not Finding Server¶

Symptoms: Added server doesn't appear in Claude

Solutions:

Restart Claude completely

# macOS
pkill -9 Claude

# Linux
pkill -9 claude

# Windows (PowerShell)
Stop-Process -Name "Claude Desktop*"

Verify settings.json

# Check settings file is valid JSON
jq . ~/.config/Claude/claude_desktop_config.json

# If invalid, restore from backup
skillmeat mcp restore

Check server name format

# Server names should be valid identifiers
# Valid: filesystem, github, my-server, my_server, server123
# Invalid: my server, my-server!, /path/server

FAQ¶

Q: Can I use the same MCP server in multiple collections?¶

A: Yes, add the server to each collection:

skillmeat collection init collection1
skillmeat mcp add filesystem anthropics/mcp-filesystem --collection collection1

skillmeat collection init collection2
skillmeat mcp add filesystem anthropics/mcp-filesystem --collection collection2

Q: How do I update an MCP server to a newer version?¶

A: Update the version and redeploy:

# Current version
skillmeat mcp show filesystem

# Update to new version
skillmeat mcp update filesystem --version v2.0.0

# Redeploy
skillmeat mcp deploy filesystem

Q: Can I use MCP servers with Claude Web?¶

A: No, MCP servers only work with Claude Desktop. Claude Web (on claude.ai) doesn't support MCP servers.

Q: What happens to my servers if I uninstall SkillMeat?¶

A: Your servers remain in Claude Desktop's configuration. To remove them:

# Before uninstalling, remove all servers
skillmeat mcp remove --all

# Then uninstall SkillMeat
pip uninstall skillmeat

A: Yes, export and share your collection:

# Export collection
skillmeat collection export default --output team-mcp.json

# Team member imports
skillmeat collection import team-mcp.json

Q: How do I secure sensitive environment variables?¶

A: Use environment variables and avoid storing in configuration:

# In your shell profile
export SKILLMEAT_DB_PASSWORD="secure_password"

# Add to server
skillmeat mcp env set database DB_PASSWORD "$SKILLMEAT_DB_PASSWORD"

# Or use .env files with git ignore
echo "SKILLMEAT_DB_PASSWORD=secure_password" >> .env
echo ".env" >> .gitignore

Q: What if Claude crashes when I use an MCP server?¶

A: Possible memory or resource issue. Try: 1. Restart Claude completely 2. Check server logs: skillmeat mcp logs SERVER_NAME 3. Monitor resource usage while server runs 4. Check if server has memory leaks: skillmeat mcp health SERVER_NAME --verbose 5. Reduce concurrent operations if server is resource-intensive

Next Steps¶

Quick Start Guide - Common tasks reference
Real-World Examples - Setup scenarios
Operations Runbook - For system administrators
Architecture Documentation - Technical details

MCP Server Management Guide¶

Overview¶

What This Guide Covers¶

Prerequisites¶

Optional¶

Check Your Setup¶

Getting Started¶

Step 1: Initialize Your Collection¶

Step 2: Set GitHub Token (Optional but Recommended)¶

Step 3: Test Your Setup¶

Adding MCP Servers¶

Available MCP Servers¶

Add a Server via CLI¶

Basic Addition (No Environment Variables)¶

Addition with Environment Variables¶

Addition with Description¶

View Server Details¶

Add Via Web UI¶

Deploying to Claude Desktop¶

Understanding Deployment¶

Deploy a Single Server¶

Dry-Run (Preview Changes)¶

Full Deployment¶

Deploy Multiple Servers¶

Deployment With Verification¶

Backup and Restore¶

Automatic Backups¶

Manual Backup¶

Restore from Backup¶

Managing Environment Variables¶

Understanding Environment Variables¶

Add Environment Variables¶

Via CLI¶

Update Existing Variable¶

Via Web UI¶

Sensitive Variables (Secrets)¶

Best Practices¶

Never Store Secrets in Configuration¶

Multi-Environment Setup¶

Health Monitoring¶

Check Single Server Health¶

Check All Servers¶

Understanding Health Status¶

Watch Health Status (Continuous Monitoring)¶

Health Status Caching¶

Web UI Guide¶

Accessing the Web Interface¶

MCP Servers Dashboard¶

Adding Servers via Web UI¶

Deploying from Web UI¶

Health Check from Web UI¶

Configuration Management¶

Troubleshooting¶

Server Won't Deploy¶

Server Deployed But Not Working¶

Health Check Shows Unhealthy¶

Deployment Rollback Needed¶

Claude Desktop Not Finding Server¶

FAQ¶

Q: Can I use the same MCP server in multiple collections?¶

Q: How do I update an MCP server to a newer version?¶

Q: Can I use MCP servers with Claude Web?¶

Q: What happens to my servers if I uninstall SkillMeat?¶

Q: Can I share MCP server configurations with my team?¶

Q: How do I secure sensitive environment variables?¶

Q: What if Claude crashes when I use an MCP server?¶

Next Steps¶