MCP Provider Setup

MCP Provider Setup

PopKit works with any MCP-compatible AI coding tool. The popkit-mcp server exposes PopKit’s 50 skills, 24 agents, and 25 commands as standard MCP tools that any client can call. See Architecture for how this fits into PopKit’s provider model.

This guide covers setup for each provider.

Prerequisites

Install the PopKit MCP server:

pip install popkit-mcp

This installs the primary popkit-mcp command. It also installs popkit-mcp-server as a compatibility alias, but the examples below use popkit-mcp.

Or use uvx for zero-install:

uvx popkit-mcp

---

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "popkit": {
      "command": "popkit-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Note: Cursor has a limit of ~40 tools across all MCP servers. PopKit exposes tools selectively to stay within this limit.

---

Codex CLI (OpenAI)

Add to ~/.codex/config.toml (global) or .codex/config.toml (per-project):

[mcp_servers.popkit]
command = "popkit-mcp"
args = ["--transport", "stdio"]

Codex also reads AGENTS.md for agent rules — PopKit can generate these via popkit-mcp --packages /path/to/packages.

---

GitHub Copilot CLI

Add to ~/.copilot/mcp-config.json (global) or .vscode/mcp.json (per-project):

{
  "mcpServers": {
    "popkit": {
      "command": "popkit-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

---

VS Code / GitHub Copilot

One-click install:

Click the badge to auto-configure PopKit in VS Code. Requires pip install popkit-mcp first.

Note: the one-click install assumes popkit-mcp is on your PATH. On Windows this often is not true after pip install; if the badge install creates a non-working config, use Manual setup plus the Windows PATH fallback below.

Manual setup — add to .vscode/mcp.json (per-project):

{
  "servers": {
    "popkit": {
      "command": "popkit-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Important: VS Code uses servers as the root key, not mcpServers — even though other Microsoft tools use mcpServers.

Windows PATH fallback

On Windows, pip install popkit-mcp may install popkit-mcp.exe in your user Scripts directory instead of on PATH:

%APPDATA%\Python\Python3xx\Scripts\

Use %APPDATA% instead of copying another user’s absolute path. Replace Python3xx with your installed Python folder. Run python --version to check the version.

If you do not want to edit PATH, point VS Code at the executable directly:

{
  "servers": {
    "popkit": {
      "command": "C:\\Users\\YOUR-USERNAME\\AppData\\Roaming\\Python\\Python313\\Scripts\\popkit-mcp.exe",
      "args": ["--transport", "stdio"]
    }
  }
}

Replace YOUR-USERNAME with your Windows username and Python313 with your installed Python version. Run python --version to check the version.

Check VS Code’s MCP server panel: popkit should show Connected. If it is stuck on Starting, check the MCP output log for the actual error.

In Copilot Chat (Agent mode):

Use PopKit health_check and summarize the result.

That confirms VS Code can start the MCP server and see PopKit tools.

---

Claude Code

Claude Code users should install PopKit as a plugin instead of using MCP:

/plugin marketplace add jrc1883/popkit-ai
/plugin install popkit-core@popkit-ai

See Installation for full plugin setup.

---

HTTP Transport (Advanced)

For debugging or remote setups, PopKit supports HTTP transports:

# Streamable HTTP (recommended for HTTP)
popkit-mcp --transport streamable-http --host 127.0.0.1 --port 8080

# SSE (Server-Sent Events)
popkit-mcp --transport sse --host 127.0.0.1 --port 8080

Then configure your MCP client to connect via HTTP instead of stdio.

---

Config Reference

Tool	Format	Global Path	Per-Project Path	Root Key
Cursor	JSON	~/.cursor/mcp.json	.cursor/mcp.json	mcpServers
Codex CLI	TOML	~/.codex/config.toml	.codex/config.toml	[mcp_servers.*]
Copilot CLI	JSON	~/.copilot/mcp-config.json	.vscode/mcp.json	mcpServers
VS Code	JSON	User settings	.vscode/mcp.json	servers
Claude Code	JSON	~/.claude.json	.mcp.json	mcpServers

---

Troubleshooting

MCP server not detected

Verify the server starts correctly:

popkit-mcp --help

If the command isn’t found, ensure pip install popkit-mcp installed to a directory on your PATH. On Windows, see the VS Code Windows PATH fallback.

Tools not appearing

Some clients limit the number of MCP tools. PopKit exposes tools selectively — use --log-level DEBUG to see which tools are registered:

popkit-mcp --transport stdio --log-level DEBUG