MCP Server Management

CRITICAL MUST: Secrets and .env

• NEVER store live .env files or credentials inside any skill folder.
• .env.template files belong only in templates/ within a skill.
• Store live secrets in ~/.admin/.env (or another non-skill location you control) and reference them from there.

Requires: Node.js 18+ (for most servers). MCP clients are optional.

---

⚠️ Profile Gate (MANDATORY - DO THIS FIRST)

STOP. Before ANY operation, you MUST check for the profile. This is not optional.

Step 1: Check Profile Exists

PowerShell (Windows):

pwsh -NoProfile -File "$HOME\.claude\skills\admin\scripts\Test-AdminProfile.ps1"

Bash (WSL/Linux/macOS):

~/.claude/skills/admin/scripts/test-admin-profile.sh

Returns JSON: {"exists":true,"path":"...","device":"...",...}

Step 2: If Profile Missing → Run Setup

PowerShell:

pwsh -NoProfile -File "$HOME\.claude\skills\admin\scripts\Setup-Interview.ps1"

Bash:

~/.claude/skills/admin/scripts/setup-interview.sh

DO NOT proceed with ANY MCP operation until profile exists.

Step 3: Load Profile & Log Operations

After ANY MCP operation (install, remove, scan), log it:

PowerShell:

. "$HOME\.claude\skills\admin\scripts\Log-AdminEvent.ps1"
Log-AdminEvent -Message "Installed MCP server: filesystem" -Level OK

Bash:

source ~/.claude/skills/admin/scripts/log-admin-event.sh
log_admin_event "Installed MCP server: filesystem" "OK"

---

Registry-First Approach

All MCP clients and servers are tracked in a central registry:

$ADMIN_ROOT/registries/mcp-registry.json

Use the scanner to detect clients and normalize configs:

.\scripts\scan-mcp-clients.ps1

---

Quick Start

1. Scan for MCP clients and build/update the registry:

.\scripts\scan-mcp-clients.ps1

2. Inspect the registry:

$registryPath = Join-Path $env:ADMIN_ROOT "registries\\mcp-registry.json"
Get-Content $registryPath | ConvertFrom-Json | Select-Object -ExpandProperty clients

3. Install a server for a specific client (Claude Desktop example):

.\scripts\install-mcp-server.ps1 -Name "filesystem" -Command "npx" -Args @("-y","@modelcontextprotocol/server-filesystem","C:/Users/Owner/Documents")

---

Scan MCP Clients

# Detect known clients and normalize configs into the registry
.\scripts\scan-mcp-clients.ps1

If no clients are detected, the registry is still created and left empty until you install a client.

---

Remove MCP Server

.\scripts\remove-mcp-server.ps1 -Name "filesystem"

---

Critical Rules

Always Do

• Backup client configs before editing
• Use absolute paths for commands and args
• Restart the client after config changes
• Update the MCP registry after installs/removals

Never Do

• Edit configs while the client is running
• Use relative paths in MCP server configs
• Mix npx and global installs for the same server
• Store live credentials inside any skill folder

Profile-First Approach

MCP config and servers tracked in profile:

# Config file location
$AdminProfile.mcp.configFile
# "C:/Users/Owner/AppData/Roaming/Claude/claude_desktop_config.json"

# Installed servers
$AdminProfile.mcp.servers | Format-Table

jq '.mcp' "$ADMIN_PROFILE_PATH"

---

List MCP Servers

$AdminProfile.mcp.servers.PSObject.Properties | ForEach-Object {
    [PSCustomObject]@{
        Name = $_.Name
        Package = $_.Value.package
        Status = $_.Value.status
        Tools = $_.Value.toolCount
    }
}

Example output:

Name      Package                     Status   Tools
----      -------                     ------   -----
win-cli   D:/mcp/win-cli-mcp-server   working  12
coolify   @pashvc/mcp-server-coolify  working  50

---

Config File Location

From profile:

$configPath = $AdminProfile.mcp.configFile
# Or
$configPath = $AdminProfile.paths.claudeConfig

# Read current config
$config = Get-Content $configPath | ConvertFrom-Json
$config.mcpServers

---

Install New MCP Server

Step 1: Backup Config

