tomevault-io CCPM MCP Management
MCP server discovery, configuration, and troubleshooting for CCPM workflows.
When to Use
This skill auto-activates when:
- User asks: "MCP server", "tools available", "Linear not working", "what tools do I have"
- Running
/ccpm:workcommand - Plugin installation issues
- MCP tools failing to load
- Troubleshooting CCPM setup
CCPM Required MCP Servers
Critical Servers (Must Have)
1. Linear MCP Server
- Purpose: Task tracking, issue management, Linear Documents
- Used by: All
/ccpm:*commands - Tools:
linear_create_issue,linear_update_issue,linear_create_document, etc. - Setup: Required in
.claude/mcp.json
2. GitHub MCP Server
- Purpose: PR creation, repository operations
- Used by:
/ccpm:done - Tools:
github_create_pr,github_list_prs,github_get_repo - Setup: Required for completion workflow
3. Context7 MCP Server
- Purpose: Latest library documentation
- Used by:
/ccpm:plan,docs-seekerskill - Tools:
context7_fetch_docs,context7_search - Setup: Required for spec writing
Optional Servers (PM Integrations)
4. Jira MCP Server (if using Jira)
- Purpose: Jira ticket integration
- Used by:
/ccpm:plan,/ccpm:done - Tools:
jira_get_issue,jira_update_status - Setup: Optional, only if syncing with Jira
5. Confluence MCP Server (if using Confluence)
- Purpose: Confluence page integration
- Used by:
/ccpm:plan - Tools:
confluence_get_page,confluence_search - Setup: Optional, for gathering context
6. Slack MCP Server (if using Slack)
- Purpose: Team notifications
- Used by:
/ccpm:done - Tools:
slack_post_message,slack_list_channels - Setup: Optional, for notifications
MCP Server Discovery
Check Available Servers
User: "What MCP servers are available?"
Claude: [ccpm-mcp-management activates]
Discovering MCP servers...
✅ REQUIRED SERVERS (All present):
1. Linear MCP
Status: Connected
Tools: 15 available
- linear_create_issue
- linear_update_issue
- linear_get_issue
- linear_create_document
- linear_list_teams
[+ 10 more]
2. GitHub MCP
Status: Connected
Tools: 8 available
- github_create_pr
- github_list_prs
- github_get_repo
[+ 5 more]
3. Context7 MCP
Status: Connected
Tools: 3 available
- context7_fetch_docs
- context7_search
- context7_list_sources
⚠️ OPTIONAL SERVERS (Not configured):
4. Jira MCP - Not configured
Impact: Cannot sync with Jira
Setup: Add to .claude/mcp.json if needed
5. Confluence MCP - Not configured
Impact: Cannot fetch Confluence pages
Setup: Add to .claude/mcp.json if needed
6. Slack MCP - Not configured
Impact: Cannot send notifications
Setup: Add to .claude/mcp.json if needed
All required servers operational ✅
Troubleshooting Server Issues
User: "Linear tools not working"
Claude: [ccpm-mcp-management activates]
Troubleshooting Linear MCP server...
Step 1: CHECK CONNECTION
Testing Linear MCP connection...
❌ Connection failed: ECONNREFUSED
Step 2: DIAGNOSE
Possible causes:
1. Linear MCP server not running
2. Incorrect configuration in .claude/mcp.json
3. Missing Linear API key
4. Network connectivity issues
Step 3: VERIFY CONFIGURATION
Checking .claude/mcp.json...
Found configuration:
```json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-linear"],
"env": {
"LINEAR_API_KEY": "${LINEAR_API_KEY}"
}
}
}
}
Step 4: CHECK ENVIRONMENT Checking LINEAR_API_KEY... ❌ Environment variable not set
ROOT CAUSE: Missing LINEAR_API_KEY
FIX:
Get Linear API key from https://linear.app/settings/api
Add to environment: export LINEAR_API_KEY="lin_api_xxxxxxxxxxxxx"
Restart Claude Code
Would you like help setting up the API key?
## Configuration Guide
### Minimal CCPM Configuration
**`.claude/mcp.json` (required servers only)**:
```json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-linear"],
"env": {
"LINEAR_API_KEY": "${LINEAR_API_KEY}"
}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
},
"context7": {
"command": "npx",
"args": ["-y", "@context7/mcp-server"],
"env": {
"CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
}
}
}
}
Full CCPM Configuration
With optional PM integrations:
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-linear"],
"env": {
"LINEAR_API_KEY": "${LINEAR_API_KEY}"
}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
},
"context7": {
"command": "npx",
"args": ["-y", "@context7/mcp-server"],
"env": {
"CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
}
},
"jira": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-jira"],
"env": {
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_EMAIL": "${JIRA_EMAIL}",
"JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
}
},
"confluence": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-confluence"],
"env": {
"CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
"CONFLUENCE_EMAIL": "${CONFLUENCE_EMAIL}",
"CONFLUENCE_API_TOKEN": "${CONFLUENCE_API_TOKEN}"
}
},
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
"SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
}
}
}
}
Common Issues & Solutions
Issue 1: MCP Server Not Found
Symptom: "MCP server 'linear' not found"
Solution:
# Check if MCP server package exists
npx @modelcontextprotocol/server-linear --version
# If not found, package name might be wrong
# Check official MCP registry
# Update .claude/mcp.json with correct package name
Issue 2: Authentication Failures
Symptom: "Unauthorized" or "Invalid API key"
Solution:
# Check environment variables are set
echo $LINEAR_API_KEY
echo $GITHUB_TOKEN
# If empty, add to shell profile
echo 'export LINEAR_API_KEY="your-key"' >> ~/.zshrc
source ~/.zshrc
# Or use .env file
cat > .env << EOF
LINEAR_API_KEY=lin_api_xxxxx
GITHUB_TOKEN=ghp_xxxxx
CONTEXT7_API_KEY=ctx7_xxxxx
EOF
# Restart Claude Code to pick up changes
Issue 3: Command Not Found
Symptom: "npx: command not found"
Solution:
# Install Node.js and npm
# macOS
brew install node
# Linux
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Windows
# Download from https://nodejs.org
# Verify installation
node --version
npm --version
npx --version
Issue 4: Permission Denied
Symptom: "EACCES: permission denied"
Solution:
# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
# Or use sudo (not recommended)
sudo npx @modelcontextprotocol/server-linear
Integration with CCPM Commands
/ccpm:work Integration
User: "/ccpm:work"
Claude: [ccpm-mcp-management activates]
CCPM Help - Available Tools
MCP Server Status:
✅ Linear (15 tools) - Task tracking
✅ GitHub (8 tools) - PR creation
✅ Context7 (3 tools) - Documentation
❌ Jira (not configured) - Optional
❌ Slack (not configured) - Optional
Available CCPM Commands: 37 total
- Spec Management: 6 commands
- Planning: 4 commands
- Implementation: 3 commands
- Verification: 3 commands
- Completion: 1 command
- Utilities: 20 commands
For setup help: Ask "How do I configure Jira MCP?"
For troubleshooting: Mention "Linear not working"
Plugin Installation Verification
After installing CCPM plugin:
Claude: [ccpm-mcp-management auto-activates]
Verifying CCPM plugin requirements...
Checking required MCP servers:
✅ Linear MCP - Connected
✅ GitHub MCP - Connected
❌ Context7 MCP - Not found
CCPM plugin requires Context7 for documentation features.
Setup instructions:
1. Add to .claude/mcp.json:
```json
"context7": {
"command": "npx",
"args": ["-y", "@context7/mcp-server"],
"env": {
"CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
}
}
Get API key: https://context7.ai/signup
Set environment variable: export CONTEXT7_API_KEY="ctx7_xxxxx"
Restart Claude Code
Would you like help with any of these steps?
## Server Health Monitoring
### Health Check Command
User: "Check MCP server health"
Claude: [ccpm-mcp-management activates]
Running health checks on all MCP servers...
LINEAR MCP: Status: ✅ Healthy Response time: 45ms Tools available: 15/15 Last successful call: 2 minutes ago Rate limit: 4,800 / 5,000 remaining
GITHUB MCP: Status: ✅ Healthy Response time: 120ms Tools available: 8/8 Last successful call: 15 minutes ago Rate limit: 4,950 / 5,000 remaining
CONTEXT7 MCP: Status: ⚠️ Degraded Response time: 3,200ms (slow) Tools available: 3/3 Last successful call: 1 hour ago Note: Docs fetching slower than usual, still functional
JIRA MCP: Status: ❌ Not configured Impact: Cannot sync Jira tickets Action: Configure if Jira integration needed
Overall health: Good (2/3 required servers healthy)
## Best Practices
### Do's
- ✅ Set environment variables in shell profile (persistent)
- ✅ Use `.env` file for project-specific keys
- ✅ Test MCP connections after setup
- ✅ Monitor rate limits
- ✅ Keep MCP server packages updated
- ✅ Document custom MCP configurations
### Don'ts
- ❌ Hardcode API keys in `.claude/mcp.json`
- ❌ Commit API keys to git
- ❌ Ignore authentication errors
- ❌ Run with sudo unnecessarily
- ❌ Use outdated MCP server versions
- ❌ Skip health checks
## Summary
This skill provides:
- ✅ MCP server discovery
- ✅ Configuration validation
- ✅ Troubleshooting guidance
- ✅ CCPM-specific server requirements
- ✅ Health monitoring
- ✅ Setup assistance
**Focus**: CCPM required servers (Linear, GitHub, Context7) + optional PM integrations (Jira, Confluence, Slack)
**Philosophy**: Reliable infrastructure for reliable PM workflows. Monitor, maintain, troubleshoot proactively.
---
**Source**: Adapted from [claudekit-skills/mcp-management](https://github.com/mrgoonie/claudekit-skills)
**License**: MIT
**CCPM Integration**: `/ccpm:work`, plugin installation, troubleshooting
**Required Servers**: Linear, GitHub, Context7
**Optional Servers**: Jira, Confluence, Slack, BitBucket
---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/duongdev) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->