# Admin MCP

> Client-agnostic MCP server management. Registry-first approach that scans MCP clients, normalizes server configs, and maintains a central registry under ADMIN_ROOT. Use when: installing MCP servers, scanning client configs, updating registries, or troubleshooting MCP issues across clients.

- Skill: `evolv3ai/admin-mcp` (Agent Skill, multi-file: 24 files)
- Install (CLI): `npx skillmds@latest add evolv3ai/admin-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/evolv3ai/admin-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: evolv3ai (https://skillmd.com/u/evolv3ai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/evolv3ai/admin-mcp

---


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

```
$ADMIN_ROOT/registries/mcp-registry.json
```

Use the scanner to detect clients and normalize configs:

```powershell
.\scripts\scan-mcp-clients.ps1
```

---

## Quick Start

1) Scan for MCP clients and build/update the registry:
```powershell
.\scripts\scan-mcp-clients.ps1
```

2) Inspect the registry:
```powershell
$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):
```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:
```
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