/connect-mcps connect to amplitude
/connect-mcps connect to linear
/connect-mcps connect to notion

/connect-mcps batch

claude mcp add --transport http [tool] [url]

To connect Amplitude, I need:
1. Amplitude API Key (Settings → API Keys)
2. Project ID (Settings → Projects)

[Link to Amplitude documentation]

Enter your Amplitude API Key: [you paste here]
Enter your Project ID: [you paste here]

### Using [MCP Name] (If Connected)

[MCP Name] provides [capability description].

**Available Tools:**
- `tool_name` - [purpose]
- `tool_name_2` - [purpose]

**Integration Example:**
```pseudocode
# Query Amplitude for feature metrics
amplitude.query_insights({
  "event": "feature_used",
  "feature_name": "checkout",
  "date_range": "last_14_days"
})

4. Write the updated SKILL.md back to disk
5. Log the change for the integration summary

### Step 8: Update CLAUDE.md Registry

I update two critical sections in CLAUDE.md:

**A) MCP Registry Table** - Lists all connected MCPs

| MCP | Purpose | Category | Used In | Key Tools |
|-----|---------|----------|---------|-----------|
| Amplitude | Product analytics | Analytics | feature-metrics, impact-sizing | query_insights, get_funnels |

**B) Intelligent Query Routing Logic** - Maps query patterns to MCPs

This enables me to automatically understand queries like:
- "Give me metrics on the login feature" → Route to Amplitude
- "Show my open tasks" → Route to Linear
- "What did users say about feature X" → Route to Dovetail

### Step 9: Generate Integration Summary

After successful integration, I:
- Save a detailed log to `outputs/mcp-integration-logs/[timestamp]-[tool-name].md`
- Display a summary showing:
  - Tools discovered
  - Skills updated
  - How to use the MCP with natural language queries
- Provide next steps

## MCP Intelligence Gathering

### What I Look For in Documentation

When researching an MCP, I extract:

**1. Setup Requirements**
- NPM package name or server URL
- Authentication method (API key, OAuth, token)
- Required configuration (workspace ID, project ID, etc.)
- Environment variables needed

**2. Tool Catalog**
- Available tools/functions
- Tool purposes and descriptions
- Parameter requirements (required vs optional)
- Return value structures

**3. Common Use Cases**
- Typical queries and operations
- Example workflows
- Best practices
- Rate limits or constraints

**4. Category Classification**
- Primary category (analytics, PM, research, etc.)
- Secondary categories if multi-purpose
- Keywords for routing logic

### Web Search Strategy

I use multiple search queries to find comprehensive information:

1. **"[tool] MCP server documentation 2026"** - Official MCP docs
2. **"[tool] MCP integration guide"** - Setup tutorials
3. **"[tool] Claude MCP setup"** - Claude-specific instructions
4. **"[tool] API authentication requirements"** - Auth details

I parse the results looking for:
- API key locations in the tool's settings
- Step-by-step setup instructions
- Code examples showing MCP usage
- Tool lists and function signatures

## Category Detection & Mapping Rules

### How I Determine MCP Category

**Analytics/Metrics Keywords:**
analytics, metrics, data, dashboard, reporting, charts, insights, KPI, measurement, funnel, cohort, retention, events

**Project Management Keywords:**
tickets, issues, tasks, projects, sprints, backlog, epics, stories, roadmap, planning

**Research/Interviews Keywords:**
research, interviews, transcripts, insights, quotes, themes, tagging, synthesis, user feedback

**Transcription Keywords:**
transcription, audio, recording, speech-to-text, meeting recording, voice notes

**Communication Keywords:**
slack, email, messaging, notifications, chat, channels, DMs

**Documentation Keywords:**
docs, wiki, knowledge base, pages, workspace, notes

**Design/Prototyping Keywords:**
design, prototype, mockup, wireframe, UI, UX, Figma, components

**Web Search Keywords:**
search, browse, web, internet, competitor, market research

### Mapping Logic Examples

**Amplitude MCP detected** →
- Category: Analytics (keywords: analytics, metrics, events, funnel, cohort)
- Maps to: feature-metrics, impact-sizing, retention-analysis, activation-analysis, feature-results, metrics-framework, experiment-metrics

**Linear MCP detected** →
- Category: Project Management (keywords: issues, projects, tickets)
- Maps to: create-tickets, meeting-notes, status-update, prioritize

**Dovetail MCP detected** →
- Category: Research + Transcription (keywords: research, interviews, transcripts, insights)
- Maps to: user-interview, user-research-synthesis, interview-guide, meeting-notes

## Update Patterns & Templates

### Skill File Update Template

```markdown
### Using [MCP Name] (If Connected)

