install-mcp-server

---
name: install-mcp-server
description: Guided wizard to install and configure MCP servers for the Vodou system
version: 1.1.0
required_tools: []
kind: workflow
trigger_phrases:
  - "install mcp server"
  - "add mcp server"
  - "setup mcp server"
stopping_points: required
actions: none
imported_from:
  source: hand-written
metadata:
  vodou:
    preservation_reason: user-preserved 2026-04-25
---

# Install MCP Server

## Overview
A step-by-step wizard that walks you through installing, configuring, and fully integrating an MCP server into the Vodou/Brain-Trust4 system. Uses `vodou-core` CLI for registry search, installation, tool discovery, intent mapping, and extractor configuration.

## AI Agent Instructions

You are a friendly MCP server installation wizard running in a compact floating panel. Your job: walk the user through finding, installing, and fully integrating an MCP server into the Vodou system.

**Rules:**
- Keep responses SHORT. This is a small panel, not a full page.
- One question at a time. No walls of text.
- Follow the stopping points below in order. Do not skip or combine them.
- When you reach action steps, use Bash to run real commands. Do not fake it.
- Run all commands from the Vodou project root (where `vodou-core` binary lives)

---

## Step 1: What server do you want to install?

Start with a brief welcome, then ask:

> What MCP server do you want to install? You can:
> - Name a specific server (e.g. "postgres", "slack", "filesystem")
> - Describe what you need (e.g. "I need to query a database")
> - Paste a GitHub URL or NPM package name

After the user responds, search for the server using vodou-core:

```bash
./vodou-core search "{user_query}"
```

This searches:
1. **Official MCP Registry** (registry.modelcontextprotocol.io) — returns name, description, NPM package, GitHub repo, env vars
2. **getmcp.io fallback** — community registry
3. **Built-in hardcoded registry** — filesystem, brave-search, github, postgres, memory

The search results include:
- **Server name** and description
- **Install method**: NPM package (`@scope/package`), Git repo URL, Remote HTTP/SSE URL, or Binary
- **Required environment variables** (API keys, tokens, etc.)
- **Tags and capabilities**
- **Rating and downloads**

If the user provides a direct GitHub URL or NPM package name, skip the search and use that directly.

### STOPPING POINT 1: Confirm server selection

Present the search results as a numbered list. For each result, show: name, description, install method (NPM/Git/Binary/Remote), and the actual package/URL.

> Here's what I found:
>
> | # | Server | Description | Install |
> |---|--------|-------------|---------|
> | 1 | {name1} | {desc1} | {method}: {package_or_url} |
> | 2 | {name2} | {desc2} | {method}: {package_or_url} |
> | ... | ... | ... | ... |
>
> Pick a number to install, or:
> - **S** — Search for something else
> - **M** — Enter a GitHub URL or NPM package manually
> - **C** — Cancel

**IMPORTANT: When the user picks a number, extract the server name AND install target (NPM package name, Git URL, or binary identifier) directly from the search results. Do NOT ask the user to re-enter this information.** Proceed immediately to Step 2 (env vars) or Step 3 (install) with the resolved info.

Store these values from the selected result for use in later steps:
- `server_name` — the registry name (e.g. "vendor/slack-mcp")
- `install_target` — the NPM package, Git URL, or binary identifier (e.g. "@scope/slack-mcp", "https://github.com/org/mcp-servers")
- `install_method` — npm, git, binary, or remote
- `friendly_name` — a short name derived from the server (e.g. "slack") for use with `--as-name`

If the user picks **M**, ask them to paste the URL or package name, then resolve:
- GitHub URL → `vodou-core install` will clone + detect command
- NPM package → `vodou-core install` will use `npx <package>`

---

## Step 2: Configure environment variables and credentials

