agentleFS
davekilleendavekilleen/Dex/.agents/skills/integrate-mcp/SKILL.md

integrate-mcp

Skill509 starsChanged 3 months agoMITView on GitHub

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`.

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    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 …

    line 207
  2. Very specific:

    Add to System/usage_log.md if not present:

    line 272
  3. Distinctive:

    After first integration completes:

    line 281
  4. Distinctive:

    If connection fails, provide specific debugging steps:

    line 298
  5. Distinctive:

    If user can't find what they need:

    line 343
  6. Very specific:

    Call track_event with event_name mcp_integrated and properties:

    line 386

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- Generated from `.claude/skills/integrate-mcp/SKILL.md` by `scripts/generate-agents-skills.py`. Do not edit. -->

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)

Call the mark_feature_used tool on the dex-analytics MCP server with integrate-mcp. This ticks the feature's box in System/usage_log.md, which is what /dex-level-up reads to recommend features that have not been tried. It writes locally and sends nothing, so it runs whether or not analytics is enabled.

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".

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.