[1-2 sentence description of what this MCP provides]

**Available Tools:**
- `tool_name` - [Brief description]
- `tool_name_2` - [Brief description]

**Integration Example:**
```pseudocode
# [Example showing typical usage in this skill's context]
[tool_name].method({
  param1: value1,
  param2: value2
})

### Insertion Point Logic

1. **If "Prerequisites" section exists** → Insert immediately after
2. **If "How It Works" section exists** → Insert immediately after
3. **Otherwise** → Insert after title and frontmatter, before main content

This ensures MCP integration info appears early but doesn't interrupt the skill's primary instructions.

### CLAUDE.md Registry Format

**Registry Table:**
```markdown
| MCP | Purpose | Category | Used In | Key Tools |
|-----|---------|----------|---------|-----------|
| Amplitude | Product analytics | Analytics | feature-metrics, impact-sizing, retention-analysis | query_insights, get_funnels, cohort_analysis |
| Linear | Project management | PM Tools | create-tickets, meeting-notes, status-update | create_issue, update_issue, search_issues |
| Dovetail | User research | Research | user-interview, user-research-synthesis | search_insights, get_themes, export_quotes |

**Analytics Queries** → Analytics MCPs (Amplitude, Mixpanel, Posthog)
- Pattern: "give me metrics on X", "show funnel for Y", "retention for Z"
- Multi-MCP: Ask user which tool to use
- Fallback: Check context-library/metrics/

**Task Queries** → PM MCPs (Linear, Jira)
- Pattern: "show my tasks", "create ticket for X", "status of epic Y"
- Multi-MCP: Ask user which tool to use
- Fallback: Check context-library/meetings/ for action items

User: /connect-mcps connect to figma

Me:
Let me help you connect Figma to your PM OS workspace.

