integrate-mcp

name	integrate-mcp
description	Install and wire up an existing MCP server from Smithery.ai or a GitHub repo. Use when the user names a tool that already has a server — 'add the Notion MCP', 'install this Smithery server'. Not for building a new integration from nothing; use `create-mcp`. Not for adding one already-known server safely; use `dex-add-mcp`.

Purpose

Help users discover and integrate pre-built MCP servers from the ecosystem, primarily from Smithery.ai marketplace.

When to Run

• User types /integrate-mcp
• Mentioned during /getting-started tour
• User asks about connecting tools that have existing MCPs
• User wants to browse available integrations

Entry Point

Say:

**Want to connect more tools to Dex?**

Some tools have a built-in, guided setup — no marketplace hunting needed:
• **Task apps:** Todoist (`/todoist-setup`), Things 3 (`/things-setup`), Trello (`/trello-setup`) — two-way task sync
• **Email & calendar:** Google Workspace (`/google-workspace-setup`), Microsoft Teams (`/ms-teams-setup`)
• **Meetings:** Granola (`/granola-setup`), Zoom (`/zoom-setup`)
• **Work tracking:** Jira + Confluence (`/atlassian-setup`)

For anything else, there's a marketplace of 100+ pre-built MCP servers at:
**[Smithery.ai](https://smithery.ai/servers)**

These are production-ready integrations for:
• **Dev tools:** GitHub, GitLab, Linear, Jira
• **Productivity:** Notion, Airtable, Google Sheets
• **Communication:** Slack, Discord, Email
• **Databases:** Postgres, MySQL, SQLite
• **Monitoring:** Sentry, Datadog
• **And many more...**

**How this works:**
1. Browse Smithery.ai for MCPs that match your tools
2. Copy the full URL of any MCP you want
3. Paste it here - I'll:
   - Fetch the code/documentation
   - Explain what it does
   - Help you configure it
   - Integrate into Dex
   - Update documentation

**Or** if you can't find what you need, run `/create-mcp` to build custom.

Ready to explore? [Browse Smithery.ai](https://smithery.ai/servers)

---

When User Pastes an MCP URL

Step 1: Fetch the MCP Source

Detect URL type:

• GitHub repo: https://github.com/user/repo
• npm package: https://npmjs.com/package/name
• Smithery.ai: https://smithery.ai/server/name
• Direct source: Any other URL

Fetch based on type:

if "github.com" in url:
    # Fetch README.md from repo
    readme_url = f"{url}/blob/main/README.md"
    content = web_fetch(readme_url)
elif "smithery.ai" in url:
    # Fetch from Smithery page
    content = web_fetch(url)
elif "npmjs.com" in url:
    # Fetch package info
    content = web_fetch(url)
else:
    # Try direct fetch
    content = web_fetch(url)

Step 2: Parse and Explain

Analyze the fetched content for:

• MCP server name
• What it does (capabilities)
• Required environment variables
• Installation method (npm, pip, docker, etc.)
• Authentication requirements

Say:

**Got it!** This is the **[Server Name]** MCP.

**What it does:**
• [Capability 1] - [Description]
• [Capability 2] - [Description]
• [Capability 3] - [Description]

**What you'll need to set up:**
• [ENV_VAR_1]: [Explanation of what this is]
• [ENV_VAR_2]: [Explanation]

**Installation method:** [npm/pip/docker/manual]

**Authentication:** [API key / OAuth / Local / None]

Ready to integrate this?

Step 3: Guide Through Setup

For npm packages:

"This is an npm package. Here's how to install:

1. Navigate to your Dex directory
2. Install the package:

npm install -g [package-name]

3. I'll add it to your `.mcp.json` config

Want me to proceed?"

Then add to .mcp.json:

{
  "[server-name]": {
    "command": "npx",
    "args": ["-y", "[package-name]"],
    "env": {
      "VAR1": "value1"
    }
  }
}

For Python packages:

"This is a Python MCP. Here's how to install:

1. Install via pip:

pip install [package-name]

2. I'll add it to your `.mcp.json` config

Want me to proceed?"

For GitHub repos (manual):

"This is from a GitHub repo. Here's the setup:

1. Clone the repository:

git clone [repo-url] ~/dex-mcps/[server-name]

2. Install dependencies (if any)

3. I'll add it to your `.mcp.json` config

Want me to proceed?"

Step 4: Configure Environment Variables

For each required env var:

"This MCP needs the following environment variables:

**[ENV_VAR_1]:** [Description]
Where to get it: [Instructions]

**[ENV_VAR_2]:** [Description]
Where to get it: [Instructions]

You can either:
1. Set them now (I'll add to `.env` file)
2. Set them manually later in your shell config

What's your [ENV_VAR_1]?"

Collect values and add to .env file:

# [Server Name] MCP Configuration
ENVVAR_1=value1
ENV_VAR_2=value2

After writing, make the file owner-only (chmod 600 .env) — create it with that mode if it's new, and tighten it if an existing .env was left readable by other users.

Step 5: Update MCP Config

Add to System/.mcp.json:

{
  "[server-name]": {
    "command": "[command]",
    "args": ["[args]"],
    "env": {
      "ENV_VAR_1": "${ENV_VAR_1}",
      "VAULT_PATH": "{{VAULT_PATH}}"
    }
  }
}

Step 6: Test Connection

Try calling a basic tool from the MCP:

"Testing connection..."

[Call a simple tool from the MCP, like list_resources or get_status]

[If success:]
"✅ Connection works! The [Server Name] MCP is live.

Test it: '[Example natural language query]'

See? Real data from [Tool]."

[If failure:]
"⚠️ Connection failed. Common issues:
• Environment variables not set correctly
• Authentication hasn't been completed
• MCP server not installed properly

Want help debugging this?"

Step 7: Update Documentation

Add to CLAUDE.md:

### [Server Name] Integration

**MCP Server:** [server-name]
**Purpose:** [what it does]

**Available via this MCP:**
- [Capability 1]
- [Capability 2]

**Configuration:**
- `ENV_VAR_1`: [description]

**Usage:**
- "[Natural language example 1]"
- "[Natural language example 2]"

Add to System/usage_log.md if not present:

- [ ] Connected [Tool] via MCP

---

Multiple Integrations

After first integration completes:

"Want to add another tool?

You can:
1. Browse more on Smithery.ai and paste another URL
2. Run `/create-mcp` to build something custom
3. Stop here and explore what you have

What sounds good?"

---

Troubleshooting Guide

If connection fails, provide specific debugging steps:

For authentication issues:

"Authentication failed. Let's debug:

1. Check your API key is correct
2. Verify it has the right permissions
3. Try testing it directly:

curl -H "Authorization: Bearer YOUR_KEY" [api-endpoint]

Want to try a different key?"

For installation issues:

"Installation failed. Common fixes:

1. Check Node/Python version:

node --version # Should be 18+ python --version # Should be 3.8+

2. Try installing globally:

npm install -g [package]

or

pip install --user [package]

3. Check for conflicts:

npm list -g | grep [package]

Want to try these steps?"

---

Alternative: Can't Find on Smithery

If user can't find what they need:

"Didn't find [Tool] on Smithery?

No worries - we can build it custom with `/create-mcp`.

That wizard will:
1. Help you find the tool's API docs
2. Design the integration together
3. Generate working MCP code
4. Get it integrated

Takes about 5-10 minutes depending on the API complexity.

Want to build [Tool] integration from scratch?"

Then hand off to /create-mcp skill.

---

Success Criteria

After integration:

• User can query their tool via natural language
• MCP is added to config
• Documentation is updated
• They know how to add more

The experience feels like:

• "That was easier than I expected"
• "I can do this for any tool I use"
• "This makes Dex way more powerful"

---

Track Usage (Silent)

Update System/usage_log.md to mark MCP integration as used.

Analytics (Silent):

Call track_event with event_name mcp_integrated and properties:

• (no properties — do NOT include server names)

This only fires if the user has opted into analytics. No action needed if it returns "analytics_disabled".