# NCP MCP server

> Unifies many MCP tools behind a single gateway so an AI client can find, run, and schedule tools and skills on demand.

- Repository: https://github.com/portel-dev/ncp
- Page: https://hostedmcp.org/servers/portel-dev/ncp
- Transport: stdio
- Stars: 102
- Latest version: 3.0.0

## Install

### Claude Code

```sh
claude mcp add ncp -- npx -y @portel/ncp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "ncp": {
      "command": "npx",
      "args": [
        "-y",
        "@portel/ncp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "ncp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@portel/ncp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"ncp","type":"stdio","command":"npx","args":["-y","@portel/ncp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "ncp": {
      "command": "npx",
      "args": [
        "-y",
        "@portel/ncp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add ncp -- npx -y @portel/ncp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.ncp]
command = "npx"
args = ["-y", "@portel/ncp"]
```

### Gemini CLI

```sh
gemini mcp add -s user ncp npx -- -y @portel/ncp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "ncp": {
      "command": "npx",
      "args": [
        "-y",
        "@portel/ncp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `NCP_DEBUG` | no | no | Enable debug logging for troubleshooting |
| `NCP_ENABLE_PHOTON_RUNTIME` | no | no |  |
| `NCP_MODE` | no | no | Operating mode: 'mcp' for AI assistant integration or 'cli' for command-line |
| `NO_COLOR` | no | no | Disable colored output in logs and CLI |

## Tools (2)

- `code`: Execute TypeScript code with automatic tool discovery and parameter mapping. **PRIMARY METHOD - ncp.do(intent, params):** Single-call execution with embedding-based param matching. No need to know exact tool names or param schemas! ncp.do("send email", { recipient: "john@example.com", // Auto-maps to "to" title: "Meeting", // Auto-maps to "subject" message: "Let's meet" // Auto-maps to "body" }) **Returns on success:** { success: true, tool, result, paramMappings } **Returns on failure:** { success: false, tool, schema, hint } - schema shows actual params needed - hint suggests corrections - Retry with correct params! **FALLBACK - Direct namespace calls (when you know exact tools):** - ncp.find("query"): Returns Tool[] with { toolName, schema, confidence } - namespace.tool(): Direct call e.g., gmail.send_email({ to, subject, body })
- `find`: Search or list MCP tools. Call as find() - no prefix needed. With description param: vector search tools by capability. Without description: list all available tools. Use pipe separator for multi-query ("gmail | slack").

## FAQ

### What does NCP do for an AI client?

NCP acts as a single gateway that lets the AI discover tools by intent, execute them, and schedule tasks instead of juggling dozens of separate MCP servers.

### How do I install NCP?

Install the npm package globally and then add an "ncp" entry running the ncp command to your client's MCP configuration.

### Which clients work with NCP?

NCP works with Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, Cline, Continue, and any other MCP-compatible client via npm.

### Does NCP support code execution?

Yes, code mode is enabled by default and lets the AI write TypeScript that calls tools directly.

### Can NCP run tasks on a schedule?

Yes, NCP supports creating scheduled tasks, such as a daily scraper, via its schedule command.
