516 lines
11 KiB
Markdown
516 lines
11 KiB
Markdown
# Adding MCP Servers via CLI (End User Guide)
|
|
|
|
**For end users who want to add custom MCP servers without editing code.**
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Add an MCP server from NPM
|
|
npx agentic-flow mcp add my-mcp-server --npm
|
|
|
|
# Add a local MCP server
|
|
npx agentic-flow mcp add my-local-server --command "node /path/to/server.js"
|
|
|
|
# Add with environment variables
|
|
npx agentic-flow mcp add weather-api --npm weather-mcp --env "WEATHER_API_KEY=xxx"
|
|
|
|
# List configured MCP servers
|
|
npx agentic-flow mcp list
|
|
|
|
# Remove an MCP server
|
|
npx agentic-flow mcp remove my-mcp-server
|
|
|
|
# Enable/disable MCP server
|
|
npx agentic-flow mcp enable my-mcp-server
|
|
npx agentic-flow mcp disable my-mcp-server
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration File
|
|
|
|
MCP servers are stored in `~/.agentic-flow/mcp-config.json`:
|
|
|
|
```json
|
|
{
|
|
"servers": {
|
|
"my-custom-server": {
|
|
"enabled": true,
|
|
"type": "npm",
|
|
"package": "my-mcp-package@latest",
|
|
"command": "my-mcp",
|
|
"args": ["start"],
|
|
"env": {
|
|
"MY_API_KEY": "xxx"
|
|
},
|
|
"description": "My custom MCP server"
|
|
},
|
|
"local-tools": {
|
|
"enabled": true,
|
|
"type": "local",
|
|
"command": "node",
|
|
"args": ["/home/user/my-mcp/index.js"],
|
|
"env": {},
|
|
"description": "Local development MCP server"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## CLI Commands
|
|
|
|
### 1. Add MCP Server
|
|
|
|
#### From NPM Package
|
|
```bash
|
|
# Basic NPM package
|
|
npx agentic-flow mcp add weather-api --npm weather-mcp
|
|
|
|
# With version
|
|
npx agentic-flow mcp add weather-api --npm weather-mcp@1.2.3
|
|
|
|
# With custom command
|
|
npx agentic-flow mcp add weather-api --npm weather-mcp --command mcp-server
|
|
|
|
# With environment variables
|
|
npx agentic-flow mcp add weather-api \
|
|
--npm weather-mcp \
|
|
--env "WEATHER_API_KEY=your-key-here" \
|
|
--env "WEATHER_REGION=us-west"
|
|
|
|
# With description
|
|
npx agentic-flow mcp add weather-api \
|
|
--npm weather-mcp \
|
|
--desc "Weather data MCP server"
|
|
```
|
|
|
|
#### From Local Path
|
|
```bash
|
|
# Local executable
|
|
npx agentic-flow mcp add my-tools --local /home/user/my-mcp/server.js
|
|
|
|
# With node
|
|
npx agentic-flow mcp add my-tools \
|
|
--command "node" \
|
|
--args "/home/user/my-mcp/server.js"
|
|
|
|
# With Python
|
|
npx agentic-flow mcp add python-tools \
|
|
--command "python3" \
|
|
--args "/home/user/mcp-server.py"
|
|
|
|
# With custom arguments
|
|
npx agentic-flow mcp add advanced-tools \
|
|
--command "node" \
|
|
--args "/path/to/server.js --port 8080 --debug"
|
|
```
|
|
|
|
#### With Docker
|
|
```bash
|
|
# Docker container
|
|
npx agentic-flow mcp add docker-mcp \
|
|
--command "docker" \
|
|
--args "run -i --rm my-mcp-image"
|
|
```
|
|
|
|
### 2. List MCP Servers
|
|
|
|
```bash
|
|
# List all configured servers
|
|
npx agentic-flow mcp list
|
|
|
|
# Output:
|
|
# Configured MCP Servers:
|
|
#
|
|
# ✅ weather-api (enabled)
|
|
# Type: npm
|
|
# Package: weather-mcp@latest
|
|
# Description: Weather data MCP server
|
|
#
|
|
# ✅ my-tools (enabled)
|
|
# Type: local
|
|
# Command: node /home/user/my-mcp/server.js
|
|
#
|
|
# ❌ old-server (disabled)
|
|
# Type: npm
|
|
# Package: old-mcp@1.0.0
|
|
|
|
# List only enabled
|
|
npx agentic-flow mcp list --enabled
|
|
|
|
# Show full config
|
|
npx agentic-flow mcp list --verbose
|
|
```
|
|
|
|
### 3. Enable/Disable MCP Server
|
|
|
|
```bash
|
|
# Enable server
|
|
npx agentic-flow mcp enable weather-api
|
|
|
|
# Disable server
|
|
npx agentic-flow mcp disable weather-api
|
|
|
|
# Enable all
|
|
npx agentic-flow mcp enable --all
|
|
|
|
# Disable all
|
|
npx agentic-flow mcp disable --all
|
|
```
|
|
|
|
### 4. Remove MCP Server
|
|
|
|
```bash
|
|
# Remove server
|
|
npx agentic-flow mcp remove weather-api
|
|
|
|
# Remove with confirmation
|
|
npx agentic-flow mcp remove weather-api --confirm
|
|
|
|
# Remove all disabled servers
|
|
npx agentic-flow mcp remove --disabled
|
|
```
|
|
|
|
### 5. Update MCP Server
|
|
|
|
```bash
|
|
# Update NPM package version
|
|
npx agentic-flow mcp update weather-api --version 2.0.0
|
|
|
|
# Update environment variables
|
|
npx agentic-flow mcp update weather-api \
|
|
--env "WEATHER_API_KEY=new-key"
|
|
|
|
# Update command
|
|
npx agentic-flow mcp update my-tools \
|
|
--command "node" \
|
|
--args "/new/path/server.js"
|
|
```
|
|
|
|
### 6. Test MCP Server
|
|
|
|
```bash
|
|
# Test if server responds
|
|
npx agentic-flow mcp test weather-api
|
|
|
|
# Output:
|
|
# Testing MCP server: weather-api
|
|
# ✅ Server started successfully
|
|
# ✅ Responds to tools/list
|
|
# ✅ Found 5 tools:
|
|
# - get_weather
|
|
# - get_forecast
|
|
# - get_alerts
|
|
# - get_historical
|
|
# - search_location
|
|
# ✅ Server is working correctly
|
|
|
|
# Test with verbose output
|
|
npx agentic-flow mcp test weather-api --verbose
|
|
```
|
|
|
|
### 7. Info/Docs
|
|
|
|
```bash
|
|
# Show server info
|
|
npx agentic-flow mcp info weather-api
|
|
|
|
# Output:
|
|
# MCP Server: weather-api
|
|
# Status: ✅ Enabled
|
|
# Type: npm
|
|
# Package: weather-mcp@1.2.3
|
|
# Command: npx -y weather-mcp start
|
|
# Environment:
|
|
# WEATHER_API_KEY: ***key***
|
|
# WEATHER_REGION: us-west
|
|
# Tools: 5 tools available
|
|
# Description: Weather data MCP server
|
|
|
|
# Show all tools from server
|
|
npx agentic-flow mcp tools weather-api
|
|
|
|
# Output:
|
|
# Tools from weather-api:
|
|
# 1. get_weather - Get current weather for location
|
|
# 2. get_forecast - Get weather forecast
|
|
# 3. get_alerts - Get weather alerts
|
|
# 4. get_historical - Get historical weather data
|
|
# 5. search_location - Search for location by name
|
|
```
|
|
|
|
---
|
|
|
|
## Usage in Agents
|
|
|
|
Once configured, MCP servers are automatically available to all agents:
|
|
|
|
```bash
|
|
# MCP servers load automatically
|
|
npx agentic-flow --agent researcher \
|
|
--task "Get weather for San Francisco using get_weather tool"
|
|
|
|
# All configured and enabled servers are available
|
|
# No need to specify which MCP server to use
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration via Environment Variables
|
|
|
|
You can also configure MCP servers via environment variables (temporary):
|
|
|
|
```bash
|
|
# Add MCP server for this session only
|
|
export AGENTIC_FLOW_MCP_WEATHER='{"type":"npm","package":"weather-mcp","env":{"API_KEY":"xxx"}}'
|
|
|
|
# Use it
|
|
npx agentic-flow --agent researcher --task "Get weather data"
|
|
```
|
|
|
|
---
|
|
|
|
## Popular MCP Servers
|
|
|
|
Here are some popular MCP servers you can add:
|
|
|
|
### Official Anthropic Servers
|
|
|
|
```bash
|
|
# Filesystem MCP
|
|
npx agentic-flow mcp add filesystem \
|
|
--npm @modelcontextprotocol/server-filesystem \
|
|
--args "/path/to/allowed/directory"
|
|
|
|
# GitHub MCP
|
|
npx agentic-flow mcp add github \
|
|
--npm @modelcontextprotocol/server-github \
|
|
--env "GITHUB_TOKEN=your-token"
|
|
|
|
# Google Drive MCP
|
|
npx agentic-flow mcp add gdrive \
|
|
--npm @modelcontextprotocol/server-gdrive \
|
|
--env "GDRIVE_CREDENTIALS=/path/to/creds.json"
|
|
|
|
# Brave Search MCP
|
|
npx agentic-flow mcp add brave-search \
|
|
--npm @modelcontextprotocol/server-brave-search \
|
|
--env "BRAVE_API_KEY=your-key"
|
|
```
|
|
|
|
### Community Servers
|
|
|
|
```bash
|
|
# Database MCP (PostgreSQL, MySQL)
|
|
npx agentic-flow mcp add database \
|
|
--npm mcp-database \
|
|
--env "DATABASE_URL=postgresql://localhost/mydb"
|
|
|
|
# Slack MCP
|
|
npx agentic-flow mcp add slack \
|
|
--npm mcp-slack \
|
|
--env "SLACK_TOKEN=xoxb-your-token"
|
|
|
|
# Email MCP (IMAP/SMTP)
|
|
npx agentic-flow mcp add email \
|
|
--npm mcp-email \
|
|
--env "EMAIL_HOST=imap.gmail.com" \
|
|
--env "EMAIL_USER=user@gmail.com" \
|
|
--env "EMAIL_PASS=app-password"
|
|
|
|
# Notion MCP
|
|
npx agentic-flow mcp add notion \
|
|
--npm @notionhq/mcp-server \
|
|
--env "NOTION_TOKEN=secret_xxx"
|
|
```
|
|
|
|
---
|
|
|
|
## Advanced Usage
|
|
|
|
### Custom Configuration File Path
|
|
|
|
```bash
|
|
# Use custom config file
|
|
export AGENTIC_FLOW_MCP_CONFIG=/path/to/custom-mcp-config.json
|
|
|
|
npx agentic-flow mcp list
|
|
```
|
|
|
|
### Multiple Profiles
|
|
|
|
```bash
|
|
# Development profile
|
|
export AGENTIC_FLOW_MCP_CONFIG=~/.agentic-flow/mcp-dev.json
|
|
npx agentic-flow mcp add local-tools --local /dev/tools/server.js
|
|
|
|
# Production profile
|
|
export AGENTIC_FLOW_MCP_CONFIG=~/.agentic-flow/mcp-prod.json
|
|
npx agentic-flow mcp add prod-tools --npm production-mcp
|
|
```
|
|
|
|
### Import/Export Configuration
|
|
|
|
```bash
|
|
# Export configuration
|
|
npx agentic-flow mcp export > my-mcp-config.json
|
|
|
|
# Import configuration
|
|
npx agentic-flow mcp import < my-mcp-config.json
|
|
|
|
# Share with team
|
|
cat my-mcp-config.json | pbcopy # macOS
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Server Not Working
|
|
|
|
```bash
|
|
# 1. Test server
|
|
npx agentic-flow mcp test my-server
|
|
|
|
# 2. Check if enabled
|
|
npx agentic-flow mcp list
|
|
|
|
# 3. Check logs
|
|
npx agentic-flow --agent coder --task "test" --verbose
|
|
# Look for: "Loading MCP server: my-server"
|
|
|
|
# 4. Test manually
|
|
npx my-mcp-package start
|
|
```
|
|
|
|
### Environment Variables Not Set
|
|
|
|
```bash
|
|
# Check current config
|
|
npx agentic-flow mcp info my-server
|
|
|
|
# Update env vars
|
|
npx agentic-flow mcp update my-server \
|
|
--env "API_KEY=correct-key"
|
|
```
|
|
|
|
### NPM Package Not Found
|
|
|
|
```bash
|
|
# Test NPM package
|
|
npx my-mcp-package --help
|
|
|
|
# Update package name
|
|
npx agentic-flow mcp update my-server \
|
|
--npm correct-package-name
|
|
```
|
|
|
|
---
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Don't Commit API Keys**
|
|
```bash
|
|
# Use environment variables
|
|
npx agentic-flow mcp add weather \
|
|
--npm weather-mcp \
|
|
--env "API_KEY=$WEATHER_API_KEY"
|
|
```
|
|
|
|
2. **Validate Sources**
|
|
```bash
|
|
# Check NPM package first
|
|
npm view weather-mcp
|
|
|
|
# Review package code
|
|
npm view weather-mcp repository
|
|
```
|
|
|
|
3. **Use Version Pinning**
|
|
```bash
|
|
# Pin to specific version
|
|
npx agentic-flow mcp add weather \
|
|
--npm weather-mcp@1.2.3 # Not @latest
|
|
```
|
|
|
|
4. **Review Permissions**
|
|
```bash
|
|
# Check what tools are available
|
|
npx agentic-flow mcp tools my-server
|
|
|
|
# Disable if not needed
|
|
npx agentic-flow mcp disable my-server
|
|
```
|
|
|
|
---
|
|
|
|
## Example Workflow
|
|
|
|
```bash
|
|
# 1. Install agentic-flow
|
|
npm install -g agentic-flow
|
|
|
|
# 2. Add weather MCP server
|
|
npx agentic-flow mcp add weather \
|
|
--npm weather-mcp \
|
|
--env "WEATHER_API_KEY=your-key" \
|
|
--desc "Real-time weather data"
|
|
|
|
# 3. Test it
|
|
npx agentic-flow mcp test weather
|
|
|
|
# 4. Use it
|
|
npx agentic-flow --agent researcher \
|
|
--task "Get current weather and 7-day forecast for Tokyo"
|
|
|
|
# 5. Check what it can do
|
|
npx agentic-flow mcp tools weather
|
|
|
|
# 6. Update if needed
|
|
npx agentic-flow mcp update weather --version 2.0.0
|
|
|
|
# 7. Share config with team
|
|
npx agentic-flow mcp export > team-mcp-config.json
|
|
```
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
**Quick Reference Card:**
|
|
|
|
| Task | Command |
|
|
|------|---------|
|
|
| Add NPM server | `npx agentic-flow mcp add NAME --npm PACKAGE` |
|
|
| Add local server | `npx agentic-flow mcp add NAME --local PATH` |
|
|
| List servers | `npx agentic-flow mcp list` |
|
|
| Test server | `npx agentic-flow mcp test NAME` |
|
|
| Enable/disable | `npx agentic-flow mcp enable/disable NAME` |
|
|
| Update config | `npx agentic-flow mcp update NAME --env "KEY=val"` |
|
|
| Remove server | `npx agentic-flow mcp remove NAME` |
|
|
| Show tools | `npx agentic-flow mcp tools NAME` |
|
|
|
|
**Config File:** `~/.agentic-flow/mcp-config.json`
|
|
|
|
**All enabled MCP servers automatically available to agents!**
|
|
|
|
---
|
|
|
|
## Implementation Status
|
|
|
|
**🚧 COMING SOON - This feature is not yet implemented.**
|
|
|
|
The CLI commands documented above will be available in **agentic-flow v1.2.0**.
|
|
|
|
**Current Workaround:** Use environment variables as documented in the [main guide](./ADDING-MCP-SERVERS.md).
|
|
|
|
**Track Progress:** https://github.com/ruvnet/agentic-flow/issues
|
|
|
|
---
|
|
|
|
**Want this feature sooner?** Contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
|