MCP Server Management

rolecraft can install and manage Model Context Protocol (MCP) servers alongside skills. This means you can provision both behavior (skills) and capabilities (MCP tools) for your AI agents in a single workflow.

Why MCP + Skills Together?

• Skill → changes how an agent behaves (coding rules, style guides, conventions)
• MCP → expands what an agent can do (query databases, call APIs, access GitHub, search the web)

When a SKILL.md declares mcp_servers: in its frontmatter, rolecraft install installs both the skill and its required MCP servers in one command — no manual config editing.

Quick Start

# Install from npm (Node.js)
rolecraft mcp install npm:@modelcontextprotocol/github --cursor --claude

# Install from GitHub (Node.js)
rolecraft mcp install gh:github/github-mcp-server --all

# Install from Python (uvx)
rolecraft mcp install uvx:@anthropic/postgres-mcp --cursor

# Install from Python (pipx)
rolecraft mcp install pipx:postgres-mcp --cursor

# Install from Go
rolecraft mcp install go:github.com/org/mcp-server --all

# Install from Deno
rolecraft mcp install deno:jsr:@org/mcp-server --all

# Install from Rust (cargo)
rolecraft mcp install cargo:my-mcp-server --cursor

# Pin to a specific version
rolecraft mcp install npm:@modelcontextprotocol/github@1.2.3 --cursor

# Pin to a branch or tag (GitHub source)
rolecraft mcp install gh:github/github-mcp-server@main --all
rolecraft mcp install gh:github/github-mcp-server@v1.0.0 --cursor

# Install from a local path
rolecraft mcp install ./my-mcp-server --cursor

# List configured MCP servers
rolecraft mcp list

# Search for MCP servers (GitHub)
rolecraft mcp search github

# Search npm registry for MCP packages
rolecraft mcp search postgres --npm

# Interactive search + install
rolecraft mcp search filesystem --interactive

# Check for MCP server updates
rolecraft mcp check

# Update a MCP server to latest version
rolecraft mcp update npm:@modelcontextprotocol/github --cursor

# Remove an MCP server
rolecraft mcp remove github-mcp-server --cursor

# Validate MCP configurations
rolecraft doctor

Onboarding Example

Suppose your team has three developers using different agents — Cursor, Claude Code, and Windsurf. You want everyone to use the same PostgreSQL conventions and have database access via MCP:

1. Create a skill with mcp_servers

---
name: my-postgres-rules
description: Team PostgreSQL style guide
mcp_servers:
  - name: github
    source: gh:github/github-mcp-server
  - name: postgres
    source: npm:@anthropic/postgres-mcp
---

- Always prefer `JOIN` over subqueries
- `SELECT *` is forbidden
- All queries must be parameterized

2. Install with a single command

rolecraft install ./my-postgres-rules --cursor --claude --windsurf

This does three things automatically:

1. Skill installation → copies my-postgres-rules to ~/.cursor/skills/, ~/.claude/skills/, ~/.codeium/windsurf/skills/
2. MCP installation → reads mcp_servers from SKILL.md, resolves the sources
3. Config wiring → writes MCP config in each agent's native format:
   • Cursor: ~/.cursor/mcp.json
   • Claude Code: ~/.claude.json
   • Windsurf: ~/.windsurf/mcp_config.json

3. Each agent can now

• Follow rules — never writes SELECT *, always uses JOIN
• Query the database — via the Postgres MCP server
• Access GitHub — via the GitHub MCP server

4. Team onboarding with bundle

# Team lead creates a bundle once
rolecraft bundle create team-onboarding

# Every developer runs
rolecraft bundle install team-onboarding.json
# → All skills installed
# → All MCP servers configured automatically
# → Each agent's config written in the correct format

Supported MCP Agents

Agent	Config File	Format
opencode	~/.agents/mcp.json	Standard mcpServers object
claude-code	~/.claude.json	Standard mcpServers object
cursor	~/.cursor/mcp.json	Standard mcpServers object
windsurf	~/.windsurf/mcp_config.json	Standard mcpServers object
devin	./.devin/mcp.json	Standard mcpServers object
copilot	./.github/copilot/.mcp.json	{ inputs: [], servers: {} }
continue	~/.continue/config.json	{ experimental: { mcpServers: [] } }

