Discovering New MCP Clients

This guide explains how to add support for new MCP clients to NCP's auto-import feature.

Overview

To support a new MCP client, we need two key pieces of information:

1. Client Name: What clientInfo.name the client sends during MCP handshake
2. Config Path: Where the client stores its MCP server configurations

Step 1: Capture Client Name

Method A: Use the MCP Client Sniffer (Recommended)

The sniffer is a minimal MCP server that logs initialization requests.

1. Add sniffer to client config:

   {
     "mcpServers": {
       "client-sniffer": {
         "command": "node",
         "args": ["/path/to/ncp/scripts/mcp-client-sniffer.cjs"]
       }
     }
   }

2. Restart the client or reload MCP connections

3. Check the output:

   • Console will show: ✨ CLIENT DETECTED!
   • Details saved to: client-info-log.json

4. Review captured data:

   cat client-info-log.json

   Example output:

   [
     {
       "timestamp": "2025-10-31T12:00:00.000Z",
       "clientInfo": {
         "name": "cursor",
         "version": "0.42.0"
       },
       "protocolVersion": "2024-11-05"
     }
   ]

Method B: Check Client Documentation

Some clients document their clientInfo.name:

• Claude Desktop: claude-desktop or claude-ai
• Cursor: cursor
• Cline: cline
• Continue: continue

Method C: Monitor MCP Logs

If the client creates logs, check for initialization messages:

# Example: Check Windsurf logs
find ~/Library/Application\ Support/Windsurf/logs -name "*mcp*" | head -5

Step 2: Find Config Path

Search Strategy

1. Check home directory:

   ls -la ~ | grep -i <client-name>

2. Check .config directory:

   ls -la ~/.config | grep -i <client-name>

3. Check Application Support (macOS):

   ls -la ~/Library/Application\ Support/ | grep -i <client-name>

4. Check AppData (Windows):

   ls $env:APPDATA | Select-String <client-name>

5. Search for MCP-related files:

   find ~ -name "*mcp*.json" 2>/dev/null | grep -i <client-name>

Common Patterns

