Skip to content
Back to search

ncp

Natural Context Provider (NCP). Your MCPs, supercharged. Find any tool instantly, load on demand, run on schedule, ready for any client. Smart loading saves tokens and energy.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/portel-dev--ncp/badge.svg)](/listings/portel-dev--ncp)

HTML

<a href="/listings/portel-dev--ncp"><img src="/api/listings/portel-dev--ncp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 | **[→ Full Guide](docs/clients/claude-desktop.md)** | | **Claude Code** | Terminal-first AI workflow. Works out of the box! | Built-in support | | **VS Code** | GitHub Copilot with Agent Mode. Use NCP for semantic tool discovery | **[→ Setup](docs/clients/vscode.md)** | | **Cursor** | AI-first code editor with Composer. Popular VS Code alternative | **[→ Setup](docs/clients/cursor.md)** | | **Windsurf** | Codeium's AI-native IDE with Cascade. Built on VS Code | **[→ Setup](docs/clients/windsurf.md)** | | **Cline** | VS Code extension for AI-assisted development with MCP support | **[→ Setup](docs/clients/cline.md)** | | **Continue** | VS Code AI assistant with Agent Mode and local LLM support | **[→ Setup](docs/clients/continue.md)** | | **Want more clients?** | See the full list of MCP-compatible clients and tools | [Official MCP Clients](https://github.com/modelcontextprotocol/servers#clients) • [Awesome MCP](https://github.com/punkpeye/awesome-mcp) | | **Other Clients** | Any MCP-compatible client via npm | [Quick Start ↓](#quick-start-npm) |

---

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 now sees just 2 tools instead of 50+.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 780 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![npm version](https://img.shields.io/npm/v/%40portel%2Fncp.svg)](https://www.npmjs.com/package/@portel/ncp)
  2. [![npm downloads](https://img.shields.io/npm/dt/@portel/ncp?label=downloads)](https://www.npmjs.com/package/@portel/ncp)
  3. [![GitHub release downloads](https://img.shields.io/github/downloads/portel-dev/ncp/total?label=.dxt%20downloads)](https://github.com/portel-dev/ncp/releases)
  4. [![Latest release](https://img.shields.io/github/downloads/portel-dev/ncp/latest/total?label=latest%20.dxt)](https://github.com/portel-dev/ncp/releases/latest)
  5. [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic--2.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
  6. [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)
  7. <!-- mcp-name: io.github.portel-dev/ncp -->
  8. <div align="center">
  9. <img src="./assets/ncp.svg" alt="NCP Logo" width="200" height="200">
  10. # NCP - Natural Context Provider
  11. > **1 MCP to rule them all**
  12. </div>
  13. Your MCPs, [supercharged](#-supercharged-features). 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.
  14. **Related Portel project:** [Photon](https://photon.portel.dev/) 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.
  15. ## 💍 **What is NCP?**
  16. 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**.
  17. 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.
  18. - **`find`** - Search for any tool, skill, or Photon: "I need to read a file" → finds the right tool automatically
  19. - **`code`** - Execute TypeScript directly: `await github.create_issue({...})` (code mode, enabled by default)
  20. - **`run`** - Execute tools individually (when code mode is disabled)
  21. 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.
  22. 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.
  23. ![NCP Transformation Flow](docs/images/ncp-transformation-flow.png)
  24. **Why this matters:**
  25. - Your AI stops analyzing "which tool do I use?" and starts doing actual work
  26. - **Code mode** lets AI write multi-step TypeScript workflows combining tools, skills, and scheduling
  27. - **Skills** provide domain expertise: canvas design, PDF manipulation, document generation, more
  28. - **Photons** enable custom TypeScript MCPs without npm publishing
  29. - **On-demand discovery** keeps the initial tool surface focused; actual context use depends on the host, enabled NCP tools, and connected servers
  30. - **Your AI becomes focused.** Not desperate.
  31. 🚀 **NEW:** Project-level configuration - each project can define its own MCPs automatically
  32. > **What's MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) 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.
  33. ---
  34. ## 📑 **Quick Navigation**
  35. - [The Problem](#-the-mcp-paradox-from-assistant-to-desperate) - Why too many tools break your AI
  36. - [The Solution](#-the-before--after-reality) - How NCP transforms your experience
  37. - [Getting Started](#-prerequisites) - Installation & quick start
  38. - [Try It Out](#-test-drive-see-the-difference-yourself) - See the CLI in action
  39. - [Supercharged Features](#-supercharged-features) - How NCP empowers your MCPs
  40. - [Setup by Client](#️-configuration-for-different-ai-clients) - Claude Desktop, Cursor, VS Code, etc.
  41. - [Popular MCPs](#-popular-mcps-that-work-great-with-ncp) - Community favorites to add
  42. - [Advanced Features](#-advanced-features) - Project config, scheduling, remote MCPs
  43. - [Troubleshooting](#-troubleshooting) - Common issues & solutions
  44. - [How It Works](#-deep-dive-how-it-works) - Technical deep dive
  45. - [Contributing](#-contributing) - Help us improve NCP
  46. ---
  47. ## 😤 **The MCP Paradox: From Assistant to Desperate**
  48. You gave your AI assistant 50 tools to be more capable. Instead, you got desperation:
  49. - **Paralyzed by choice** ("Should I use `read_file` or `get_file_content`?")
  50. - **Exhausted before starting** ("I've spent my context limit analyzing which tool to use")
  51. - **Costs explode** (50+ tool schemas burn tokens before any real work happens)
  52. - **Asks instead of acts** (used to be decisive, now constantly asks for clarification)
  53. ---
  54. ## 🧸 **Why Too Many Tools Break the System**
  55. Think about it like this:
  56. **A child with one toy** → Treasures it, masters it, creates endless games with it
  57. **A child with 50 toys** → Can't hold them all, gets overwhelmed, stops playing entirely
  58. **Your AI is that child.** MCPs are the toys. More isn't always better.
  59. 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.
  60. **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.
  61. ---
  62. ## 📊 **The Before & After Reality**
  63. ### **Before NCP: Desperate Assistant** 😵‍💫
  64. When your AI assistant manages 50 tools directly:
  65. ```
  66. 🤖 AI Assistant Context:
  67. ├── Filesystem MCP (12 tools)
  68. ├── Database MCP (8 tools)
  69. ├── Web Search MCP (6 tools)
  70. ├── Email MCP (15 tools)
  71. ├── Shell MCP (10 tools)
  72. ├── GitHub MCP (20 tools)
  73. └── Slack MCP (9 tools)
  74. 💀 Total: 80 tool schemas compete for attention before useful work begins
  75. ```
  76. **What happens:**
  77. - AI burns 50%+ of context just understanding what tools exist
  78. - Spends 5-8 seconds analyzing which tool to use
  79. - Often picks wrong tool due to schema confusion
  80. - Hits context limits mid-conversation
  81. ### **After NCP: Executive Assistant** ✨
  82. With NCP as Chief of Staff:
  83. ```
  84. 🤖 AI Assistant Context:
  85. └── NCP gateway tools → discover and run the tools needed for this request
  86. 🎯 Behind the scenes: NCP manages all 80 tools
  87. 📈 Tool discovery happens on demand
  88. 🎪 AI behavior: Confident, focused, decisive
  89. ```
  90. 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.
  91. ---
  92. ## 📋 **Prerequisites**
  93. - **Node.js 22+** (Node.js 24 recommended; CI uses 24) ([Download here](https://nodejs.org/))
  94. - **npm** (included with Node.js) or **npx** for running packages
  95. - **Command line access** (Terminal on Mac/Linux, Command Prompt/PowerShell on Windows)
  96. ## 🚀 **Installation**
  97. Choose your MCP client for setup instructions:
  98. | Client | Description | Setup Guide |
  99. |--------|-------------|-------------|
  100. | **Claude Desktop** | Anthropic's official desktop app. **Best for NCP** - one-click .dxt install with auto-sync | **[→ Full Guide](docs/clients/claude-desktop.md)** |
  101. | **Claude Code** | Terminal-first AI workflow. Works out of the box! | Built-in support |
  102. | **VS Code** | GitHub Copilot with Agent Mode. Use NCP for semantic tool discovery | **[→ Setup](docs/clients/vscode.md)** |
  103. | **Cursor** | AI-first code editor with Composer. Popular VS Code alternative | **[→ Setup](docs/clients/cursor.md)** |
  104. | **Windsurf** | Codeium's AI-native IDE with Cascade. Built on VS Code | **[→ Setup](docs/clients/windsurf.md)** |
  105. | **Cline** | VS Code extension for AI-assisted development with MCP support | **[→ Setup](docs/clients/cline.md)** |
  106. | **Continue** | VS Code AI assistant with Agent Mode and local LLM support | **[→ Setup](docs/clients/continue.md)** |
  107. | **Want more clients?** | See the full list of MCP-compatible clients and tools | [Official MCP Clients](https://github.com/modelcontextprotocol/servers#clients) • [Awesome MCP](https://github.com/punkpeye/awesome-mcp) |
  108. | **Other Clients** | Any MCP-compatible client via npm | [Quick Start ↓](#quick-start-npm) |
  109. ---
  110. ### Quick Start (npm)
  111. For advanced users or MCP clients not listed above:
  112. **Step 1: Install NCP**
  113. ```bash
  114. npm install -g @portel/ncp
  115. ```
  116. **Step 2: Import existing MCPs (optional)**
  117. ```bash
  118. ncp config import # Paste your config JSON when prompted
  119. ```
  120. **Step 3: Configure your MCP client**
  121. Add to your client's MCP configuration:
  122. ```json
  123. {
  124. "mcpServers": {
  125. "ncp": {
  126. "command": "ncp"
  127. }
  128. }
  129. }
  130. ```
  131. **✅ Done!** Your AI can discover and run tools through NCP. Hosts with MCP Apps support may also receive selected app callback tools.
  132. ![NCP List Overview](docs/images/ncp-list.png)
  133. ---
  134. ## 🧪 **Test Drive: See the Difference Yourself**
  135. Want to experience what your AI experiences? NCP has a human-friendly CLI:
  136. ### **🔍 Smart Discovery**
  137. ```bash
  138. # Ask like your AI would ask:
  139. ncp find "I need to read a file"
  140. ncp find "help me send an email"
  141. ncp find "search for something online"
  142. ```
  143. ![NCP Find Command](docs/images/ncp-find.png)
  144. **Notice:** NCP understands intent, not just keywords. Just like your AI needs.
  145. ### **📋 Ecosystem Overview**
  146. ```bash
  147. # See your complete MCP ecosystem:
  148. ncp list --depth 2
  149. # Get help anytime:
  150. ncp --help
  151. ```
  152. ![NCP Help Command](docs/images/ncp-help.png)
  153. ### **⚡ Direct Testing**
  154. ```bash
  155. # Test any tool safely:
  156. ncp run filesystem read_file --path "/tmp/test.txt"
  157. ```
  158. **Why this matters:** You can debug and test tools directly, just like your AI would use them.
  159. ### **✅ Verify Everything Works**
  160. ```bash
  161. # 1. Check NCP is installed correctly
  162. ncp --version
  163. # 2. Confirm your MCPs are imported
  164. ncp list
  165. # 3. Test tool discovery
  166. ncp find "file"
  167. # 4. Test a simple tool (if you have filesystem MCP)
  168. ncp run filesystem read_file --path "/tmp/test.txt" --dry-run
  169. ```
  170. **✅ Success indicators:**
  171. - NCP shows version number
  172. - `ncp list` shows your imported MCPs
  173. - `ncp find` returns relevant tools
  174. - Your AI client shows NCP's gateway tools; an Apps-capable host may also show selected app callback tools
  175. ---
  176. ## 💪 **From Tools to Automation: The Real Power**
  177. You've seen `find` (discover tools) and `code` (execute TypeScript). Individually, they're useful. **Together with scheduling, they become an automation powerhouse.**
  178. ### A Real Example: The MCP Conference Scraper
  179. 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:
  180. > "Set up a daily scraper that finds MCP conferences and saves them to a CSV file"
  181. **What Claude did:**
  182. 1. **Used `code` to write the automation:**
  183. ```typescript
  184. // Search the web for MCP conferences
  185. const results = await web.search({
  186. query: "Model Context Protocol conference 2025"
  187. });
  188. // Read each result and extract details
  189. for (const url of results) {
  190. const content = await web.read({ url });
  191. // Extract title, deadline, description...
  192. // Save to ~/.ncp/mcp-conferences.csv
  193. }
  194. ```
  195. 2. **Used `schedule` to automate it:**
  196. ```bash
  197. ncp schedule create code:run "every day at 9am" \
  198. --name "MCP Conference Scraper" \
  199. --catchup-missed
  200. ```
  201. **How to set this up yourself:**
  202. First, install the web photon (provides search and read capabilities):
  203. ```bash
  204. # Install from the official photons repo
  205. ncp photon add https://raw.githubusercontent.com/portel-dev/photons/main/web.photon.ts
  206. ```
  207. Then ask Claude to create the scraper - it will use the web photon automatically.
  208. **What happens now:**
  209. - Every morning at 9am, the scraper runs automatically
  210. - Searches for new MCP events and adds them to the CSV
  211. - If our laptop was closed at 9am, it catches up when we open it
  212. - We wake up to fresh conference data - no manual work
  213. **The insight:** `find` and `code` let AI write automation. `schedule` makes it run forever. That's the powerhouse.
  214. ---
  215. ## 💡 **Why NCP Transforms Your AI Experience**
  216. ### **🧠 From Desperation to Delegation**
  217. - **Desperate Assistant:** "I see 50 tools... which should I use... let me think..."
  218. - **Executive Assistant:** "I need file access. Done." *(NCP handles the details)*
  219. ### **💰 Focused Tool Discovery**
  220. - NCP lets the host search a larger tool catalog on demand
  221. - The context impact depends on your host and enabled tool surface
  222. ### **🎯 Eliminates Choice Paralysis**
  223. - **Desperate:** AI freezes, picks wrong tool, asks for clarification
  224. - **Executive:** NCP's Chief of Staff finds the RIGHT tool instantly
  225. ### **🚀 Confident Action**
  226. - **Before:** 8-second delays, hesitation, "Which tool should I use?"
  227. - **After:** Instant decisions, immediate execution, zero doubt
  228. **Bottom line:** Your AI goes from desperate assistant to **executive assistant**.
  229. ---
  230. ## ⚡ **Supercharged Features**
  231. Here's exactly how NCP empowers your MCPs:
  232. | Feature | What It Does | Why It Matters |
  233. |---------|-------------|----------------|
  234. | **🔍 Tool Discovery** | Search tools by intent as well as keywords | Find relevant tools without exposing every downstream schema at once |
  235. | **📦 On-Demand Loading** | Discover downstream tools when needed | Keeps the initial tool surface focused; context savings vary by setup |
  236. | **⏰ Automated Scheduling** | Run any tool on cron schedules or natural language times | Background automation without keeping AI sessions open |
  237. | **🔌 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 |
  238. | **💾 Smart Caching** | Intelligent caching of tool schemas and responses | Eliminates redundant indexing - energy efficient and fast |
  239. **The result:** Your MCPs go from scattered tools to a **unified, intelligent system** that your AI can actually use effectively.
  240. ---
  241. ## 🛠️ **For Power Users: Manual Setup**
  242. Prefer to build from scratch? Add MCPs manually:
  243. ```bash
  244. # Add the most popular MCPs:
  245. # AI reasoning and memory
  246. ncp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking
  247. ncp add memory npx @modelcontextprotocol/server-memory
  248. # File and development tools
  249. ncp add filesystem npx @modelcontextprotocol/server-filesystem ~/Documents # Path: directory to access
  250. ncp add github npx @modelcontextprotocol/server-github # No path needed
  251. # Search and productivity
  252. ncp add brave-search npx @modelcontextprotocol/server-brave-search # No path needed
  253. ```
  254. ![NCP Add Command](docs/images/ncp-add.png)
  255. **💡 Pro tip:** Browse [Smithery.ai](https://smithery.ai) (2,200+ MCPs) or [mcp.so](https://mcp.so) to discover tools for your specific needs.
  256. ---
  257. ## 🎯 **Popular MCPs That Work Great with NCP**
  258. ### **🔥 Most Downloaded**
  259. ```bash
  260. # Community favorites (download counts from Smithery.ai):
  261. ncp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking # 5,550+ downloads
  262. ncp add memory npx @modelcontextprotocol/server-memory # 4,200+ downloads
  263. ncp add brave-search npx @modelcontextprotocol/server-brave-search # 680+ downloads
  264. ```
  265. ### **🛠️ Development Essentials**
  266. ```bash
  267. # Popular dev tools:
  268. ncp add filesystem npx @modelcontextprotocol/server-filesystem ~/code
  269. ncp add github npx @modelcontextprotocol/server-github
  270. ncp add shell npx @modelcontextprotocol/server-shell
  271. ```
  272. ### **🌐 Productivity & Integrations**
  273. ```bash
  274. # Enterprise favorites:
  275. ncp add gmail npx @mcptools/gmail-mcp
  276. ncp add slack npx @modelcontextprotocol/server-slack
  277. ncp add google-drive npx @modelcontextprotocol/server-gdrive
  278. ncp add postgres npx @modelcontextprotocol/server-postgres
  279. ncp add puppeteer npx @hisma/server-puppeteer
  280. ```
  281. ## 🤖 **Internal MCPs**
  282. NCP includes powerful internal MCPs that extend functionality beyond external tool orchestration:
  283. ### **Scheduler MCP** - Automate Any Tool
  284. Schedule any MCP tool to run automatically using cron or natural language schedules.
  285. ```bash
  286. # Schedule a daily backup check
  287. ncp run schedule:create --params '{
  288. "name": "Daily Backup",
  289. "schedule": "every day at 2am",
  290. "tool": "filesystem:list_directory",
  291. "parameters": {"path": "/backups"}
  292. }'
  293. ```
  294. **Features:**
  295. - ✅ Natural language schedules ("every day at 9am", "every monday")
  296. - ✅ Standard cron expressions for advanced control
  297. - ✅ Automatic validation before scheduling
  298. - ✅ Execution history and monitoring
  299. - ✅ Works even when NCP is not running (system cron integration)
  300. **[→ Full Scheduler Guide](docs/SCHEDULER_USER_GUIDE.md)**
  301. ### **MCP Management MCP** - Install MCPs from AI
  302. Install and configure MCPs dynamically through natural language.
  303. ```bash
  304. # AI can discover and install MCPs for you
  305. ncp find "install mcp"
  306. # Shows: mcp:add, mcp:remove, mcp:list
  307. ```
  308. **Features:**
  309. - ✅ Search and discover MCPs from registries
  310. - ✅ Install MCPs without manual configuration
  311. - ✅ Update and remove MCPs programmatically
  312. - ✅ AI can self-extend with new capabilities
  313. ### **Skills Management MCP** - Extend Claude with Plugins
  314. Manage Anthropic Agent Skills - modular extensions that add specialized knowledge and tools to Claude.
  315. ```typescript
  316. // Discover skills using vector search
  317. const results = await skills.find({ query: "canvas design" });
  318. // Install a skill
  319. await skills.add({ skill_name: "canvas-design" });
  320. // List installed skills
  321. const installed = await skills.list();
  322. // Read skill resources
  323. const template = await skills.read_resource({
  324. skill_name: "canvas-design",
  325. file_path: "resources/templates.md"
  326. });
  327. ```
  328. **Features:**
  329. - ✅ Vector-powered semantic search for skills
  330. - ✅ One-command install from official marketplace
  331. - ✅ Progressive disclosure (metadata → full content → resources)
  332. - ✅ Official Anthropic marketplace integration
  333. - ✅ Custom marketplace support
  334. - ✅ Auto-loading of installed skills
  335. **[→ Full Skills Guide](./SKILLS.md)**
  336. ### **Analytics MCP** - Visualize Usage & Performance
  337. View usage statistics, token savings, and performance metrics directly in your chat.
  338. ```bash
  339. # View usage overview with ASCII charts
  340. ncp run analytics:overview --params '{"period": 7}'
  341. ```
  342. **Features:**
  343. - ✅ Usage trends and most used tools
  344. - ✅ Token savings analysis (Code-Mode efficiency)
  345. - ✅ Performance metrics (response times, error rates)
  346. - ✅ ASCII-formatted charts for AI consumption
  347. **Configuration:**
  348. Internal MCPs are disabled by default. Enable in your profile settings:
  349. ```json
  350. {
  351. "settings": {
  352. "enable_schedule_mcp": true,
  353. "enable_mcp_management": true,
  354. "enable_skills": true,
  355. "enable_analytics_mcp": true
  356. }
  357. }
  358. ```
  359. ---
  360. ## 🔧 **Advanced Features**
  361. ### **Smart Health Monitoring**
  362. NCP automatically detects broken MCPs and routes around them:
  363. ```bash
  364. ncp list --depth 1 # See health status
  365. ncp config validate # Check configuration health
  366. ```
  367. **🎯 Result:** Your AI never gets stuck on broken tools.
  368. ### **Multi-Profile Organization**
  369. Organize MCPs by project or environment:
  370. ```bash
  371. # Development setup
  372. ncp add --profile dev filesystem npx @modelcontextprotocol/server-filesystem ~/dev
  373. # Production setup
  374. ncp add --profile prod database npx production-db-server
  375. # Use specific profile
  376. ncp --profile dev find "file tools"
  377. ```
  378. ### **🚀 Project-Level Configuration**
  379. **New:** Configure MCPs per project with automatic detection - perfect for teams and Cloud IDEs:
  380. ```bash
  381. # In any project directory, create local MCP configuration:
  382. mkdir .ncp
  383. ncp add filesystem npx @modelcontextprotocol/server-filesystem ./
  384. ncp add github npx @modelcontextprotocol/server-github
  385. # NCP automatically detects and uses project-local configuration
  386. ncp find "save file" # Uses only project MCPs
  387. ```
  388. **How it works:**
  389. - 📁 **Local `.ncp` directory exists** → Uses project configuration
  390. - 🏠 **No local `.ncp` directory** → Falls back to global `~/.ncp`
  391. - 🎯 **Zero profile management needed** → Everything goes to default `all.json`
  392. **Perfect for:**
  393. - 🤖 **Claude Code projects** (project-specific MCP tooling)
  394. - 👥 **Team consistency** (ship `.ncp` folder with your repo)
  395. - 🔧 **Project-specific tooling** (each project defines its own MCPs)
  396. - 📦 **Environment isolation** (no global MCP conflicts)
  397. ```bash
  398. # Example project structures:
  399. frontend-app/
  400. .ncp/profiles/all.json # → playwright, lighthouse, browser-context
  401. src/
  402. api-backend/
  403. .ncp/profiles/all.json # → postgres, redis, docker, kubernetes
  404. server/
  405. ```
  406. ### **Remote MCP Transports and Hibernation Support**
  407. NCP supports both **stdio** (local) and **HTTP/SSE** (remote) MCP servers:
  408. **Stdio Transport** (Traditional):
  409. ```bash
  410. # Local MCP servers running as processes
  411. ncp add filesystem npx @modelcontextprotocol/server-filesystem ~/Documents
  412. ```
  413. **Streamable HTTP** (Remote):
  414. ```json
  415. {
  416. "mcpServers": {
  417. "remote-mcp": {
  418. "url": "https://mcp.example.com/api",
  419. "transport": "streamableHttp",
  420. "auth": {
  421. "type": "bearer",
  422. "token": "your-token-here"
  423. }
  424. }
  425. }
  426. }
  427. ```
  428. 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.
  429. **OAuth 2.1 with PKCE** (MCP 2025-03-26 spec):
  430. ```json
  431. {
  432. "mcpServers": {
  433. "oauth-mcp": {
  434. "url": "https://mcp.example.com/api",
  435. "auth": {
  436. "type": "oauth",
  437. "oauth21": {
  438. "scopes": ["read", "write"],
  439. "callbackPort": 9876,
  440. "clientId": "optional-pre-registered-client-id",
  441. "clientSecret": "optional-client-secret"
  442. }
  443. }
  444. }
  445. }
  446. }
  447. ```
  448. **OAuth 2.1 Features:**
  449. - ✅ **PKCE (Proof Key for Code Exchange)** - Required by OAuth 2.1 for security
  450. - ✅ **Dynamic Client Registration (RFC 7591)** - Auto-registers if no clientId provided
  451. - ✅ **Token Storage & Auto-Refresh** - Tokens saved to `~/.ncp/auth/` and refreshed automatically
  452. - ✅ **Browser Authorization Flow** - Opens browser for user consent
  453. - ✅ **Headless Fallback** - Manual code entry for servers/CI environments
  454. - ✅ **Protected Resource Discovery (RFC 9728)** - Auto-discovers OAuth endpoints
  455. **First-time setup flow:**
  456. 1. NCP opens browser to authorization URL
  457. 2. You grant permissions
  458. 3. Browser redirects to local callback (`http://localhost:9876`)
  459. 4. NCP exchanges code for access token (with PKCE)
  460. 5. Token saved and refreshed automatically for future requests
  461. **🔋 Hibernation-Enabled Servers:**
  462. NCP automatically supports hibernation-enabled MCP servers (like Cloudflare Durable Objects or Metorial):
  463. - **Zero configuration needed** - Hibernation works transparently
  464. - **Automatic wake-up** - Server wakes on demand when NCP makes requests
  465. - **State preservation** - Server state is maintained across hibernation cycles
  466. - **Cost savings** - Only pay when MCPs are actively processing requests
  467. **How it works:**
  468. 1. Server hibernates when idle (consumes zero resources)
  469. 2. NCP sends a request → Server wakes instantly
  470. 3. Server processes request and responds
  471. 4. Server returns to hibernation after idle timeout
  472. **Perfect for:**
  473. - 💰 **Cost optimization** - Only pay for active processing time
  474. - 🌐 **Cloud-hosted MCPs** - Metorial, Cloudflare Workers, serverless platforms
  475. - ♻️ **Resource efficiency** - No idle server costs
  476. - 🚀 **Scale to zero** - Servers automatically sleep when not needed
  477. > **Note:** Hibernation is a server-side feature. NCP's remote MCP client works with both traditional and hibernation-enabled servers without special configuration.
  478. ### **Modern MCP extensions and result handling**
  479. 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.
  480. 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`.
  481. 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.
  482. 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](docs/development/mcp-compatibility.md).
  483. ### **Photon Runtime (CLI vs DXT)**
  484. The TypeScript Photon runtime is enabled by default, but the toggle lives in different places depending on how you run NCP:
  485. - **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"`.
  486. - **DXT / client bundles (Claude Desktop, Cursor, etc.):** These builds **ignore** `~/.ncp/settings.json`. Configure photons by setting the env var inside the client config:
  487. ```json
  488. {
  489. "mcpServers": {
  490. "ncp": {
  491. "command": "ncp",
  492. "env": {
  493. "NCP_ENABLE_PHOTON_RUNTIME": "true"
  494. }
  495. }
  496. }
  497. }
  498. ```
  499. If you disable the photon runtime, internal MCPs continue to work, but `.photon.ts` files are ignored until you re-enable the flag.
  500. ### **Import from Anywhere**
  501. ```bash
  502. # From clipboard (any JSON config)
  503. ncp config import
  504. # From specific file
  505. ncp config import "~/my-mcp-config.json"
  506. # From Claude Desktop (auto-detected paths)
  507. ncp config import
  508. ```
  509. ---
  510. ## 🛟 **Troubleshooting**
  511. ### **Import Issues**
  512. ```bash
  513. # Check what was imported
  514. ncp list
  515. # Validate health of imported MCPs
  516. ncp config validate
  517. # See detailed import logs
  518. DEBUG=ncp:* ncp config import
  519. ```
  520. ### **AI Not Using Tools**
  521. - **Check connection:** `ncp list` (should show your MCPs)
  522. - **Test discovery:** `ncp find "your query"`
  523. - **Validate config:** Ensure your AI client points to `ncp` command
  524. ### **Performance Issues**
  525. ```bash
  526. # Check MCP health (unhealthy MCPs slow everything down)
  527. ncp list --depth 1
  528. # Clear cache if needed
  529. rm -rf ~/.ncp/cache
  530. # Monitor with debug logs
  531. DEBUG=ncp:* ncp find "test"
  532. ```
  533. ---
  534. ## 🌓 **Why We Built This**
  535. **Like Yin and Yang, everything relies on the balance of things.**
  536. **Compute** gives us precision and certainty.
  537. **AI** gives us creativity and probability.
  538. We believe breakthrough products emerge when you combine these forces in the right ratio.
  539. **How NCP embodies this balance:**
  540. | What NCP Does | AI (Creativity) | Compute (Precision) | The Balance |
  541. |---------------|-----------------|---------------------|-------------|
  542. | **Tool Discovery** | Understands "read a file" semantically | Routes to exact tool deterministically | Natural request → Precise execution |
  543. | **Orchestration** | Flexible to your intent | Reliable tool execution | Natural flow → Certain outcomes |
  544. | **Health Monitoring** | Adapts to patterns | Monitors connections, auto-failover | Smart adaptation → Reliable uptime |
  545. Neither pure AI (too unpredictable) nor pure compute (too rigid).
  546. Your AI stays creative. NCP handles the precision.
  547. ---
  548. ## 📚 **Deep Dive: How It Works**
  549. A [reproducible gateway benchmark](docs/benchmarks/mcp-gateway.md) 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.
  550. Want the technical details? Token analysis, architecture diagrams, and performance benchmarks:
  551. 📖 **[Read the Technical Guide →](HOW-IT-WORKS.md)**
  552. Learn about:
  553. - Vector similarity search algorithms
  554. - N-to-1 orchestration architecture
  555. - Real-world token usage comparisons
  556. - Health monitoring and failover systems
  557. ---
  558. ## 🤝 **Contributing**
  559. Help make NCP even better:
  560. - 🐛 **Bug reports:** [GitHub Issues](https://github.com/portel-dev/ncp/issues)
  561. - 💡 **Feature requests:** [GitHub Discussions](https://github.com/portel-dev/ncp/discussions)
  562. - 🔄 **Pull requests:** [Contributing Guide](CONTRIBUTING.md)
  563. ---
  564. ## 📄 **License**
  565. Elastic License 2.0 - [Full License](LICENSE)
  566. **TLDR:** Free for all use including commercial. Cannot be offered as a hosted service to third parties.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.