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):

powershell

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

Bash (WSL/Linux/macOS):

bash

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

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

Step 2: If Profile Missing → Run Setup

PowerShell:

powershell

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

Bash:

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:

powershell

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

Bash:

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:

code

$ADMIN_ROOT/registries/mcp-registry.json

Use the scanner to detect clients and normalize configs:

powershell

.\scripts\scan-mcp-clients.ps1

Quick Start

•Scan for MCP clients and build/update the registry:

powershell

.\scripts\scan-mcp-clients.ps1

•Inspect the registry:

powershell

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

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

powershell

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

Scan MCP Clients

powershell

# 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

powershell

.\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:

powershell

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

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

bash

jq '.mcp' "$ADMIN_PROFILE_PATH"

List MCP Servers

powershell

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

Example output:

code

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:

powershell

$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

powershell

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

Step 2: Add Server Entry

powershell

$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

powershell

$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

powershell

$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)

json

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

Global npm

json

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

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

Local Clone

json

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

With Environment Variables

json

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

Troubleshooting

Check Profile for Issues

powershell

# 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

powershell

# 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

powershell

$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

powershell

$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

powershell

$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