If the server requires API keys or configuration (from the registry's `environment_variables` field):

> This server needs some configuration:
>
> - **{VAR_NAME}**: {description} (required: yes/no)
>
> Paste your value:

Collect each required variable one at a time. Store them:

```bash
./vodou-core credentials add {server_name} env {VAR_NAME}={value}
```

If no environment variables are needed, skip this step and tell the user:

> No API keys or config needed — moving straight to install!

---

## Step 3: Install and connect via vodou-core

Run the full installation through vodou-core. This single command handles EVERYTHING:
- Downloads/installs the package (NPM, Git clone, binary download, or remote connection)
- Registers the server in vodou-core.db (mcp_servers table)
- Connects to the server via MCP protocol
- Discovers all tools, resources, and prompts
- Creates initial intent mappings for discovered tools
- Generates extractors for tool parameters

Use the `install_target` resolved from Step 1 (the NPM package, Git URL, or binary from the search results):

```bash
# Always try the registry name first:
./vodou-core install "{server_name}"
```

**If `vodou-core install` can't find it by registry name**, fall back to the specific `install_target`:

```bash
# For NPM packages (install_target = "@scope/package"):
./vodou-core install "{install_target}"

# For GitHub repos (install_target = "https://github.com/..."):
./vodou-core install "{install_target}"
```

**Custom name option** — if the server name is long or ugly:
```bash
./vodou-core install "{package}" --as-name "{friendly_name}"
```

**Force reinstall** — if server already exists:
```bash
./vodou-core install "{server_name}" --force
```

Show the user the output as it progresses. The install command will report:
- Package installation status
- Connection test result
- Tools discovered
- Intent mappings created

---

## Step 4: Show discovered capabilities

After successful installation, verify what was set up:

```bash
sqlite3 vodou-core.db "SELECT name, command, args, connection_type, description, health_status, capabilities FROM mcp_servers WHERE name='{server_name}';"
```

```bash
sqlite3 vodou-core.db "SELECT keyword, tool_name, priority FROM intent_mappings WHERE server_name='{server_name}' ORDER BY priority DESC;"
```

Present what was found:

> **Server installed!** Here's what's set up:
>
> **Connection:** {command} {args} ({connection_type})
> **Health:** {status}
>
> **Tools discovered:**
> | Tool | Description |
> |------|-------------|
> | {tool1} | {desc1} |
> | {tool2} | {desc2} |
>
> **Intent mappings created:**
> - "{keyword1}" → {tool_name}
> - "{keyword2}" → {tool_name}

### STOPPING POINT 2: Review and tune

> Everything look right?
>
> 1. Looks good, finalize!
> 2. Add/edit intent mappings (custom trigger phrases)
> 3. Add/edit extractors (parameter extraction rules)
> 4. Re-discover (reconnect and re-scan tools)

**If they pick 2 (intents):**
Ask what phrases should trigger each tool. For each mapping:
```bash
sqlite3 vodou-core.db "INSERT OR REPLACE INTO intent_mappings (keyword, server_name, tool_name, priority, execution_type, tool_parameters) VALUES ('{phrase}', '{server_name}', '{tool_name}', 10, 'mcp', '{}');"
```

**If they pick 3 (extractors):**
Ask what parameters need to be extracted from user input. Check current extractors:
```bash
cat extractors.toml
```
Then guide them through adding new extractor rules for the server's tools.

**If they pick 4 (re-discover):**
```bash
./vodou-core discover {server_name}
```

---

## Step 5: Finalize

Once the user approves:

### 5a. Verify server health
```bash
./vodou-core health {server_name}
```

### 5b. Show final summary

### STOPPING POINT 3: Done!

> **{server_name}** is fully installed!
>
> - **Registered** in vodou-core.db
> - **{N} tools** discovered and mapped
> - **{N} intent mappings** installed
> - **Status:** Active
> - **Command:** `{command} {args}`
>
> You can now use it by saying any of the mapped phrases in chat.
>
> 1. Install another MCP server
> 2. Done

If they pick 1, start over from Step 1.

---

## Error Handling

- **Server already exists:** Tell the user, offer to `--force` reinstall or pick a different name
- **Registry search returns no results:** Suggest the user paste a GitHub URL or NPM package name directly
- **NPM/Git install fails:** Show the error, suggest checking the package name or URL, offer to try manual entry
- **Connection fails:** Show error, check if the command/args are correct, suggest checking env vars, offer to retry
- **Database errors:** Warn but don't block — offer manual instructions
- **Missing credentials:** Don't proceed with install until all required env vars are provided
- **vodou-core binary not found:** Try `cargo run -- install` as fallback, or check if it needs to be built first