$configPath = $AdminProfile.mcp.configFile
$backup = "$configPath.backup.$(Get-Date -Format 'yyyyMMdd-HHmmss')"
Copy-Item $configPath $backup

Step 2: Add Server Entry

$config = Get-Content $configPath | ConvertFrom-Json

# NPX pattern (most common)
$config.mcpServers | Add-Member -NotePropertyName "new-server" -NotePropertyValue @{
    command = "npx"
    args = @("-y", "@some/mcp-server")
}

# Save
$config | ConvertTo-Json -Depth 10 | Set-Content $configPath

Step 3: Update Profile

$AdminProfile.mcp.servers["new-server"] = @{
    name = "new-server"
    package = "@some/mcp-server"
    version = "1.0.0"
    command = "npx -y @some/mcp-server"
    configFile = $null
    environment = @{}
    status = "pending"
    toolCount = 0
    notes = "Just installed"
}

$AdminProfile | ConvertTo-Json -Depth 10 | Set-Content $AdminProfile.paths.deviceProfile

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop, then verify tools appear.

Step 5: Update Status

$AdminProfile.mcp.servers["new-server"].status = "working"
$AdminProfile.mcp.servers["new-server"].toolCount = 15  # Count from Claude
$AdminProfile | ConvertTo-Json -Depth 10 | Set-Content $AdminProfile.paths.deviceProfile

---

Installation Patterns

NPX (Recommended)

{
  "command": "npx",
  "args": ["-y", "@package/mcp-server"]
}

Global npm

{
  "command": "mcp-server-name"
}

Requires: npm install -g @package/mcp-server

Local Clone

{
  "command": "node",
  "args": ["D:/mcp/server-name/dist/index.js"]
}

With Environment Variables

{
  "command": "npx",
  "args": ["-y", "@package/mcp-server"],
  "env": {
    "API_KEY": "your-key",
    "BASE_URL": "https://api.example.com"
  }
}

---

Troubleshooting

Check Profile for Issues

# Known MCP issues
$AdminProfile.issues.current | Where-Object { $_.tool -like "*mcp*" }

Common Problems

| Error | Cause | Fix | |-------|-------|-----| | spawn ENOENT | Command not found | Check path, install globally | | Server not starting | Config syntax | Validate JSON | | Tools not appearing | Didn't restart | Close/reopen Claude | | Permission denied | Path issue | Use absolute Windows paths |

Diagnostics

# Check Node
node --version

# Check npm global
npm list -g --depth=0

# Validate config JSON
$configPath = $AdminProfile.mcp.configFile
try {
    Get-Content $configPath | ConvertFrom-Json | Out-Null
    Write-Host "Config JSON valid"
} catch {
    Write-Host "Config JSON invalid: $_"
}

---

Track MCP Issue

$AdminProfile.issues.current += @{
    id = "mcp-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
    tool = "mcp-server-name"
    issue = "Server fails to start - spawn ENOENT"
    priority = "high"
    status = "pending"
    created = (Get-Date).ToString("o")
}

$AdminProfile | ConvertTo-Json -Depth 10 | Set-Content $AdminProfile.paths.deviceProfile

---

Remove MCP Server

From Claude Config

$config = Get-Content $AdminProfile.mcp.configFile | ConvertFrom-Json
$config.mcpServers.PSObject.Properties.Remove("server-to-remove")
$config | ConvertTo-Json -Depth 10 | Set-Content $AdminProfile.mcp.configFile

From Profile

$AdminProfile.mcp.servers.PSObject.Properties.Remove("server-to-remove")
$AdminProfile | ConvertTo-Json -Depth 10 | Set-Content $AdminProfile.paths.deviceProfile

---

References

• references/registry-schema.md - Registry structure and fields
• references/client-configs.md - Per-client config formats
• references/installation-patterns.md - npx vs global vs clone trade-offs
• references/common-servers.md - Popular MCP servers
• references/diagnostics.md - Troubleshooting and diagnostics
• references/known-issues.md - Common pitfalls and prevention
• references/INSTALLATION.md - Legacy install patterns (Claude Desktop)
• references/CONFIGURATION.md - Legacy config structure (Claude Desktop)
• references/TROUBLESHOOTING.md - Legacy fixes