[Searches: "Figma official MCP server"]
[Finds: https://developers.figma.com/docs/figma-mcp-server/]

✅ **Great news! Figma has an official remote MCP server.**

**This is the easiest method:**

1. Run this command in your terminal:
   ```bash
   claude mcp add --transport http figma https://mcp.figma.com/mcp

---

### Example 1: Amplitude (Analytics)

### Example 2: Linear (Project Management)

### Example 3: Batch Connection

## Natural Language Query Routing (After Setup)

Once MCPs are connected, you can ask questions naturally and I'll route them automatically.

### Example: Analytics Query

### Example: Multi-MCP Disambiguation

### Example: Task Management Query

## Error Handling & Edge Cases

### Common Issues & Solutions

**1. MCP Documentation Not Found**

**2. Invalid Credentials**

**3. MCP Already Connected**

**4. Skill File Read-Only**

**5. Ambiguous Category**

## Pro Tips

1. **Connect MCPs during initial setup** - The first-time workspace setup will prompt you to connect your tools. Do it then for a seamless experience.

2. **Use natural language after setup** - Don't think about which MCP to call. Just ask your question naturally and I'll figure out the routing.

3. **Batch connect if you can** - If you're setting up multiple tools, use `/connect-mcps batch` to go through them all at once.

4. **Test with simple queries first** - After connecting, try a simple query like "show me X" to verify the connection works before complex queries.

5. **Keep credentials handy** - Have your API keys and workspace IDs ready before running `/connect-mcps connect to [tool]` to speed up setup.

6. **Check the integration log** - Each connection creates a log in `outputs/mcp-integration-logs/` with full details about what was updated.

7. **MCPs are optional** - If an MCP isn't connected, skills will gracefully fall back to manual workflows (e.g., "Upload CSV to context-library/metrics/").

8. **Re-run `/connect-mcps connect` to update** - If credentials change or expire, just run the connect command again to reconfigure.

9. **Check CLAUDE.md registry** - View `CLAUDE.md` → "MCP Integrations" section to see all connected MCPs and routing logic.

10. **Skills auto-update** - When you connect an MCP, relevant skills are automatically updated with integration instructions. No manual work needed.

## Common Mistakes to Avoid

❌ **Don't paste credentials in chat without the prompt** - Wait for me to explicitly ask for your API key. Don't volunteer it unprompted.

❌ **Don't skip the tool name** - Use `/connect-mcps connect to amplitude`, not just `/connect-mcps amplitude` or `/connect-mcps connect amplitude`.

❌ **Don't connect before installing** - Install the MCP server locally first (via NPM, Docker, etc.), then run `/connect-mcps connect to [tool]`.

❌ **Don't assume immediate availability** - After connecting, I'll tell you it's ready. Don't start querying until you see the success message.

❌ **Don't manually edit CLAUDE.md** - Let me update the registry automatically. Manual edits can break the routing logic.

❌ **Don't connect duplicate MCPs** - If you already have Amplitude connected, don't run `/connect-mcps connect to amplitude` again unless you're reconfiguring.

❌ **Don't ignore errors** - If connection fails, read the error message. It usually tells you exactly what's wrong (expired key, wrong format, etc.).

❌ **Don't use both individual and batch modes together** - Pick one. Use individual for one tool, batch for multiple. Don't mix them in the same command.

❌ **Don't forget to check prerequisites** - Some MCPs require specific permissions or scopes on the API key. Check the tool's documentation.

❌ **Don't skip the fallback** - Even with MCPs connected, keep some exported data in `context-library/` as backup for offline work.

## Troubleshooting

### "I couldn't find documentation for [tool] MCP"

**Solution:** The tool may not have an official MCP server yet. Check:
- The tool's official docs for MCP support
- GitHub for community MCP implementations
- The Anthropic MCP directory

If no MCP exists, you can still use the tool manually and store outputs in `context-library/`.

### "Connection test failed"

**Solution:**
1. Verify credentials are correct (no typos, no extra spaces)
2. Check API key hasn't expired
3. Confirm API key has required permissions/scopes
4. Test the API key in the tool's web interface first
5. Check for network/firewall issues blocking MCP server

### "Skills weren't updated"

**Solution:**
1. Check the integration log in `outputs/mcp-integration-logs/`
2. Look for error messages indicating which skills failed
3. Verify skill files aren't read-only or locked
4. Re-run `/connect-mcps connect to [tool]` to retry updates

### "Queries aren't routing to my MCP"

**Solution:**
1. Check `CLAUDE.md` → "MCP Integrations" → Verify MCP is listed
2. Verify routing logic includes your MCP category
3. Try being more explicit: "Use Amplitude to show me metrics on X"
4. Check if MCP connection is still active (test with simple query)

### "I want to disconnect an MCP"

**Solution:** Currently, to disconnect:
1. Remove the MCP from your system (uninstall server/remove credentials)
2. Edit `CLAUDE.md` to remove the MCP from the registry table
3. Optionally, remove MCP sections from skill files

(Future enhancement: `/mcp disconnect [tool]` command)

---

## Recommended PM Tools to Connect

Based on real PM workflows, here's which MCPs provide the highest value. Start with Priority Tier, then add others as needed.

### Priority Tier: Must-Have MCPs ⭐⭐⭐⭐⭐

Connect these first. They provide immediate ROI for product managers.

#### 1. Analytics Tools (Amplitude, Mixpanel, Posthog, Pendo)

**Why connect:** Self-serve analytics without waiting on data team. Ask questions and get answers in seconds.

**What you can do:**
- "What's the funnel conversion rate for onboarding?"
- "Show me retention by signup cohort for last quarter"
- "Which features correlate with power user behavior?"
- "Pull session recordings for users who churned last week"

**Setup:** Run `/connect-mcps connect to amplitude` (or your analytics tool)

**Tools discovered:** query_insights, get_funnels, cohort_analysis, event_tracking, session_replays

**Best for:** Feature performance analysis, A/B test results, user behavior research

---

#### 2. Project Management (Linear, Jira, Asana)

**Why connect:** Batch create tickets from meeting notes. Generate sprint reports. Track engineering progress without tab-switching.

**What you can do:**
- "Take these action items and create Linear tickets"
- "Show completed tickets from current sprint"
- "List all blocked tickets and their reasons"
- "Update ticket LIN-123 to mark it as done"

**Setup:** Run `/connect-mcps connect to linear` (or your PM tool)

**Tools discovered:** create_issue, update_issue, search_issues, get_project_status

**Best for:** Meeting follow-ups, sprint planning, progress tracking

---

#### 3. Communication (Slack, Microsoft Teams)

**Why connect:** Share analysis summaries. Search past decisions. Draft announcements without leaving Claude.

**What you can do:**
- "Summarize this week's work and post to #engineering-updates"
- "Search Slack for conversations about pricing from last month"
- "Draft an announcement for the feature launch"
- "Find the decision about API versioning we discussed"

**Setup:** Run `/connect-mcps connect to slack`

**Tools discovered:** read_channels, post_message, search_history, manage_threads

**Best for:** Team updates, decision archaeology, communication drafts

---

#### 4. Documentation (Notion, Confluence, Google Drive)

**Why connect:** Access PRDs and specs. Create documents from templates. Search institutional knowledge.

**What you can do:**
- "Search my Drive for customer interview notes from Q3"
- "Create a PRD for dark mode and save to Product Docs"
- "Read the Q4 roadmap and summarize key themes"
- "Update the onboarding guide with new screenshots"

**Setup:** Run `/connect-mcps connect to notion` (or your docs tool)

**Tools discovered:** read_pages, create_document, search_workspace, update_pages

**Best for:** Document creation, knowledge search, team alignment

---

### High Value Tier: Very Useful ⭐⭐⭐⭐

Not required day one, but add these once core setup is done.

#### 5. Design Tools (Figma, Sketch)

**Why connect:** Reference designs in conversations. Extract specs from mockups. Track design feedback.

**What you can do:**
- "Summarize feedback on the new dashboard design"
- "Export the mobile mockups as PNGs"
- "What's the latest version of the checkout flow?"

**Setup:** Run `/connect-mcps connect to figma`

**Best for:** Design review, spec extraction, version tracking

---

#### 6. Calendar (Google Calendar, Outlook)

**Why connect:** Analyze time allocation. Schedule research sessions. Find focus time patterns.

**What you can do:**
- "Analyze my calendar this week - where did I spend time?"
- "Find a 1-hour slot for user interviews next week"
- "Create recurring 1:1s with my reports"

**Setup:** Run `/connect-mcps connect to google-calendar`

**Best for:** Time management, meeting scheduling, calendar analysis

---

#### 7. Code Repository (GitHub, GitLab)

**Why connect:** Track engineering progress. Review technical discussions. Understand implementation details.

**What you can do:**
- "What PRs were merged in the mobile repo this week?"
- "Summarize the discussion in issue #234 about performance"
- "Create a PR to update the API documentation"

**Setup:** Run `/connect-mcps connect to github`

**Best for:** Engineering collaboration, progress tracking, technical context

---

### Specialized Tier: Niche But Powerful ⭐⭐⭐

For specific workflows or advanced users.

#### 8. Customer Support (Zendesk, Intercom)

**What you can do:**
- Analyze support tickets for patterns
- Find common user issues
- Track resolution times
- Identify bug clusters

**Setup:** Run `/connect-mcps connect to zendesk`

**Best for:** Support insights, bug prioritization, customer pain points

---

#### 9. Revenue Tools (Stripe, ChartMogul)

**What you can do:**
- Analyze subscription trends
- Track MRR changes
- Identify churn patterns
- Monitor payment issues

**Setup:** Run `/connect-mcps connect to stripe`

**Best for:** Revenue analysis, subscription health, payment insights

---

#### 10. Social Listening (Twitter/X, Reddit)

**What you can do:**
- Monitor competitor mentions
- Analyze user sentiment
- Find feature requests in the wild
- Track industry trends

**Setup:** Run `/connect-mcps connect to reddit`

**Best for:** Competitive intelligence, user research, trend spotting

---

### Choosing Your Stack

**For Solo PM:**
- Analytics + Project Management + Slack + Docs
- Setup time: 30-45 minutes
- Covers 80% of daily workflows

**For PM Team:**
- Solo stack + Design + Calendar + GitHub
- Setup time: 1-2 hours
- Full workflow coverage

**For PM Leader:**
- Team stack + Support + Revenue tools
- Setup time: 2-3 hours
- Complete analytics and insights

**Pro tip:** Start small. Add one MCP at a time as you discover needs. More MCPs ≠ better.

---

### Setup Difficulty Guide

**Easy (5-10 min):**
- Linear, Jira: API token only
- Slack: Workspace token
- GitHub: Personal access token

**Medium (10-20 min):**
- Amplitude, Mixpanel: API key + Project ID
- Notion: Integration setup required
- Figma: OAuth flow

**Advanced (20-30 min):**
- Google Drive: OAuth + permission scopes
- Database tools: Credentials + read-only setup
- Calendar: OAuth + calendar selection

---

### Analytics Tool Details

Since analytics is the #1 requested integration, here's the specifics:

**PostHog MCP**
- Official server: `@anthropic/posthog-mcp`
- What you need: API key, host URL (US/EU/self-hosted)
- Tools: Insights, funnels, experiments, feature flags, session replays
- Query language: SQL-like HogQL
- Best for: Self-hosted analytics, session replay analysis

**Amplitude MCP**
- Official server: `@anthropic/amplitude-mcp`
- What you need: API key, Project ID
- Tools: Insights, funnels, cohorts, user profiles
- Query language: AQL (Amplitude Query Language)
- Best for: Behavioral analytics, cohort analysis

**Mixpanel MCP**
- Community server: `mcp-server-mixpanel`
- What you need: Project token, API secret
- Tools: Events, funnels, flows, retention
- Query language: JQL (Mixpanel JSON Query Language)
- Best for: Event-based analytics, user flows

**Pendo MCP**
- Beta status: Check Pendo docs for latest
- What you need: API key, subscription key
- Tools: Product usage, guides, NPS scores
- Best for: Product adoption analytics

**Common Analytics Queries:**

---

### Maintenance Tips

**Weekly:**
- Test critical integrations with simple queries
- Check MCP logs for errors (if issues arise)
- Update API tokens if expiring soon

**Monthly:**
- Update MCP servers to latest versions (`npm update`)
- Review permissions and access scopes
- Remove MCPs you haven't used

**Quarterly:**
- Evaluate new MCP releases
- Assess ROI of each integration
- Optimize configuration for performance

**Signs you need to update:**
- Connection errors or timeouts
- Missing tools that should be available
- Slow response times
- Authentication failures

---

### Security Best Practices

**API Keys:**
- Use read-only credentials whenever possible
- Store keys in environment variables, never in code
- Rotate keys quarterly or when team members leave
- Never share keys in Slack or email

**Permissions:**
- Grant minimum required scopes
- Audit access regularly
- Use separate keys for prod vs staging
- Revoke unused tokens immediately

**Data Privacy:**
- Don't query PII unless necessary
- Be mindful of GDPR/data regulations
- Use aggregated data when possible
- Don't export sensitive user data to logs

---

### Getting Help

**When MCP connection fails:**
1. Check API key is correct (no typos, extra spaces)
2. Verify token hasn't expired
3. Confirm required permissions are granted
4. Test the API key in the tool's web interface first
5. Check network/firewall isn't blocking MCP server

**Resources:**
- **MCP Documentation:** https://modelcontextprotocol.io
- **Anthropic Forums:** https://discuss.anthropic.com
- **GitHub Issues:** https://github.com/modelcontextprotocol/servers
- **Community Discord:** MCP Community server

**For PM-specific help:**
- Check `outputs/mcp-integration-logs/` for detailed error messages
- Ask in chat: "Why did my Amplitude connection fail?"
- Reference CLAUDE.md → MCP Integrations section for routing logic

---

## What Happens Behind the Scenes

When you run `/connect-mcps connect to amplitude`:

1. **I search the web** for Amplitude MCP documentation
2. **I parse** the results to extract setup requirements
3. **I prompt you** for each required credential
4. **I test** the connection to verify it works
5. **I discover** available tools by querying the MCP
6. **I categorize** the MCP (Analytics) based on keywords
7. **I map** to relevant skills (feature-metrics, impact-sizing, etc.)
8. **I read** each skill file to find insertion points
9. **I add** MCP integration sections to each skill
10. **I update** CLAUDE.md with registry entry and routing logic
11. **I create** an integration log with full details
12. **I confirm** success and show you how to use it

All of this happens automatically in seconds. You just provide credentials and I handle the rest.

---

**Ready to connect your first MCP? Try:**

And I'll guide you through the rest!

---

## Output Quality Self-Check

Before confirming an MCP connection is complete, verify:

- [ ] **Connection tested successfully** -- A simple query returned valid results (not just "connected" status)
- [ ] **Tools discovered and documented** -- Available MCP tools are listed with descriptions
- [ ] **Category correctly assigned** -- MCP is mapped to the right category (Analytics, PM, Research, etc.)
- [ ] **Relevant skills updated** -- All skills that benefit from this MCP have integration sections added
- [ ] **CLAUDE.md registry updated** -- MCP appears in the registry table with purpose, category, used-in skills, and key tools
- [ ] **Routing logic updated** -- Natural language query patterns are mapped to this MCP in CLAUDE.md
- [ ] **Integration log saved** -- Detailed log written to `outputs/mcp-integration-logs/[timestamp]-[tool].md`
- [ ] **Fallback documented** -- Skills note what to do when this MCP is unavailable
- [ ] **No duplicate entries** -- MCP is not listed twice in registry or skill files
- [ ] **PM knows how to use it** -- Example natural language queries provided so the PM can start using the MCP immediately

If any check fails, fix it before declaring success. A half-connected MCP causes confusion when skills try to use it.