MCP Connection Errors

Overview

MCP (Model Context Protocol) enables AI clients to use your API tools. This guide helps troubleshoot connection issues between MCP clients (Claude, Cursor, etc.) and Automagik Tools MCP server.

Connection Issues

MCP Server Not Found

Problem: AI client can’t find or connect to MCP server Symptoms:

Tools don’t appear in AI client
“MCP server not responding” errors
Connection timeout messages

Solutions:

Verify MCP Configuration

Claude Code (~/.claude/mcp.json):

{
  "mcpServers": {
    "my-api-tools": {
      "command": "uvx",
      "args": ["automagik-tools", "mcp", "--spec", "/absolute/path/to/spec.json"]
    }
  }
}

Cursor (Settings → MCP):

{
  "mcp.servers": {
    "my-api-tools": {
      "command": "uvx",
      "args": ["automagik-tools", "mcp", "--spec", "/absolute/path/to/spec.json"]
    }
  }
}

Important: Use absolute paths, not relative paths

Test MCP Server Directly

# Test if server starts correctly
uvx automagik-tools mcp --spec /path/to/spec.json

# Should output: "MCP server running in stdio mode"
# Press Ctrl+C to exit

# If errors appear, fix them before configuring client

Check Command Availability

# Verify uvx is in PATH
which uvx
uvx --version

# Test full command
uvx automagik-tools --version

# If not found, add to PATH
export PATH="$HOME/.cargo/bin:$PATH"

stdio vs SSE Mode Confusion

Problem: Wrong transport mode configured Understanding Transports:

stdio (Default)
SSE (Server-Sent Events)

Best for: Local AI clients (Claude Code, Cursor)

{
  "mcpServers": {
    "my-api-tools": {
      "command": "uvx",
      "args": ["automagik-tools", "mcp", "--spec", "spec.json"]
      // No --sse flag = stdio mode (default)
    }
  }
}

Characteristics:

Uses standard input/output
No network ports required
Most compatible with desktop AI clients

Solution: Use stdio for local clients unless you specifically need SSE

Port Already in Use (SSE Mode)

Problem: Error: Address already in use: 0.0.0.0:8000 Solution:

# Find process using the port
lsof -i :8000  # macOS/Linux
netstat -ano | findstr :8000  # Windows

# Kill the process
kill -9 <PID>  # macOS/Linux
taskkill /PID <PID> /F  # Windows

# Or use different port
uvx automagik-tools mcp --spec spec.json --sse --port 8001

# Update client config to match new port

Tools Not Appearing in Client

Problem: MCP server connected but tools don’t show in AI client Solutions:

Verify OpenAPI Spec

# Validate spec file
uvx automagik-tools validate --spec spec.json

# Should output: "✓ OpenAPI spec is valid"
# Fix any validation errors

Check Server Logs

Claude Code:

# Check logs for errors
tail -f ~/.claude/logs/mcp-my-api-tools.log

# Look for tool registration messages

Cursor:

Help → Show Logs → MCP Logs

Restart AI Client

Claude Code:

Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
Type: "Reload MCP Servers"

Cursor:

Cmd+R (macOS) or Ctrl+R (Windows/Linux)
Or: View → Reload Window

Verify Tool Names

# List tools from spec
uvx automagik-tools list-tools --spec spec.json

# Ask AI client: "What MCP tools are available?"
# Tool names should match

Configuration Issues

Environment Variables Not Loaded

Problem: API keys or configuration not available to MCP server Solutions:

Set in MCP Configuration

{
  "mcpServers": {
    "my-api-tools": {
      "command": "uvx",
      "args": ["automagik-tools", "mcp", "--spec", "spec.json"],
      "env": {
        "API_KEY": "your-api-key-here",
        "BASE_URL": "https://api.example.com",
        "TIMEOUT": "30"
      }
    }
  }
}

Note: Environment variables set here override system variables

Use .env File

# Create .env in same directory as spec
cat > .env << EOF
API_KEY=your-api-key
BASE_URL=https://api.example.com
EOF

# Reference in MCP config
{
  "command": "uvx",
  "args": ["automagik-tools", "mcp", "--spec", "spec.json", "--env-file", ".env"]
}

Set System-Wide

# Add to shell profile
echo 'export API_KEY=your-key' >> ~/.bashrc
echo 'export BASE_URL=https://api.example.com' >> ~/.bashrc
source ~/.bashrc

# For AI clients to see variables:
# 1. Set variables
# 2. Restart AI client from terminal
# 3. Variables are now available to MCP servers

Absolute vs Relative Paths

Problem: MCP server can’t find spec file Error: FileNotFoundError: spec.json not found Solution:

# ❌ Wrong: Relative path (may not work)
{
  "args": ["automagik-tools", "mcp", "--spec", "spec.json"]
}

# ✅ Correct: Absolute path
{
  "args": ["automagik-tools", "mcp", "--spec", "/Users/you/project/spec.json"]
}

# Get absolute path
pwd  # Shows current directory
realpath spec.json  # Shows absolute path

# macOS/Linux
"args": ["automagik-tools", "mcp", "--spec", "/home/user/project/spec.json"]

# Windows (use forward slashes in JSON)
"args": ["automagik-tools", "mcp", "--spec", "C:/Users/user/project/spec.json"]

Working Directory Issues

Problem: MCP server runs in wrong directory Solution:

{
  "mcpServers": {
    "my-api-tools": {
      "command": "uvx",
      "args": ["automagik-tools", "mcp", "--spec", "/path/to/spec.json"],
      "cwd": "/path/to/project"  // Set working directory
    }
  }
}

Authentication Issues

API Authentication Failures

Problem: Tools execute but return 401/403 errors Common Causes:

Missing API Key
Bearer Token
OAuth 2.0
Basic Auth

# Verify API key is set
echo $API_KEY

# Set in MCP config
{
  "env": {
    "API_KEY": "your-actual-api-key-here"
  }
}

# Or use security component
{
  "securitySchemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key"
    }
  }
}

Environment Variable Substitution Not Working

Problem: Variables like ${API_KEY} not being replaced Solution:

# Some MCP clients don't support variable substitution
# Use actual values instead

# ❌ May not work
{
  "env": {
    "API_KEY": "${MY_API_KEY}"
  }
}

# ✅ Use actual value
{
  "env": {
    "API_KEY": "actual-key-value-here"
  }
}

# Or load from shell before starting client
export API_KEY=your-key
# Start AI client from same terminal

Client-Specific Issues

Claude Code Issues

Problem: MCP servers not loading in Claude Code

Check Configuration File

# Location
~/.claude/mcp.json  # macOS/Linux
%APPDATA%\Claude\mcp.json  # Windows

# Validate JSON syntax
cat ~/.claude/mcp.json | python -m json.tool

# Common mistakes:
# - Missing commas
# - Trailing commas
# - Unescaped quotes
# - Invalid JSON structure

Check Logs

# View logs
tail -f ~/.claude/logs/mcp-*.log

# Look for errors like:
# - "Command not found"
# - "Spec file not found"
# - "Invalid JSON"
# - "Tool registration failed"

Reload MCP Servers

Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
Type: "Reload MCP Servers"
Wait for reload to complete
Check logs for errors

Cursor Issues

Problem: MCP integration not working in Cursor

Enable MCP in Settings

Open Cursor Settings (Cmd+, or Ctrl+,)
Search for "MCP"
Enable "MCP Server Support"
Add server configuration

Check Settings JSON

// Cursor settings.json location:
// macOS: ~/Library/Application Support/Cursor/User/settings.json
// Windows: %APPDATA%\Cursor\User\settings.json
// Linux: ~/.config/Cursor/User/settings.json

{
  "mcp.servers": {
    "my-api-tools": {
      "command": "uvx",
      "args": ["automagik-tools", "mcp", "--spec", "/path/to/spec.json"]
    }
  }
}

Restart Cursor

Close all Cursor windows
Quit Cursor completely (Cmd+Q or Alt+F4)
Restart Cursor
Open Command Palette
Check for MCP tools

VSCode + Cline Issues

Problem: MCP tools not working with Cline extension Solution:

Install MCP Extension

Open VSCode
Extensions → Search "MCP"
Install official MCP extension
Reload VSCode

Configure MCP Servers

// VSCode settings.json
{
  "mcp.servers": {
    "my-api-tools": {
      "command": "uvx",
      "args": ["automagik-tools", "mcp", "--spec", "/path/to/spec.json"]
    }
  }
}

Enable in Cline

Open Cline extension
Settings → MCP Integration
Enable MCP support
Select MCP server

Debugging Connection Issues

Enable Debug Logging

Server-side:

# Run with debug output
uvx automagik-tools mcp --spec spec.json --debug

# Shows:
# - Tool registration
# - Request/response details
# - Error stack traces

Client-side:

# Claude Code
cat ~/.claude/logs/mcp-*.log

# Cursor
# Help → Show Logs → MCP Logs

# VSCode
# Output → MCP Logs

