Skip to main content

​
What is MCP Integration?

Model Context Protocol (MCP) lets AI agents use external tools through a standardized interface. Automagik-tools provides instant MCP servers for any API - no code required.
Install once with uvx automagik-tools list and connect to Claude Desktop, Cursor, VSCode, and more.

​
Quick Start

​
1. Verify Installation

uvx automagik-tools list
You should see available tools like genie, omni, evolution-api, etc.

​
2. Generate MCP Config

uvx automagik-tools mcp-config genie
Output shows copy-paste ready JSON for your client.

​
3. Choose Your Client

Claude Code

Desktop & CLI

Cursor

IDE Integration

VSCode + Cline

VSCode Extension

​
Available Tools

Run uvx automagik-tools list to see all tools:
ToolDescriptionEnvironment Variables
genieGeneric MCP orchestrator with persistent memoryOptional: OPENAI_API_KEY
omniMulti-tenant omnichannel messaging (WhatsApp, Slack, Discord)Varies by instance
evolution-apiComplete WhatsApp messaging suiteEVOLUTION_API_BASE_URL, EVOLUTION_API_API_KEY
automagikAI-powered agents and workflowsAUTOMAGIK_API_KEY, AUTOMAGIK_BASE_URL
gemini-assistantGemini consultation with session managementGEMINI_API_KEY

​
Configuration Patterns

​
Basic Tool Setup

{
  "mcpServers": {
    "genie": {
      "command": "uvx",
      "args": ["automagik-tools@latest", "tool", "genie"]
    }
  }
}

​
Tool with Environment Variables

{
  "mcpServers": {
    "evolution-api": {
      "command": "uvx",
      "args": ["automagik-tools@latest", "tool", "evolution-api"],
      "env": {
        "EVOLUTION_API_BASE_URL": "http://localhost:8080",
        "EVOLUTION_API_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

​
Multiple Tools

{
  "mcpServers": {
    "genie": {
      "command": "uvx",
      "args": ["automagik-tools@latest", "tool", "genie"]
    },
    "omni": {
      "command": "uvx",
      "args": ["automagik-tools@latest", "tool", "omni"]
    },
    "evolution-api": {
      "command": "uvx",
      "args": ["automagik-tools@latest", "tool", "evolution-api"],
      "env": {
        "EVOLUTION_API_BASE_URL": "http://localhost:8080",
        "EVOLUTION_API_API_KEY": "YOUR_KEY"
      }
    }
  }
}

​
Custom OpenAPI Tools

Convert any OpenAPI spec to an MCP tool: 
# Test the conversion
uvx automagik-tools openapi https://api.github.com/openapi.json -t stdio

# Use in config
{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": [
        "automagik-tools@latest",
        "openapi",
        "https://api.github.com/openapi.json"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}
See Custom OpenAPI guide for details.

​
Testing Your Setup

​
1. Check Tool is Available

uvx automagik-tools list

​
2. Test Tool Runs

# Should output: "Starting MCP server 'Genie' with transport 'stdio'"
uvx automagik-tools tool genie -t stdio
Press Ctrl+C to stop.

​
3. Generate Config

uvx automagik-tools mcp-config genie
Copy the JSON to your client config file.

​
4. Restart Your Client

  • Claude Desktop: Quit completely (Cmd/Ctrl+Q) and reopen
  • Cursor: Reload window (Cmd/Ctrl+R)
  • VSCode: Reload window (Cmd/Ctrl+Shift+P → “Developer: Reload Window”)

​
5. Test Connection

Ask your AI client: 
"What MCP tools do you have access to?"
Expected: Should list “genie” or your configured tool name.

​
Troubleshooting

​
Tool Not Showing Up

Check logs: 
# Claude Desktop (macOS)
tail -f ~/Library/Logs/Claude/mcp*.log

# Cursor
# View → Output → Select "MCP"

# VSCode + Cline
# View → Output → Select "Cline"
Verify command: 
# Should work
uvx automagik-tools tool genie -t stdio

# If fails, check installation
uvx --version

​
Connection Refused

Test the tool directly: 
uvx automagik-tools tool TOOLNAME -t stdio
Should output “Starting MCP server…” without errors.

​
Authentication Errors

Verify environment variables: 
# Check if set
echo $EVOLUTION_API_API_KEY

# Test API access
curl -H "X-API-KEY: $EVOLUTION_API_API_KEY" http://localhost:8080

​
Client-Specific Setup

Claude Desktop/Code

Config: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)Test: “what tools are available?”

Cursor

Config: ~/.cursor/mcp.jsonTest: Cursor MCP status panel

VSCode + Cline

Config: VSCode Settings → Search “Cline MCP”Test: Cline panel shows tools

Custom OpenAPI

Convert any API to MCPWorks with all clients

​
Common Issues

​
uvx: command not found

Install uv: 
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

​
Tool version mismatch

Force latest version: 
uvx --reinstall automagik-tools@latest list

​
JSON syntax errors

Validate your config: 
# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool

# Or use online validator
# https://jsonlint.com
No trailing commas allowed in JSON!

​
Next Steps

  1. Choose your client setup guide above
  2. Copy the tested config examples
  3. Restart your client
  4. Test with “what tools are available?”
  5. Start using MCP tools in natural language
All configs on this page are tested and work as-is. Just replace API keys with your actual values.