add-mcp-server
Add an MCP server to pi. Use when asked to "add mcp server", "configure mcp", "add mcp", "new mcp server", "setup mcp", "connect mcp server", or "register mcp server". Handles both global and project-local configurations.
Best use case
add-mcp-server is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Add an MCP server to pi. Use when asked to "add mcp server", "configure mcp", "add mcp", "new mcp server", "setup mcp", "connect mcp server", or "register mcp server". Handles both global and project-local configurations.
Teams using add-mcp-server should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/add-mcp-server/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How add-mcp-server Compares
| Feature / Agent | add-mcp-server | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Add an MCP server to pi. Use when asked to "add mcp server", "configure mcp", "add mcp", "new mcp server", "setup mcp", "connect mcp server", or "register mcp server". Handles both global and project-local configurations.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Add an MCP Server
Add an MCP server configuration to `pi-mcp-adapter`. Determine scope and server type, write the config, and verify the connection.
## Step 1: Determine Scope
Ask the user if not obvious from context:
| Scope | Config File | When to Use |
|-------|-------------|-------------|
| **Global** | `~/.pi/agent/mcp.json` | Server used across all projects |
| **Project** | `.pi/mcp.json` (project root) | Server specific to one project |
Project-local configs override global ones. Both files use the same format.
## Step 2: Determine Server Type
MCP servers connect via **stdio** (local process) or **HTTP** (remote URL).
**Stdio server** — runs a local command:
```json
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "package-name@latest"],
"env": { "KEY": "value" }
}
}
}
```
**HTTP server** — connects to a URL:
```json
{
"mcpServers": {
"server-name": {
"url": "http://localhost:8080/mcp",
"headers": { "Authorization": "Bearer token" }
}
}
}
```
## Step 3: Gather Configuration
Collect only what's needed. All fields except `command`/`url` are optional.
| Field | Type | Description |
|-------|------|-------------|
| `command` | string | Executable to run (stdio) |
| `args` | string[] | Command arguments (stdio) |
| `env` | object | Environment variables (stdio) |
| `cwd` | string | Working directory (stdio) |
| `url` | string | Server URL (HTTP) |
| `headers` | object | HTTP headers (HTTP) |
| `auth` | `"oauth"` or `"bearer"` | Auth method (HTTP) |
| `bearerToken` | string | Static bearer token |
| `bearerTokenEnv` | string | Env var name for bearer token |
| `lifecycle` | `"lazy"` / `"eager"` / `"keep-alive"` | Connection strategy (default: `lazy`) |
| `idleTimeout` | number | Minutes before idle disconnect |
| `debug` | boolean | Show server stderr |
Lifecycle modes:
- **lazy** (default) — connects on first tool call, disconnects after idle timeout
- **eager** — connects at session start, no auto-disconnect
- **keep-alive** — connects at start, auto-reconnects if dropped
## Step 4: Write the Config
1. Read the target config file if it exists
2. Merge the new server into the existing `mcpServers` object
3. Write the updated JSON
If the file doesn't exist, create it with the full structure:
```json
{
"mcpServers": {
"server-name": { ... }
}
}
```
Warn if a server with the same name already exists and confirm before overwriting.
## Step 5: Verify
1. Run `/reload` to pick up the new config
2. Use `mcp({ connect: "server-name" })` to test the connection
3. Use `mcp({ server: "server-name" })` to list available tools
4. Report success or troubleshoot connection errorsRelated Skills
write-todos
Write clear, actionable todos that workers can execute without losing architectural intent. Use when "create todos", "write todos", "break into tasks", "plan todos", "make todos", or creating work items from a plan. Ensures each todo has unambiguous expected outcomes, concrete examples, and explicit constraints so workers don't drift from the design.
skill-creator
Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, planning, writing, registration, and verification.
session-reader
Efficiently read and analyze pi agent session JSONL files. Use when asked to "read a session", "review a session", "analyze a session", "what happened in this session", "load session", "parse session", "session history", "go through sessions", or given a .jsonl session file path.
self-improve
End-of-session retrospective that identifies improvements to agent config, tests, docs, and code. Use when asked to "self-improve", "reflect on session", "what can we improve", "session retrospective", "end of session review". Creates actionable todos from findings.
presentation-creator
Create data-driven presentation slides using React, Vite, and Recharts with Sentry branding. Use when asked to "create a presentation", "build slides", "make a deck", "create a data presentation", "build a Sentry presentation". Scaffolds a complete slide-based app with charts, animations, and single-file HTML output.
learn-codebase
Discover project conventions and surface security concerns. Use when starting work in a new or unfamiliar project, when asked to "learn the codebase", "check project rules", "what are the conventions", "onboard to this project", or "anything shady in this codebase". Scans agent config files (.claude/, .cursor/, CLAUDE.md, etc.) and runs a security/smell sweep for hardcoded secrets, insecure patterns, suspicious dependencies, and dangerous configurations.
iterate-pr
Iterate on a PR until CI passes. Use when you need to fix CI failures, address review feedback, or continuously push fixes until all checks are green. Automates the feedback-fix-push-wait cycle.
github
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
frontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
commit
Read this skill before making git commits
code-simplifier
Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Use when asked to "simplify code", "clean up code", "refactor for clarity", "improve readability", or review recently modified code for elegance. Focuses on project-specific best practices.
cmux
Manage terminal sessions and browser surfaces via cmux — spawn workspaces for dev servers, test runners, background tasks, and embedded browsers. Read output, send commands, interact with web pages, and orchestrate multi-terminal workflows.