Test with Simple Spec

Problem: Complex spec causing issues Solution:

// Create minimal test spec
{
  "openapi": "3.0.0",
  "info": {
    "title": "Test API",
    "version": "1.0.0"
  },
  "servers": [{
    "url": "https://api.example.com"
  }],
  "paths": {
    "/test": {
      "get": {
        "summary": "Test endpoint",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}

# Test with minimal spec
uvx automagik-tools mcp --spec test-spec.json

# If this works, problem is in your full spec
# Add complexity gradually to find issue

Verify Network Connectivity (SSE Mode)

Problem: Client can’t reach SSE server

# Test server is running
curl http://localhost:8000

# Should return MCP server info

# Test from client machine
curl http://server-ip:8000

# Check firewall
sudo ufw status  # Linux
# Allow port if needed
sudo ufw allow 8000/tcp

# Test with telnet
telnet localhost 8000

Performance Issues

Slow Tool Execution

Problem: MCP tools respond slowly Solutions:

Check API Response Time

# Test API directly
time curl https://api.example.com/endpoint

# If API is slow, not much MCP can do
# Consider caching or pagination

Enable Response Caching

# Cache API responses
uvx automagik-tools mcp --spec spec.json --cache-ttl 300

# TTL in seconds (300 = 5 minutes)
# Subsequent identical requests use cache

Reduce Payload Size

// In OpenAPI spec, limit response fields
{
  "parameters": [{
    "name": "fields",
    "in": "query",
    "schema": {
      "type": "string",
      "default": "id,name,status"
    }
  }]
}

Memory Issues

Problem: MCP server using too much memory Solution:

# Monitor memory usage
ps aux | grep automagik-tools

# Limit response size in OpenAPI spec
{
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "maxItems": 100  // Limit array size
          }
        }
      }
    }
  }
}

# Restart MCP server periodically
# Add to cron job or task scheduler

Next Steps

Common Issues

General troubleshooting guide

OpenAPI Conversion

OpenAPI specification issues

MCP Usage Guide

Learn about MCP integration

FAQ

Frequently asked questions

Phase 1: Get It Running

Phase 2: Reference

Phase 3: Real Examples

Phase 4: Deep Concepts

Troubleshooting

Overview

Connection Issues

MCP Server Not Found

stdio vs SSE Mode Confusion

Port Already in Use (SSE Mode)

Tools Not Appearing in Client

Configuration Issues

Environment Variables Not Loaded

Absolute vs Relative Paths

Working Directory Issues

Authentication Issues

API Authentication Failures

Environment Variable Substitution Not Working

Client-Specific Issues

Claude Code Issues

Cursor Issues

VSCode + Cline Issues

Debugging Connection Issues

Enable Debug Logging

Test with Simple Spec

Verify Network Connectivity (SSE Mode)

Performance Issues

Slow Tool Execution

Memory Issues

Next Steps

Common Issues

OpenAPI Conversion

MCP Usage Guide

FAQ

Phase 1: Get It Running

Phase 2: Reference

Phase 3: Real Examples

Phase 4: Deep Concepts

Troubleshooting

​Overview

​Connection Issues

​MCP Server Not Found

​stdio vs SSE Mode Confusion

​Port Already in Use (SSE Mode)

​Tools Not Appearing in Client

​Configuration Issues

​Environment Variables Not Loaded

​Absolute vs Relative Paths

​Working Directory Issues

​Authentication Issues

​API Authentication Failures

​Environment Variable Substitution Not Working

​Client-Specific Issues

​Claude Code Issues

​Cursor Issues

​VSCode + Cline Issues

​Debugging Connection Issues

​Enable Debug Logging

​Test with Simple Spec

​Verify Network Connectivity (SSE Mode)

​Performance Issues

​Slow Tool Execution

​Memory Issues

​Next Steps

Common Issues

OpenAPI Conversion

MCP Usage Guide

FAQ

Overview

Connection Issues

MCP Server Not Found

stdio vs SSE Mode Confusion

Port Already in Use (SSE Mode)

Tools Not Appearing in Client

Configuration Issues

Environment Variables Not Loaded

Absolute vs Relative Paths

Working Directory Issues

Authentication Issues

API Authentication Failures

Environment Variable Substitution Not Working

Client-Specific Issues

Claude Code Issues

Cursor Issues

VSCode + Cline Issues

Debugging Connection Issues

Enable Debug Logging

Test with Simple Spec

Verify Network Connectivity (SSE Mode)

Performance Issues

Slow Tool Execution

Memory Issues

Next Steps