Ncp

NCP - Natural Context Provider

1 MCP to rule them all

Your MCPs, supercharged. Discover tools, execute with code mode, run on schedule, find skills, and load Photons through common MCP clients. On-demand discovery keeps the initial tool surface focused.

Related Portel project: Photon turns TypeScript methods into reliable agent-facing capabilities: MCP tools, embedded app UIs, CLI commands, web routes, schedules, webhooks, retries, and Beam interfaces. NCP helps agents discover and operate tools; Photon helps developers build the tools and apps agents can trust.

💍 What is NCP?

Instead of your AI juggling 50+ tools scattered across different MCPs, NCP gives it a single, unified interface with code mode execution, scheduling, skills discovery, and custom Photons.

Most hosts see NCP's small gateway surface (find, run, and, when enabled, code). Hosts that support MCP Apps can also receive selected app callback tools so embedded interfaces keep working. NCP adds app tools selectively; it omits conflicting app groups rather than renaming callbacks that an app may call by name.

• `find` - Search for any tool, skill, or Photon: "I need to read a file" → finds the right tool automatically
• `code` - Execute TypeScript directly: await github.create_issue({...}) (code mode, enabled by default)
• `run` - Execute tools individually (when code mode is disabled)

Behind the scenes, NCP manages all 50+ tools + skills + Photons: routing requests, discovering the right capability, executing code, scheduling tasks, managing health, and caching responses.

The host determines which optional features it can use. NCP advertises MCP Apps, Skills, and Tasks capabilities, while clients that do not support an extension continue with the core tools and existing request flows.

Why this matters:

• Your AI stops analyzing "which tool do I use?" and starts doing actual work
• Code mode lets AI write multi-step TypeScript workflows combining tools, skills, and scheduling
• Skills provide domain expertise: canvas design, PDF manipulation, document generation, more
• Photons enable custom TypeScript MCPs without npm publishing
• On-demand discovery keeps the initial tool surface focused; actual context use depends on the host, enabled NCP tools, and connected servers
• Your AI becomes focused. Not desperate.

🚀 NEW: Project-level configuration - each project can define its own MCPs automatically

What's MCP? The Model Context Protocol by Anthropic lets AI assistants connect to external tools and data sources. Think of MCPs as "plugins" that give your AI superpowers like file access, web search, databases, and more.

---

📑 Quick Navigation

• The Problem - Why too many tools break your AI
• The Solution - How NCP transforms your experience
• Getting Started - Installation & quick start
• Try It Out - See the CLI in action
• Supercharged Features - How NCP empowers your MCPs
• Setup by Client - Claude Desktop, Cursor, VS Code, etc.
• Popular MCPs - Community favorites to add
• Advanced Features - Project config, scheduling, remote MCPs
• Troubleshooting - Common issues & solutions
• How It Works - Technical deep dive
• Contributing - Help us improve NCP

---

😤 The MCP Paradox: From Assistant to Desperate

You gave your AI assistant 50 tools to be more capable. Instead, you got desperation:

• Paralyzed by choice ("Should I use read_file or get_file_content?")
• Exhausted before starting ("I've spent my context limit analyzing which tool to use")
• Costs explode (50+ tool schemas burn tokens before any real work happens)
• Asks instead of acts (used to be decisive, now constantly asks for clarification)

---

🧸 Why Too Many Tools Break the System

Think about it like this:

A child with one toy → Treasures it, masters it, creates endless games with it A child with 50 toys → Can't hold them all, gets overwhelmed, stops playing entirely

Your AI is that child. MCPs are the toys. More isn't always better.

The most creative people thrive with constraints, not infinite options. A poet given "write about anything" faces writer's block. Given "write a haiku about rain"? Instant inspiration.

Your AI is the same. Give it one perfect tool → Instant action. Give it 50 tools → Cognitive overload. NCP provides just-in-time tool discovery so your AI gets exactly what it needs, when it needs it.

---

📊 The Before & After Reality

Before NCP: Desperate Assistant 😵💫

When your AI assistant manages 50 tools directly:

🤖 AI Assistant Context:

├── Filesystem MCP (12 tools) ├── Database MCP (8 tools) ├── Web Search MCP (6 tools) ├── Email MCP (15 tools) ├── Shell MCP (10 tools) ├── GitHub MCP (20 tools) └── Slack MCP (9 tools)

💀 Total: 80 tool schemas compete for attention before useful work begins

What happens:

• AI burns 50%+ of context just understanding what tools exist
• Spends 5-8 seconds analyzing which tool to use
• Often picks wrong tool due to schema confusion
• Hits context limits mid-conversation

After NCP: Executive Assistant ✨

With NCP as Chief of Staff:

🤖 AI Assistant Context:

└── NCP gateway tools → discover and run the tools needed for this request

🎯 Behind the scenes: NCP manages all 80 tools 📈 Tool discovery happens on demand 🎪 AI behavior: Confident, focused, decisive

NCP reduces the need to load every downstream tool schema into the host up front. The amount of context saved and any effect on response time vary with the host, server catalog, and enabled features.

---

📋 Prerequisites

• Node.js 22+ (Node.js 24 recommended; CI uses 24) (Download here)
• npm (included with Node.js) or npx for running packages
• Command line access (Terminal on Mac/Linux, Command Prompt/PowerShell on Windows)

🚀 Installation

Choose your MCP client for setup instructions:

---

Quick Start (npm)

For advanced users or MCP clients not listed above:

Step 1: Install NCP

npm install -g @portel/ncp

Step 2: Import existing MCPs (optional)

ncp config import  # Paste your config JSON when prompted

Step 3: Configure your MCP client

Add to your client's MCP configuration:

{

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

✅ Done! Your AI can discover and run tools through NCP. Hosts with MCP Apps support may also receive selected app callback tools.

---

🧪 Test Drive: See the Difference Yourself

Want to experience what your AI experiences? NCP has a human-friendly CLI:

🔍 Smart Discovery

# Ask like your AI would ask:

ncp find "I need to read a file" ncp find "help me send an email" ncp find "search for something online"

Notice: NCP understands intent, not just keywords. Just like your AI needs.

📋 Ecosystem Overview

# See your complete MCP ecosystem:

ncp list --depth 2

Get help anytime:

ncp --help

⚡ Direct Testing

# Test any tool safely:

ncp run filesystem read_file --path "/tmp/test.txt"

Why this matters: You can debug and test tools directly, just like your AI would use them.

✅ Verify Everything Works

# 1. Check NCP is installed correctly

ncp --version

2. Confirm your MCPs are imported

ncp list

3. Test tool discovery

ncp find "file"

4. Test a simple tool (if you have filesystem MCP)

ncp run filesystem read_file --path "/tmp/test.txt" --dry-run

✅ Success indicators:

• NCP shows version number
• ncp list shows your imported MCPs
• ncp find returns relevant tools
• Your AI client shows NCP's gateway tools; an Apps-capable host may also show selected app callback tools

---

💪 From Tools to Automation: The Real Power

You've seen find (discover tools) and code (execute TypeScript). Individually, they're useful. Together with scheduling, they become an automation powerhouse.

A Real Example: The MCP Conference Scraper

We wanted to stay on top of MCP-related conferences and workshops for an upcoming release. Instead of manually checking websites daily, we asked Claude:

"Set up a daily scraper that finds MCP conferences and saves them to a CSV file"

What Claude did:

1. Used `code` to write the automation:

   // Search the web for MCP conferences

const results = await web.search({ query: "Model Context Protocol conference 2025" });

// Read each result and extract details for (const url of results) { const content = await web.read({ url }); // Extract title, deadline, description... // Save to ~/.ncp/mcp-conferences.csv }

1. Used `schedule` to automate it:

   ncp schedule create code:run "every day at 9am" \

--name "MCP Conference Scraper" \ --catchup-missed

How to set this up yourself:

First, install the web photon (provides search and read capabilities):

# Install from the official photons repo

ncp photon add https://raw.githubusercontent.com/p