More agents will be added as their MCP standards solidify.

Source Types

Source	Example	Description
npm:	npm:@modelcontextprotocol/github	Install from npm, runs via npx -y
gh:	gh:github/github-mcp-server	Clone from GitHub, runs via node
uvx:	uvx:@anthropic/postgres-mcp	Python package via uvx
pipx:	pipx:postgres-mcp	Python package via pipx run
go:	go:github.com/org/mcp-server	Go package via go run
deno:	deno:jsr:@org/mcp-server	Deno module via deno run
cargo:	cargo:my-mcp-server	Rust crate via cargo run
Local path	./my-mcp-server/index.js	Run directly with node

Where gh: servers are cloned

gh: servers run from a path on disk, so that path has to survive. Each one is cloned to ~/.agents/mcp/<owner-repo>[@ref]/repo — rolecraft's own directory, not the OS temp dir, which is swept on a schedule rolecraft does not control.

Installing the same source again replaces its own clone rather than leaving the old one behind. A server name with a ref (gh:owner/repo@v1.0.0) gets its own directory, so two versions of one repo do not overwrite each other.

rolecraft mcp list checks every absolute path in a server entry and marks the ones that no longer exist, so an entry whose files went missing is reported instead of listed as healthy. Removing a server leaves its clone on disk.

Security Scanning

When installing from gh: sources, rolecraft automatically scans the cloned repository for security issues before installation:

Severity	Example	Score Impact
🔴 Critical	Command injection (curl | bash)	-20
🔴 High	Credential access (process.env.TOKEN), data exfiltration	-10
🟡 Medium	Network requests, file access, shell execution, env access	-3
⚪ Low	Untrusted publisher, npm registry source	-1

The scan produces a score (0-100):

Score	Label	Behavior
90-100	✅ Safe	Installs normally
70-89	⚠️ Review	Shows warning, continues
0-69	❌ Danger	Blocks install unless --yes is passed

# Security scan runs automatically during install
rolecraft mcp install gh:untrusted-user/mcp-server
# → Shows scan report before confirmation prompt

# Skip security block with --yes
rolecraft mcp install gh:untrusted-user/mcp-server --yes

Trusted Publishers

Repositories from these publishers are not flagged with low-severity untrusted publisher warnings: github, modelcontextprotocol, anthropic, vercel, openai

Lockfile & CI Restore

Every MCP server you install is tracked in ~/.agents/.mcp-lock.json. This lockfile records:

• The original source string (e.g. npm:@modelcontextprotocol/github)
• Which agents the server is installed to

When you run rolecraft ci, MCP servers from the lockfile are automatically re-installed to their configured agents — just like skills.

# After git clone — restores skills + MCP servers
rolecraft ci

The lockfile updates automatically:

• Install → server is added to the lockfile
• Remove → server is removed from the lockfile (or agents are unlinked if installed elsewhere)
• Update → lockfile is refreshed with the new source

Commands

See docs/commands/mcp.md for the full command reference.

SKILL.md Integration

When a skill declares mcp_servers: in its YAML frontmatter, rolecraft install automatically installs those MCP servers to the same agent targets. You don't need to run a separate rolecraft mcp install command.

---
name: my-skill
mcp_servers:
  - name: server-name
    source: npm:@org/mcp-server
---

If you only want the skill without MCP servers, pass --no-mcp during installation.

Security approval for npm sources

npm package contents are not currently fetched for scanning. Both rolecraft mcp install npm:… and a skill with an embedded npm MCP server require --yes after you review and trust the source (API: yes: true). Without approval they report MCP_SECURITY_REVIEW. rolecraft ci fails unscanned npm entries from the global MCP lock instead of silently reinstalling them; it has no --yes override. Scanned gh: sources keep their existing REVIEW/DANGER policy.

See also

• rolecraft mcp command — subcommands, source types, and pinning.
• Agent Discovery — the 9 MCP-capable agents and their directories.
• Glossary — what an MCP server is in rolecraft terms.