> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prpm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers

> Publishing and installing MCP server packages with PRPM

PRPM has first-class support for publishing and installing MCP server packages. When you run `prpm install`, PRPM automatically merges server configurations into the right config file for your editor — no manual JSON editing required.

## What are MCP Servers?

**MCP (Model Context Protocol)** servers provide specialized capabilities to Claude Code and other AI clients, like:

* File system operations
* Database queries
* Web search
* Cloud resource management (Azure, AWS, GCP)
* Custom tools and APIs
* Third-party integrations (Slack, GitHub, Notion, etc.)

Think of MCP servers as tools that extend what AI assistants can do.

## Why Publish MCP Servers to PRPM?

PRPM provides dedicated installation logic that handles the complexity of MCP server configuration across editors:

* **Multi-editor support** — A single `prpm install` automatically configures the server for Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini, Kiro, Trae, Amp, Zed, and OpenCode
* **Local and global installs** — Install to a project (`.mcp.json`) or globally (`~/.claude/settings.json`) with the `--global` flag
* **Config merging** — PRPM merges server entries into existing config files without overwriting your other servers
* **Lockfile tracking** — Installations are tracked in `prpm.lock` for clean uninstalls that don't remove your manual configurations
* **One command** — No need to manually edit JSON config files for each editor

### Editor Config Locations

When you run `prpm install`, MCP server configs are written to the correct location automatically:

| Editor      | Local Config              | Global Config                         |
| ----------- | ------------------------- | ------------------------------------- |
| Claude Code | `.mcp.json`               | `~/.claude/settings.json`             |
| Cursor      | `.cursor/mcp.json`        | `~/.cursor/mcp.json`                  |
| VS Code     | `.vscode/mcp.json`        | Platform-specific                     |
| Codex       | `.codex/config.toml`      | `~/.codex/config.toml`                |
| Windsurf    | —                         | `~/.codeium/windsurf/mcp_config.json` |
| Gemini      | `.gemini/settings.json`   | `~/.gemini/settings.json`             |
| Kiro        | `.kiro/settings/mcp.json` | `~/.kiro/settings/mcp.json`           |
| OpenCode    | `opencode.json`           | `~/.config/opencode/opencode.json`    |
| Trae        | `.trae/mcp.json`          | —                                     |
| Amp         | `.amp/settings.json`      | `~/.amp/settings.json`                |
| Zed         | —                         | `~/.config/zed/settings.json`         |

## Publishing an MCP Server Package

### 1. Create the MCP Server Config File

Create a JSON file that defines your MCP server(s). This follows the standard MCP server configuration format:

```json mcp-server.json theme={null}
{
  "name": "My MCP Server",
  "description": "What this MCP server does",
  "version": "1.0.0",
  "author": "Your Name",
  "license": "MIT",
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}
```

Each server entry in `mcpServers` supports:

| Field     | Required       | Description                                                   |
| --------- | -------------- | ------------------------------------------------------------- |
| `command` | Yes (stdio)    | Command to execute                                            |
| `args`    | No             | Command arguments                                             |
| `env`     | No             | Environment variables (use `${VAR}` for user-provided values) |
| `url`     | Yes (http/sse) | Server URL for remote servers                                 |
| `type`    | No             | Connection type: `stdio` (default), `http`, or `sse`          |

### 2. Add to prpm.json

Reference the config file in your `prpm.json` with `format: "mcp"` and `subtype: "tool"`:

**Single package:**

```json prpm.json theme={null}
{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "description": "MCP server for interacting with my service",
  "author": "Your Name",
  "license": "MIT",
  "format": "mcp",
  "subtype": "tool",
  "tags": ["mcp", "mcp-server", "my-service"],
  "files": ["mcp-server.json"]
}
```

**Multi-package repository:**

```json prpm.json theme={null}
{
  "name": "my-packages",
  "author": "Your Name",
  "license": "MIT",
  "repository": "https://github.com/username/repo",
  "packages": [
    {
      "name": "my-mcp-server",
      "version": "1.0.0",
      "description": "MCP server for interacting with my service",
      "format": "mcp",
      "subtype": "tool",
      "tags": ["mcp", "mcp-server"],
      "files": ["path/to/mcp-server.json"]
    }
  ]
}
```

### 3. Publish

```bash theme={null}
prpm publish
```

## Installing MCP Server Packages

```bash theme={null}
# Install to local project (writes to .mcp.json for Claude Code)
prpm install @org/my-mcp-server

# Install globally
prpm install @org/my-mcp-server --global

# Install for a specific editor
prpm install @org/my-mcp-server --as cursor
prpm install @org/my-mcp-server --as vscode --global
```

## MCP Servers + PRPM Collections

MCP server packages work alongside other PRPM packages. Install prompts, rules, and agents alongside MCP servers from the same registry:

```bash theme={null}
# Install development prompts and rules
prpm install @prpm/typescript-best-practices

# Install an MCP server for database access
prpm install @org/postgres-mcp-server
```

## Other MCP Server Catalogs

If you're looking for existing MCP servers to use (not publish), these catalogs are also available:

* **[Smithery](https://smithery.ai)** — Large catalog with a CLI for installing servers
* **[MCP Server Finder](https://mcpserverfinder.com)** — Directory with implementation guides
* **[Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)** — Curated GitHub list
* **[Official MCP Servers](https://github.com/modelcontextprotocol/servers)** — Reference implementations by Anthropic
* **[Composio](https://composio.dev)** — Pre-built integrations (Gmail, Linear, Slack, etc.)

## FAQ

<AccordionGroup>
  <Accordion title="What format and subtype should I use for MCP servers?">
    Use `format: "mcp"` and `subtype: "tool"`. MCP servers provide tools to AI clients, so `tool` is the appropriate subtype.
  </Accordion>

  <Accordion title="What should the MCP server JSON file contain?">
    A JSON object with a `name` field and a `mcpServers` object containing one or more server configurations. Each server needs either a `command` (for stdio servers) or a `url` (for HTTP/SSE servers).
  </Accordion>

  <Accordion title="Can I publish multiple servers in one package?">
    Yes. The `mcpServers` object can contain multiple server entries. All servers in the package will be merged into the user's config on install.
  </Accordion>

  <Accordion title="How does PRPM handle uninstalls?">
    PRPM tracks which servers it installed via `prpm.lock`. On uninstall, it removes only the servers it added, leaving your manually configured servers untouched.
  </Accordion>

  <Accordion title="Which editors are supported?">
    PRPM can install MCP server configs for Claude Code, Cursor, VS Code, Codex, Windsurf, Gemini, Kiro, OpenCode, Trae, Amp, and Zed. Use the `--as` flag to target a specific editor (e.g., `--as cursor`).
  </Accordion>

  <Accordion title="Do I need MCP servers to use PRPM?">
    No. PRPM packages like rules, agents, and skills work on their own. MCP servers are an additional package type you can publish and install through the same registry.
  </Accordion>
</AccordionGroup>