portel-dev/ncp

> **1 MCP to rule them all**
Your MCPs, supercharged. Find any tool instantly, execute with code mode, run on schedule, discover skills, load Photons, ready for any client. Smart loading saves tokens and energy.
**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**.
Your AI sees just **2-3 simple tools:**
- **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.
**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
- **97% fewer tokens burned** on tool confusion (2,500 vs 103,000 for 80 tools)
- **5x faster responses** (sub-second tool selection vs 5-8 seconds)
- **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.