NCP (MCP Orchestrator) MCP server for AI agents

Natural Context Provider (NCP) is a tool that transforms multiple Model Context Protocol (MCP) servers into a single intelligent orchestrator. This allows your AI to interact with just two simple tools instead of numerous complex ones, while NCP handles all the routing, discovery, and execution behind the scenes.

Installation

Prerequisites

Node.js 18 or higher
npm (included with Node.js) or npx for running packages
Command line access

Quick Setup for Existing MCP Users

Step 1: Import Your Existing MCPs

# Install NCP globally
npm install -g @portel/ncp

# Copy your claude_desktop_config.json content to clipboard
# Then import it with:
ncp config import

Step 2: Connect NCP to Your AI

Replace your entire MCP configuration with this single entry:

{
  "mcpServers": {
    "ncp": {
      "command": "ncp"
    }
  }
}

Step 3: Verify Installation

# Check NCP is installed correctly
ncp --version

# Confirm your MCPs are imported
ncp list

# Test tool discovery
ncp find "file"

Alternative Installation with npx

If you prefer not to install globally, you can use npx:

# Import MCPs
npx @portel/ncp config import

# Find tools
npx @portel/ncp find "file operations"

# Client configuration example (Claude Desktop)
{
  "mcpServers": {
    "ncp": {
      "command": "npx",
      "args": ["@portel/ncp"]
    }
  }
}

Manual Setup

You can also add MCPs manually if you prefer to build from scratch:

# Add reasoning and memory
ncp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking
ncp add memory npx @modelcontextprotocol/server-memory

# Add file and development tools
ncp add filesystem npx @modelcontextprotocol/server-filesystem ~/Documents
ncp add github npx @modelcontextprotocol/server-github

# Add search capabilities
ncp add brave-search npx @modelcontextprotocol/server-brave-search

Usage

Testing NCP Features

NCP provides a human-friendly CLI for testing:

# Discover tools based on intent
ncp find "I need to read a file"
ncp find "help me send an email"

# View your complete MCP ecosystem
ncp list --depth 2

# Get help
ncp --help

# Test a specific tool
ncp run filesystem:read_file --params '{"path": "/tmp/test.txt"}'

Configuring Different AI Clients

Claude Desktop

Configuration file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Replace your config with:

{
  "mcpServers": {
    "ncp": {
      "command": "ncp"
    }
  }
}

Remember to restart Claude Desktop after saving the config file.

VS Code with GitHub Copilot

Add to your VS Code settings.json:

{
  "mcp.servers": {
    "ncp": {
      "command": "ncp"
    }
  }
}

Restart VS Code after saving.

Cursor IDE

{
  "mcp": {
    "servers": {
      "ncp": {
        "command": "ncp"
      }
    }
  }
}

Advanced Features

Health Monitoring

ncp list --depth 1    # See health status
ncp config validate   # Check configuration health

Multi-Profile Organization

# Development setup
ncp add --profile dev filesystem npx @modelcontextprotocol/server-filesystem ~/dev

# Production setup
ncp add --profile prod database npx production-db-server

# Use specific profile
ncp --profile dev find "file tools"

Project-Level Configuration

# In any project directory, create local MCP configuration
mkdir .ncp
ncp add filesystem npx @modelcontextprotocol/server-filesystem ./
ncp add github npx @modelcontextprotocol/server-github

# NCP automatically detects and uses project-local configuration
ncp find "save file"  # Uses only project MCPs

Troubleshooting

Import Issues

# Check what was imported
ncp list

# Validate health of imported MCPs
ncp config validate

# See detailed import logs
DEBUG=ncp:* ncp config import

AI Not Using Tools

Check connection: ncp list (should show your MCPs)
Test discovery: ncp find "your query"
Validate config: Ensure your AI client points to ncp command

Performance Issues

# Check MCP health
ncp list --depth 1

# Clear cache if needed
rm -rf ~/.ncp/cache

# Monitor with debug logs
DEBUG=ncp:* ncp find "test"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "ncp" '{"command":"ncp"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "ncp": {
            "command": "ncp"
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "ncp": {
            "command": "ncp"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect