# IDE and CLI Integration Guide
> Get up and running with Amicus MCP in under 5 minutes
This guide covers how to integrate the Amicus MCP server with various IDEs and CLI clients. Choose your preferred environment and follow the step-by-step instructions.
## Table of Contents
- [VS Code (Official & Insiders)](#vs-code-official--insiders)
- [Cursor](#cursor)
- [Windsurf](#windsurf)
- [Claude Desktop App](#claude-desktop-app)
- [Zed Editor](#zed-editor)
- [Claude CLI](#claude-cli)
- [GitHub Copilot CLI](#github-copilot-cli)
- [Direct MCP Protocol](#direct-mcp-protocol)
- [Troubleshooting](#troubleshooting)
---
## Prerequisites
Before integrating with any IDE, install Amicus MCP:
```bash
uv tool install amicus-mcp --force
amicus-mcp --version # Verify installation
```
For development installations, see the [main README](../README.md).
---
## Dynamic Configuration Generator
Amicus includes a built-in configuration generator that creates properly formatted MCP configurations for any supported client.
### List Supported Clients
```bash
amicus-mcp --list-clients
```
### Generate Configuration
```bash
# Print to stdout (useful for copying)
amicus-mcp --client <client-name> --generate-mcp-config stdout
# Write to global config file
amicus-mcp --client <client-name> --generate-mcp-config global --force
# Write to workspace config file
amicus-mcp --client <client-name> --generate-mcp-config workspace --force
```
### Supported Clients
| Client | Global Config | Workspace Config |
|--------|---------------|------------------|
| `copilot` | `~/.copilot/mcp-config.json` | `.github/mcp.json` |
| `claude-desktop` | `~/Library/Application Support/Claude/claude_desktop_config.json` | - |
| `claude-code` | (use `claude mcp add`) | `.mcp.json` |
| `vscode` | (use settings) | `.vscode/mcp.json` |
| `cursor` | - | `.cursor/mcp.json` |
| `windsurf` | `~/.codeium/windsurf/mcp_config.json` | `.windsurf/mcp.json` |
| `zed` | (use settings) | `.zed/settings.json` |
### Examples
```bash
# Generate GitHub Copilot CLI config
amicus-mcp --client copilot --generate-mcp-config global --force
# Generate Cursor workspace config
amicus-mcp --client cursor --generate-mcp-config workspace --force
# Generate Claude Desktop config
amicus-mcp --client claude-desktop --generate-mcp-config global --force
# Preview Zed config without writing
amicus-mcp --client zed --generate-mcp-config stdout
```
---
## VS Code (Official & Insiders)
VS Code's MCP support is integrated through extensions. The configuration can be done via settings UI or manually.
### Quick Install
Add via command line (easiest method):
```bash
code --add-mcp '{"type":"stdio","name":"amicus","command":"uvx","args":["amicus-mcp"]}'
```
### Manual Configuration
**Option 1: Project-Level Configuration**
Create `.vscode/mcp.json` in your project root:
```json
{
"mcpServers": {
"amicus": {
"command": "uvx",
"args": ["amicus-mcp"],
"env": {}
}
}
}
```
**Option 2: User Settings**
Open VS Code Settings (JSON) and add:
```json
{
"mcp.servers": {
"amicus": {
"command": "uvx",
"args": ["amicus-mcp"]
}
}
}
```
### Enable MCP in Chat
1. Open Settings (Cmd/Ctrl + ,)
2. Search for "MCP"
3. Enable `Chat > Mcp > Discovery` (auto-discover tools)
4. Enable `Chat > Mcp` (enable MCP servers in chat)
### Verify Installation
1. Open GitHub Copilot Chat
2. Type: "List available MCP tools"
3. You should see Amicus tools listed
### VS Code Insiders
Same configuration as VS Code, but use `code-insiders` command:
```bash
code-insiders --add-mcp '{"type":"stdio","name":"amicus","command":"uvx","args":["amicus-mcp"]}'
```
---
## Cursor
Cursor has excellent MCP support with a dedicated configuration UI.
### Quick Setup (UI Method)
1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to **Tools & Integrations** → **New MCP Server**
3. Fill in the form:
- **Name**: `Amicus`
- **Type**: `command`
- **Command**: `uvx amicus-mcp`
4. Click **Save**
### Manual Configuration
Create or edit `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"amicus": {
"command": "uvx",
"args": ["amicus-mcp"]
}
}
}
```
### Project-Specific Configuration
Cursor automatically recognizes `.cursor/mcp.json` when you open a project. This is ideal for team sharing.
### Verify Installation
1. Open Cursor Chat
2. Ask: "What MCP tools are available?"
3. Amicus tools should appear
---
## Windsurf
Windsurf supports MCP through its Cascade AI system.
### Quick Setup (UI Method)
1. Open Settings (Cmd/Ctrl + ,)
2. Scroll to **Cascade** section
3. Click **MCP servers**
4. Click **Add Server** → **Add custom server**
5. Fill in:
- **Name**: `Amicus`
- **Command**: `uvx`
- **Args**: `["amicus-mcp"]`
### Manual Configuration
Edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"amicus": {
"command": "uv",
"args": ["tool", "run", "amicus-mcp"],
"env": {
"CONTEXT_BUS_DIR": "/path/to/your/project/.ai"
}
}
}
}
```
### Project-Level Configuration
Create `.windsurf/mcp.json` in your project:
```json
{
"mcpServers": {
"amicus": {
"command": "uvx",
"args": ["amicus-mcp"]
}
}
}
```
### Restart Required
After configuration, restart Windsurf for changes to take effect.
---
## Claude Desktop App
The Claude Desktop app supports MCP through a configuration file.
### Configuration by Platform
#### macOS
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"amicus": {
"command": "uvx",
"args": ["amicus-mcp"]
}
}
}
```
#### Windows
Edit `%APPDATA%/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"amicus": {
"command": "cmd",
"args": ["/c", "uvx", "amicus-mcp"]
}
}
}
```
**Note:** On Windows, the `cmd /c` wrapper is required for npx/uvx commands.
#### Linux
Edit `~/.config/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"amicus": {
"command": "uvx",
"args": ["amicus-mcp"]
}
}
}
```
### Access Configuration File
**Via UI:**
1. Open Claude Desktop
2. Click **Settings** (toolbar)
3. Navigate to **Developer** tab
4. Click **Edit Config**
This opens the config file directory in your file manager.
### Restart Required
After editing the config file, restart Claude Desktop.
### Verify Installation
In Claude Desktop chat:
1. Type: "What MCP tools do you have access to?"
2. Look for Amicus tools in the response
---
## Zed Editor
Zed has native MCP support through the Model Context Protocol integration.
### Configuration Method 1: Settings UI
1. Open Zed
2. Go to **Preferences** → **Settings** (Cmd/Ctrl + ,)
3. Add to your `settings.json`:
```json
{
"context_servers": {
"amicus": {
"source": "custom",
"command": "uvx",
"args": ["amicus-mcp"],
"env": {}
}
}
}
```
### Configuration Method 2: Via Extension
Zed supports MCP servers as extensions. Check the Zed extension marketplace for pre-packaged MCP servers.
### Project-Level Configuration
Create `.zed/settings.json` in your project:
```json
{
"context_servers": {
"amicus": {
"source": "custom",
"command": "uvx",
"args": ["amicus-mcp"]
}
}
}
```
### Advanced Configuration
For custom environment variables:
```json
{
"context_servers": {
"amicus": {
"source": "custom",
"command": "uvx",
"args": ["amicus-mcp"],
"env": {
"CONTEXT_BUS_DIR": "/path/to/project/.ai"
}
}
}
}
```
### Verify Installation
1. Open Zed Assistant
2. Check for available context servers
3. Amicus should be listed
---
## Claude CLI
The Claude CLI (claude-cli) supports MCP through the `claude mcp` commands.
### Quick Setup
Add Amicus with a single command:
```bash
claude mcp add amicus --transport stdio -- uvx amicus-mcp
```
### Configuration Scopes
The `--scope` flag controls where configuration is stored:
```bash
# User-level (available across all projects)
claude mcp add amicus --scope user --transport stdio -- uvx amicus-mcp
# Project-level (shared via .mcp.json)
claude mcp add amicus --scope project --transport stdio -- uvx amicus-mcp
# Local (current project only, not shared)
claude mcp add amicus --scope local --transport stdio -- uvx amicus-mcp
```
### Windows Configuration
On Windows, use the `cmd /c` wrapper:
```bash
claude mcp add amicus --transport stdio -- cmd /c uvx amicus-mcp
```
### Verify Installation
List configured MCP servers:
```bash
claude mcp list
```
Test the server:
```bash
claude mcp get amicus
```
### Remove Server
If you need to reconfigure:
```bash
claude mcp remove amicus
```
### Manual Configuration
Alternatively, edit the config file directly:
**macOS/Linux:**
`~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:**
`%APPDATA%/Claude/claude_desktop_config.json`
Add:
```json
{
"mcpServers": {
"amicus": {
"command": "uvx",
"args": ["amicus-mcp"]
}
}
}
```
After editing, restart Claude CLI or reload config:
```bash
claude mcp list # Verify changes
```
---
## GitHub Copilot CLI
GitHub Copilot CLI (v0.0.400+) supports MCP through native protocol integration.
### Quick Setup
Use the dynamic configuration generator:
```bash
# Generate and install global configuration
amicus-mcp --client copilot --generate-mcp-config global --force
# Or generate workspace configuration for team sharing
amicus-mcp --client copilot --generate-mcp-config workspace --force
```
### Manual Configuration
**Global Configuration:** `~/.copilot/mcp-config.json`
```json
{
"mcpServers": {
"amicus": {
"command": "/path/to/amicus-mcp",
"args": [],
"env": {},
"tools": ["*"]
}
}
}
```
**Workspace Configuration:** `.github/mcp.json`
```json
{
"mcpServers": {
"amicus": {
"command": "amicus-mcp",
"args": [],
"env": {},
"tools": ["*"]
}
}
}
```
> **Important**: The `tools` array is required by Copilot CLI's Zod schema validation. Use `["*"]` to enable all tools.
### Configuration Requirements
Copilot CLI has specific requirements for MCP server configuration:
1. **`tools` array is required** - Must be `["*"]` or list specific tool names
2. **`args` must be empty** - Amicus runs in stdio mode by default
3. **Full path recommended** for global config - Use `which amicus-mcp` to get path
### Verify Installation
```bash
# Start Copilot CLI and list tools
copilot --prompt "list available MCP tools"
```
You should see all 19 Amicus tools listed:
- `read_state`, `update_state`, `add_task`, `claim_task`, `complete_task`
- `register_node`, `set_agent_status`, `claim_best_task`, `assess_workload`
- `broadcast_message`, `heartbeat`, `toggle_tracking`
- `is_safe_path`, `execute_safe_command`, `get_best_model`
- `create_github_issue`, `list_github_issues`, `import_github_issue_to_task`, `sync_task_to_github_issue`
### Example Usage
```bash
# Read current state
copilot --prompt "Use read_state to show the amicus context bus"
# Add a task
copilot --prompt "Use add_task to create a task: Review authentication module"
# Register as an agent
copilot --prompt "Use register_node to register as developer agent"
```
### Troubleshooting
**"Invalid input" error:**
- Ensure `tools` array is present in configuration
- Verify JSON syntax is valid
**"unrecognized arguments: stdio" error:**
- Change `args` from `["stdio"]` to `[]`
- Amicus runs in stdio mode by default without arguments
**Server not loading:**
- Check full path to amicus-mcp is correct: `which amicus-mcp`
- Verify amicus-mcp runs standalone: `amicus-mcp --version`
- Check Copilot CLI logs for errors
### Testing Documentation
Comprehensive testing documented in [GitHub Issue #6](https://github.com/earchibald/amicus-mcp/issues/6).
---
## Direct MCP Protocol
For advanced users or custom integrations, you can connect directly to the Amicus MCP server.
### Start the Server
```bash
amicus-mcp
```
This starts the server using stdio transport.
### Using uvx
For one-shot execution:
```bash
uvx amicus-mcp
```
### HTTP Transport (Advanced)
Amicus currently supports stdio transport. For HTTP transport, you would need to wrap the server with an HTTP adapter.
### Testing with MCP Inspector
Use the official MCP inspector for debugging:
```bash
npx @modelcontextprotocol/inspector uvx amicus-mcp
```
This opens a web UI for testing MCP tools interactively.
### Example: Python Client
```python
import subprocess
import json
# Start Amicus MCP server
proc = subprocess.Popen(
["uvx", "amicus-mcp"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True
)
# Send MCP initialize request
init_request = {
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "custom-client", "version": "1.0.0"}
}
}
proc.stdin.write(json.dumps(init_request) + "\n")
proc.stdin.flush()
# Read response
response = proc.stdout.readline()
print(response)
```
### Example: curl (HTTP servers only)
If using an HTTP-wrapped MCP server:
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}'
```
---
## Troubleshooting
### Common Issues
#### Issue: "Command not found: uvx"
**Solution:** Install uv:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Or via pipx:
```bash
pipx install uv
```
#### Issue: "Permission denied"
**Solution:** Ensure amicus-mcp is installed correctly:
```bash
uv tool install amicus-mcp --force
which amicus-mcp # Should show a valid path
```
#### Issue: MCP server not appearing in IDE
**Solutions:**
1. Restart the IDE completely
2. Verify config file syntax (valid JSON)
3. Check IDE logs for errors
4. Test the command manually: `uvx amicus-mcp`
#### Issue: "No state file found"
**Solution:** Initialize the project:
```bash
cd /path/to/your/project
amicus-mcp --init
```
#### Issue: State not persisting between sessions
**Solution:** Verify `.ai/` directory exists and is writable:
```bash
ls -la .ai/
amicus-mcp --validate-env
```
#### Issue: Tools not working in chat
**Solutions:**
1. Verify tools are loaded: `amicus-mcp --list-tools`
2. Check MCP server status in IDE settings
3. Ensure the IDE has MCP enabled (some require feature flags)
### Platform-Specific Issues
#### macOS: "Developer cannot be verified"
**Solution:**
```bash
xattr -d com.apple.quarantine $(which amicus-mcp)
```
#### Windows: Path issues
**Solution:** Use full paths in config:
```json
{
"command": "C:\\Users\\YourName\\.local\\bin\\uvx.exe",
"args": ["amicus-mcp"]
}
```
#### Linux: Python version conflicts
**Solution:** Ensure Python 3.10+ is default:
```bash
python3 --version # Should be 3.10+
update-alternatives --config python3
```
### Debug Mode
Enable verbose logging:
```bash
export AMICUS_DEBUG=1
amicus-mcp
```
### Getting Help
If you encounter issues not covered here:
1. Check [GitHub Issues](https://github.com/earchibald/amicus-mcp/issues)
2. Run diagnostics: `amicus-mcp --validate-env`
3. Check IDE-specific logs
4. Create a new issue with:
- Your IDE and version
- Platform (macOS/Windows/Linux)
- Amicus version (`amicus-mcp --version`)
- Error messages and logs
---
## Quick Reference
### Installation Command
```bash
uv tool install amicus-mcp --force
```
### Basic Configuration Template
```json
{
"mcpServers": {
"amicus": {
"command": "uvx",
"args": ["amicus-mcp"]
}
}
}
```
### Essential CLI Commands
```bash
amicus-mcp --init # Initialize project
amicus-mcp --version # Show version
amicus-mcp --list-tools # List available tools
amicus-mcp --validate-env # Validate environment
amicus-mcp --show-state # Display current state
amicus-mcp --list-clients # List supported MCP clients
amicus-mcp --client <name> --generate-mcp-config <target> # Generate config
```
### Config File Locations
| Platform | Path |
|----------|------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%/Claude/claude_desktop_config.json` |
| **Linux** | `~/.config/Claude/claude_desktop_config.json` |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **VS Code** | `.vscode/mcp.json` (project) or user settings |
| **Cursor** | `.cursor/mcp.json` (project) |
| **Zed** | `settings.json` → `context_servers` |
---
## Next Steps
After successful integration:
1. **Initialize your project:**
```bash
cd /path/to/your/project
amicus-mcp --init
```
2. **Verify tools are available:**
Ask your AI assistant: "What Amicus MCP tools are available?"
3. **Start using Amicus:**
- "Use read_state to check the context bus"
- "Add a task to review the authentication module"
- "Register this agent as a developer node"
4. **Explore advanced features:**
- [Synapse Protocol](SYNAPSE_PROTOCOL.md) - Multi-agent coordination
- [Anti-Idle System](ANTI_IDLE_SYSTEM.md) - Automatic node lifecycle
- [GitHub Workflow](GITHUB_WORKFLOW.md) - Issue integration
---
## Related Documentation
- [Main README](../README.md) - Project overview and features
- [Security Guide](../SECURITY.md) - Security considerations
- [Synapse Protocol](SYNAPSE_PROTOCOL.md) - Agent coordination patterns
- [Bootstrap Manager](BOOTSTRAP_MANAGER.md) - Cluster management
- [GitHub Workflow](GITHUB_WORKFLOW.md) - GitHub integration
---
**Last Updated:** 2026-02-02
**Version:** 0.5.2
**Maintained by:** Amicus Synapse Cluster
For questions or contributions, visit [GitHub](https://github.com/earchibald/amicus-mcp).