Location	Example
Home dotfiles	~/.cursor/mcp.json
.config	~/.config/enconvo/mcp_config.json
Application Support	~/Library/Application Support/Claude/claude_desktop_config.json
VSCode-like	~/Library/Application Support/<IDE>/User/globalStorage/<extension>/settings/*.json

Verify Config Format

Once you find the config file:

cat <config-path> | jq '.mcpServers'

Check:

• ✅ Is it JSON or TOML?
• ✅ Where are MCP servers stored? (root level? nested path?)
• ✅ What's the structure? (object with MCP names as keys?)

Example structures:

Standard format (Claude Desktop, Cursor):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

Nested format (Continue):

{
  "experimental": {
    "modelContextProtocolServers": {
      "filesystem": { ... }
    }
  }
}

Array format (Perplexity):

{
  "servers": [
    { "name": "filesystem", "command": "..." }
  ]
}

Step 3: Add to Client Registry

Update src/utils/client-registry.ts:

'<client-id>': {
  displayName: '<Client Name>',
  configPaths: {
    darwin: '~/path/to/config.json',           // macOS
    win32: '%APPDATA%/path/to/config.json',    // Windows
    linux: '~/.config/path/to/config.json'     // Linux
  },
  configFormat: 'json',  // or 'toml'
  mcpServersPath: 'mcpServers'  // JSON path to servers object
}

Important Notes

1. Client ID normalization: NCP normalizes client names by:

   • Converting to lowercase
   • Removing spaces and dashes
   • Example: "Claude Desktop" → "claudedesktop"

2. Add all aliases: Some clients send different names:

   'claude-desktop': { ... },
   'claude-ai': { ... },  // Alias pointing to same paths

3. Platform-specific paths: Only include paths for supported platforms

Step 4: Test Auto-Import

Build and Verify

# 1. Build
npm run build

# 2. Check detection
node scripts/verify-client-configs.js

# Expected output:
# ✅ INSTALLED CLIENTS (Can Test Auto-Import)
# 📦 <Your Client>
#    Client ID: <client-id>
#    Config: /actual/path/to/config.json

Manual Test

# 1. Clear NCP profile
rm ~/.ncp/profiles/all.json

# 2. Start NCP with client's name
# (or configure client to use NCP and restart)

# 3. Check if MCPs were imported
cat ~/.ncp/profiles/all.json | jq '.mcpServers'

Integration Test

Add test to tests/integration/comprehensive-dxt-test.cjs:

const id = test.sendRequest('initialize', {
  protocolVersion: '2024-11-05',
  clientInfo: {
    name: '<client-id>',
    version: '1.0.0'
  }
});

Step 5: Document

Update docs:

1. docs/testing-client-auto-import.md - Add config path reference
2. README.md - Add client to supported list
3. docs/clients/<client>.md - Create setup guide (optional)

Examples

Example 1: Cursor

Discovery:

# Found config
ls ~/.cursor/
# Output: mcp.json

# Verified format
cat ~/.cursor/mcp.json
# Shows: { "mcpServers": { ... } }

Captured clientInfo (using sniffer):

{
  "clientInfo": {
    "name": "cursor",
    "version": "0.42.0"
  }
}

Added to registry:

'cursor': {
  displayName: 'Cursor',
  configPaths: {
    darwin: '~/.cursor/mcp.json',
    win32: '%USERPROFILE%/.cursor/mcp.json',
    linux: '~/.cursor/mcp.json'
  },
  configFormat: 'json',
  mcpServersPath: 'mcpServers'
}

Example 2: Enconvo

Discovery:

# Search for config
find ~ -name "*enconvo*" -type d
# Found: ~/.config/enconvo

# Check contents
ls ~/.config/enconvo/
# Found: mcp_config.json

# Verify format
cat ~/.config/enconvo/mcp_config.json
# Shows: { "mcpServers": {} }

Added to registry:

'enconvo': {
  displayName: 'Enconvo',
  configPaths: {
    darwin: '~/.config/enconvo/mcp_config.json'
  },
  configFormat: 'json',
  mcpServersPath: 'mcpServers'
}

Troubleshooting

Client not detected

1. Check client name normalization:

   // In src/utils/client-registry.ts
   export function normalizeClientName(name: string): string {
     return name.toLowerCase().replace(/[\s-]/g, '');
   }

2. Verify config exists:

   ls -la <config-path>

3. Check NCP logs:

   export NCP_DEBUG=true
   cat ~/.ncp/debug.log | grep -i "client"

MCPs not imported

1. Check mcpServersPath: Verify JSON path is correct

   cat <config> | jq '.<mcpServersPath>'

2. Test config parsing:

   import { importFromClient } from './dist/utils/client-importer.js';
   const result = await importFromClient('<client-id>');
   console.log(result);

Config format issues

1. TOML support: Use configFormat: 'toml' and install parser
2. Custom format: Add custom parser in client-importer.ts
3. Array format: Update mcpServersPath to handle arrays

Tools Reference

Scripts

Script	Purpose
scripts/mcp-client-sniffer.cjs	Capture clientInfo from any MCP client
scripts/verify-client-configs.js	Check which clients are installed and detectable
scripts/capture-client-info.js	Advanced monitoring with NCP server

Files to Update

File	What to Add
src/utils/client-registry.ts	Client definition with paths
src/utils/client-importer.ts	Custom parsers (if needed)
docs/testing-client-auto-import.md	Testing instructions
tests/integration/comprehensive-dxt-test.cjs	Integration test

Best Practices

1. Test on actual installations - Don't guess paths
2. Document platform differences - Note any OS-specific quirks
3. Handle edge cases - Client might not have MCPs configured yet
4. Validate data - Ensure MCPs have required command field
5. Preserve user data - Don't overwrite existing configs during import