NCP

Appearance

NCP Advanced Usage Guide ​

This guide covers advanced patterns, optimization strategies, and techniques for power users.

Table of Contents ​

  1. Advanced Workflow Patterns
  2. Performance Optimization
  3. Troubleshooting
  4. Custom MCP Development
  5. Architecture Deep-Dive

Advanced Workflow Patterns ​

Multi-Step Orchestration ​

Combine multiple MCPs to create sophisticated workflows:

bash
# Example: Create GitHub issue from local file content
# 1. Read local file
ncp run filesystem:read_file path=/path/to/issue-template.md

# 2. Use content to create GitHub issue
ncp run github:create_issue \
  owner=myorg \
  repo=my-repo \
  title="New Feature Request" \
  body="<from previous response>"

# 3. Post notification to Slack
ncp run slack:send_message \
  channel=#notifications \
  text="Issue created: <issue-url>"

Conditional Execution Chains ​

Use scripting to create conditional MCP executions:

bash
#!/bin/bash
# Check if repository needs update
NEEDS_UPDATE=$(ncp run github:list_branches owner=myorg repo=my-repo | grep -c "feature-branch")

if [ $NEEDS_UPDATE -gt 0 ]; then
  echo "Found feature branches, creating PR"
  ncp run github:create_pull_request \
    owner=myorg \
    repo=my-repo \
    head=feature-branch \
    base=main
else
  echo "No feature branches found"
fi

Batch Operations ​

Process multiple items efficiently:

bash
# Process multiple files across an MCP
for file in /data/*.json; do
  echo "Processing $file"
  ncp run custom-processor:process_file path="$file"
done

Performance Optimization ​

Caching Strategy ​

NCP implements intelligent caching for frequently accessed data:

  • Prompts/Resources Caching: 60-second TTL for list operations
  • Tool Discovery: Results cached during tool lookup phase
  • Connection Pooling: Reuses MCP connections with configurable limits

To maximize caching benefits:

  • Batch multiple find/list operations within 60 seconds
  • Avoid frequent profile switching (invalidates caches)
  • Monitor cache hits via debug logging: ncp config debugLogging true

Connection Pool Management ​

NCP maintains a connection pool with these limits:

  • MAX_CONNECTIONS: Maximum simultaneous MCP connections (default: 50)
  • MAX_EXECUTIONS_PER_CONNECTION: Executions before reconnection (default: 1000)
  • LRU Eviction: Least recently used connections removed when limit exceeded

Optimize for your workload:

bash
# For high-frequency operations, ensure pool size is adequate
# Monitor connection reuse: check logs for "Reusing connection" messages

# For long-running sessions, monitor execution counts
# to detect forced reconnections

Query Optimization ​

When using find, optimize your queries:

bash
# ✅ Good: Specific, natural language
ncp find "read file from filesystem"

# ✅ Good: Tool name prefix
ncp find "filesystem:read"

# ⚠️ Inefficient: Too broad
ncp find "data"

# Use depth control to reduce data transfer
ncp find "file operations" --depth 0  # Names only
ncp find "file operations" --depth 1  # Names + descriptions
ncp find "file operations" --depth 2  # Full details (default)

Troubleshooting ​

Debug Logging ​

Enable comprehensive debugging:

bash
ncp config debugLogging true

# Or via environment variable
export NCP_DEBUG=true
ncp run github:list_issues owner=anthropic repo=claude-code

Debug logs include:

  • MCP connection establishment
  • Tool discovery process
  • Parameter validation
  • Cache hits/misses
  • Performance metrics

Connection Issues ​

Symptom: "Failed to connect to MCP"

bash
# Check MCP health
ncp doctor

# Verify configuration
ncp config location  # Check where configs are stored

# Test with explicit profile
ncp list --profile all

Symptom: "Tool not found"

bash
# Search across all MCPs
ncp find "operation description"

# List specific MCP tools
ncp list | grep "mcp-name"

# Verify MCP is loaded
ncp doctor

Symptom: "Command execution timeout"

bash
# Check if MCP is responsive
ncp run mcp-name:simple_tool

# Enable debug logs to see where timeout occurred
ncp config debugLogging true

# Try with dry-run to verify parameters
ncp run mcp-name:tool_name param1=value --dry-run

Performance Issues ​

Symptom: Slow find operations

bash
# Use more specific queries
ncp find "database query operations" --depth 1  # Reduce data
ncp find "postgres" --depth 2  # Be specific

# Check cache effectiveness
ncp config debugLogging true
# Look for "Using cached" messages

Symptom: Slow tool execution

bash
# Profile the execution
time ncp run mcp:tool param=value

# Check connection pool status
ncp config debugLogging true
# Monitor "Reusing connection" vs "Creating new connection"

# Consider connection pool limits
# If many connections are created, increase MAX_CONNECTIONS

Custom MCP Development ​

Building a Custom MCP ​

Create an MCP for your specific needs:

typescript
// src/my-custom-mcp.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'my-custom-mcp',
  version: '1.0.0'
});

// Define tools
server.setRequestHandler('tools/list', () => ({
  tools: [
    {
      name: 'process_data',
      description: 'Process data from custom source',
      inputSchema: {
        type: 'object',
        properties: {
          data: { type: 'string', description: 'Data to process' }
        },
        required: ['data']
      }
    }
  ]
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'process_data') {
    // Implementation
    return {
      content: [{ type: 'text', text: 'Processed result' }]
    };
  }
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Integrating Custom MCPs ​

Add your custom MCP to NCP:

bash
# Option 1: Direct command
ncp add my-custom-mcp node /path/to/my-custom-mcp.js

# Option 2: Via profile configuration
ncp config location  # Find config file
# Edit ~/.ncp/profiles/all.json and add:
# {
#   "mcpServers": {
#     "my-custom-mcp": {
#       "command": "node",
#       "args": ["/path/to/my-custom-mcp.js"]
#     }
#   }
# }

# Verify
ncp list | grep my-custom-mcp

Architecture Deep-Dive ​

Request Processing Pipeline ​

User Input
    ↓
Command Parser
    ↓
Tool Discovery (ToolFinder)
    ↓
Parameter Validation (ToolSchemaParser)
    ↓
Context Resolution (ToolContextResolver)
    ↓
MCP Connection Pool
    ↓
Tool Execution (with error handling)
    ↓
Result Formatting & Output

MCP Connection Lifecycle ​

1. Initial Request to MCP
   ├─ Check connection pool
   ├─ If exists: Reuse (increment executionCount)
   └─ If not: Create new connection

2. Tool Execution
   ├─ Validate parameters
   ├─ Call MCP tool
   └─ Capture response

3. Connection Management
   ├─ Track lastUsed timestamp
   ├─ Update executionCount
   └─ Check for LRU eviction

4. Cleanup
   ├─ Cache results (if applicable)
   └─ Return to pool (don't close)

Tool Discovery Mechanism ​

ToolFinder.findTools(query)
    ↓
DiscoveryEngine.findRelevantTools(query)
    ↓
Vector Similarity Search
    ├─ Convert query to embedding
    ├─ Search against indexed tools
    └─ Return sorted by relevance

Results
    ├─ Full tool schemas (if depth >= 2)
    ├─ Names + descriptions (if depth >= 1)
    └─ Names only (if depth = 0)

Internal MCP Architecture ​

NCPManagementMCP (Bundled)
├─ add: Add new MCPs to profile
├─ remove: Remove MCPs from profile
├─ list: List configured MCPs
├─ import: Import configs
└─ export: Export configs

NCPSchedulerMCP (Bundled)
├─ create: Create scheduled jobs
├─ retrieve: Get job status
├─ update: Modify job settings
└─ delete: Remove jobs

Advanced Configuration ​

Environment Variables ​

bash
# Debugging
NCP_DEBUG=true              # Enable debug logging
DEBUG=true                  # Alternative debug flag

# Auto-import control
NCP_SKIP_AUTO_IMPORT=true   # Disable Claude Desktop sync

# Scheduler
NCP_ENABLE_SCHEDULER=true   # Enable built-in scheduler

# Confirmation
NCP_CONFIRM_BEFORE_RUN=true # Always show confirmation

Profile-Specific Optimization ​

bash
# Create a high-performance profile
ncp config --profile performance

# Add only essential MCPs
ncp add github --profile performance
ncp add filesystem --profile performance

# Use it for critical operations
ncp run --profile performance github:get_issues owner=myorg

Best Practices ​

1. Use Profiles for Different Contexts ​

bash
# Development profile (many MCPs)
ncp list --profile dev | wc -l

# Production profile (essential only)
ncp list --profile prod | wc -l

2. Monitor Resource Usage ​

bash
# Check connection count
ncp config debugLogging true
# Look for active connections in logs

# Monitor cache effectiveness
# Expect 70%+ cache hits for typical workflows

3. Implement Graceful Degradation ​

bash
# Always handle tool-not-found errors
ncp run github:get_organization owner=myorg || \
  echo "GitHub MCP unavailable, using fallback"

# Use dry-run for validation
ncp run mcp:tool param=value --dry-run && \
  ncp run mcp:tool param=value || \
  echo "Validation failed"

4. Batch Operations Strategically ​

bash
# Good: Batch related operations
for repo in repo1 repo2 repo3; do
  ncp run github:create_issue owner=org repo=$repo title="Bug"
done

# Better: Use multi-argument tools when available
ncp run github:bulk_create_issues owner=org repos="repo1,repo2,repo3" titles="Bug"

5. Schedule Repetitive Tasks ​

bash
# Schedule daily health checks
ncp schedule create \
  --name "health-check" \
  --tool github:check_status \
  --schedule "0 9 * * *" \
  --timezone "America/New_York"

# Monitor scheduled job execution
ncp schedule retrieve --job health-check --executions

Performance Benchmarks ​

Typical performance metrics on a modern system:

  • Tool Discovery: 50-200ms (cached: 1-5ms)
  • Tool Execution: 100-2000ms (depends on MCP)
  • Connection Reuse: 5-10x faster than new connections
  • Cache Hit: 95%+ after initial discovery

Getting Help ​

  • Check debug logs: ncp config debugLogging true
  • Review MCP status: ncp doctor
  • Consult test-drive guide: ncp resources read ncp:test-drive
  • Review docs: ncp resources read ncp:help/getting-started

Released under the Elastic License 2.0.

Copyright Portel