1 MCP to rule them all. Orchestrate, discover, and run any tool instantly.
io.github.portel-dev/ncp MCP Server
N-to-1 MCP orchestration via a unified gateway that performs intelligent tool discovery across multiple MCP servers. The package is identified as @portel/ncp (npm) and is distributed with GitHub releases. It is positioned as an MCP client/server orchestration layer for coordinating tools.
๐ ๏ธ Key Features
N-to-1 MCP orchestration
Unified gateway for multiple MCP servers
Intelligent tool discovery
๐ Use Cases
Coordinate calls across multiple MCP servers through a single gateway
Integrate MCP tools into agent workflows targeting AI platforms
Use in MCP-client setups where multiple tool sources must be unified
โก Developer Benefits
Centralizes access to tools from multiple MCP servers
Supports MCP tool discovery for easier integration in clients
Relevant topics include mcp, mcp-server, and mcp-client
โ ๏ธ Limitations
Description does not specify supported transports, authentication, or runtime behavior beyond tool discovery and orchestration
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
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.
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.
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:
code
๐ค 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:
Client
Description
Setup Guide
Claude Desktop
Anthropic's official desktop app. Best for NCP - one-click .dxt install with auto-sync
For advanced users or MCP clients not listed above:
Step 1: Install NCP
bash
npm install -g @portel/ncp
Step 2: Import existing MCPs (optional)
bash
ncp config import # Paste your config JSON when prompted
Step 3: Configure your MCP client
Add to your client's MCP configuration:
json
{"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
bash
# 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
bash
# See your complete MCP ecosystem:
ncp list --depth 2
# Get help anytime:
ncp --help
โก Direct Testing
bash
# 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
bash
# 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:
Used code to write the automation:
typescript
// Search the web for MCP conferencesconst results = await web.search({
query: "Model Context Protocol conference 2025"
});
// Read each result and extract detailsfor (const url of results) {
const content = await web.read({ url });
// Extract title, deadline, description...// Save to ~/.ncp/mcp-conferences.csv
}
Used schedule to automate it:
bash
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):
bash
# Install from the official photons repo
ncp photon add https://raw.githubusercontent.com/portel-dev/photons/main/web.photon.ts
Then ask Claude to create the scraper - it will use the web photon automatically.
What happens now:
Every morning at 9am, the scraper runs automatically
Searches for new MCP events and adds them to the CSV
If our laptop was closed at 9am, it catches up when we open it
We wake up to fresh conference data - no manual work
The insight:find and code let AI write automation. schedule makes it run forever. That's the powerhouse.
๐ก Why NCP Transforms Your AI Experience
๐ง From Desperation to Delegation
Desperate Assistant: "I see 50 tools... which should I use... let me think..."
Executive Assistant: "I need file access. Done." (NCP handles the details)
๐ฐ Focused Tool Discovery
NCP lets the host search a larger tool catalog on demand
The context impact depends on your host and enabled tool surface
๐ฏ Eliminates Choice Paralysis
Desperate: AI freezes, picks wrong tool, asks for clarification
Executive: NCP's Chief of Staff finds the RIGHT tool instantly
๐ Confident Action
Before: 8-second delays, hesitation, "Which tool should I use?"
After: Instant decisions, immediate execution, zero doubt
Bottom line: Your AI goes from desperate assistant to executive assistant.
โก Supercharged Features
Here's exactly how NCP empowers your MCPs:
Feature
What It Does
Why It Matters
๐ Tool Discovery
Search tools by intent as well as keywords
Find relevant tools without exposing every downstream schema at once
๐ฆ On-Demand Loading
Discover downstream tools when needed
Keeps the initial tool surface focused; context savings vary by setup
โฐ Automated Scheduling
Run any tool on cron schedules or natural language times
Background automation without keeping AI sessions open
๐ MCP Client Support
Works with common MCP clients, including Claude Desktop, Claude Code, Cursor, and VS Code
Core gateway behavior is available broadly; extension support depends on the host
๐พ Smart Caching
Intelligent caching of tool schemas and responses
Eliminates redundant indexing - energy efficient and fast
The result: Your MCPs go from scattered tools to a unified, intelligent system that your AI can actually use effectively.
๐ ๏ธ For Power Users: Manual Setup
Prefer to build from scratch? Add MCPs manually:
bash
# Add the most popular MCPs:# AI reasoning and memory
ncp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking
ncp add memory npx @modelcontextprotocol/server-memory
# File and development tools
ncp add filesystem npx @modelcontextprotocol/server-filesystem ~/Documents # Path: directory to access
ncp add github npx @modelcontextprotocol/server-github # No path needed# Search and productivity
ncp add brave-search npx @modelcontextprotocol/server-brave-search # No path needed
๐ก Pro tip: Browse Smithery.ai (2,200+ MCPs) or mcp.so to discover tools for your specific needs.
For a legacy HTTP/SSE endpoint, set "transport": "sse". If an older profile has a URL and no transport, NCP continues to use its legacy SSE behavior. New registry imports select Streamable HTTP by default. Protocol-version negotiation is separate from transport selection and does not discover another endpoint automatically.
๐ Scale to zero - Servers automatically sleep when not needed
Note: Hibernation is a server-side feature. NCP's remote MCP client works with both traditional and hibernation-enabled servers without special configuration.
Modern MCP extensions and result handling
NCP preserves downstream tool descriptors and native MCP results through discovery and run, including structured content, error state, metadata, and text, image, audio, resource, and resource-link blocks. If an integration previously parsed JSON text that encoded an array of result blocks, update it to consume the native MCP result fields.
When a host advertises MCP Apps support, NCP selectively exposes downstream app launch tools and app callbacks, and serves their ui:// resources. The host controls whether app-only callbacks are available to the model. Tool-name and UI-resource collisions cause the affected app groups to be omitted; their ordinary tools remain available through find and run.
The Skills extension exposes local and compatible remote skill manifests on demand, including SHA-256 digests for the manifest bytes. The Tasks extension gives compatible modern hosts durable handles for run and code, with tasks/get, tasks/update, and tasks/cancel. After a restart, unfinished work is reported as interrupted rather than replayed; cancellation is reported only when NCP can confirm the worker stopped. Hosts without Tasks support keep the existing synchronous or multi-round request flow.
Response caches are bounded, and private cached entries are partitioned by server configuration and credential identity. Server cache lifetimes and tool-list change notifications guide refreshes. For transport, SDK, registry, extension, and compatibility details, see the MCP compatibility notes.
Photon Runtime (CLI vs DXT)
The TypeScript Photon runtime is enabled by default, but the toggle lives in different places depending on how you run NCP:
CLI / npm installs: Edit ~/.ncp/settings.json (or run ncp config) and set enablePhotonRuntime: true or false. You can also override adโhoc with NCP_ENABLE_PHOTON_RUNTIME=true ncp find "photon".
DXT / client bundles (Claude Desktop, Cursor, etc.): These builds ignore~/.ncp/settings.json. Configure photons by setting the env var inside the client config:
If you disable the photon runtime, internal MCPs continue to work, but .photon.ts files are ignored until you re-enable the flag.
Import from Anywhere
bash
# From clipboard (any JSON config)
ncp config import
# From specific file
ncp config import "~/my-mcp-config.json"# From Claude Desktop (auto-detected paths)
ncp config import
๐ Troubleshooting
Import Issues
bash
# 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
bash
# Check MCP health (unhealthy MCPs slow everything down)
ncp list --depth 1
# Clear cache if neededrm -rf ~/.ncp/cache
# Monitor with debug logs
DEBUG=ncp:* ncp find "test"
๐ Why We Built This
Like Yin and Yang, everything relies on the balance of things.
Compute gives us precision and certainty.
AI gives us creativity and probability.
We believe breakthrough products emerge when you combine these forces in the right ratio.
How NCP embodies this balance:
What NCP Does
AI (Creativity)
Compute (Precision)
The Balance
Tool Discovery
Understands "read a file" semantically
Routes to exact tool deterministically
Natural request โ Precise execution
Orchestration
Flexible to your intent
Reliable tool execution
Natural flow โ Certain outcomes
Health Monitoring
Adapts to patterns
Monitors connections, auto-failover
Smart adaptation โ Reliable uptime
Neither pure AI (too unpredictable) nor pure compute (too rigid).
Your AI stays creative. NCP handles the precision.
๐ Deep Dive: How It Works
A reproducible gateway benchmark measures serialized payload sizes, local latency, workflow completion, and result fidelity. Run npm run benchmark:mcp; its byte-based token proxy is labeled separately from actual tokenizer measurements.
Want the technical details? Token analysis, architecture diagrams, and performance benchmarks: