arcade-mcp/libs/arcade-mcp-server/docs/clients/cursor.md

Cursor IDE

Cursor is an AI-powered IDE that supports MCP servers. This guide will help you integrate your Arcade MCP server with Cursor for enhanced development capabilities.

Prerequisites

• Cursor IDE installed
• Python 3.10+ installed
• arcade-ai package installed (pip install arcade-ai)

Configuration

Cursor reads MCP server configurations from its settings. You can configure MCP servers through:

1. Cursor Settings UI
2. Configuration file
3. Workspace settings

Basic Setup

Method 1: Settings UI

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP" or "Model Context Protocol"
3. Add a new server configuration:
   • Name: arcade-tools
   • Command: python -m arcade_mcp stdio
   • Working Directory: /path/to/your/project

Method 2: Configuration File

Add to your Cursor configuration:

{
  "mcp.servers": {
    "arcade-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}

Method 3: Workspace Settings

Create .cursor/settings.json in your workspace:

{
  "mcp.servers": {
    "project-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--debug"],
      "cwd": "${workspaceFolder}",
      "env": {
        "ARCADE_API_KEY": "${env:ARCADE_API_KEY}"
      }
    }
  }
}

Development Workflow

Hot Reload Setup

For active development with automatic reload:

{
  "mcp.servers": {
    "dev-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "--reload", "--debug"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}

Virtual Environment

Use a project-specific virtual environment:

{
  "mcp.servers": {
    "project-tools": {
      "command": "${workspaceFolder}/venv/bin/python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Multiple Tool Sets

Configure different tool sets for different purposes:

{
  "mcp.servers": {
    "github-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--tool-package", "github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    },
    "database-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "${workspaceFolder}/db_tools",
      "env": {
        "DATABASE_URL": "${env:DATABASE_URL}"
      }
    },
    "api-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "${workspaceFolder}/api_tools"
    }
  }
}

Integration Features

Inline Tool Usage

Use tools directly in your code comments:

# @mcp use arcade-tools.greet name="World"
# Result will appear here

def process_data(data):
    # @mcp use database-tools.query sql="SELECT * FROM users"
    pass

Tool Discovery

View available tools in Cursor:

1. Open Command Palette (Cmd/Ctrl + Shift + P)
2. Type "MCP: List Tools"
3. Select your server to see available tools

Tool Documentation

Access tool documentation:

1. Hover over tool usage in code
2. Use Cmd/Ctrl + Click on tool names
3. View in the MCP panel

Advanced Configuration

Environment-Specific Settings

Use different configurations per environment:

{
  "mcp.servers": {
    "tools-dev": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--env-file", ".env.dev"],
      "cwd": "${workspaceFolder}",
      "when": "${config:environment} == 'development'"
    },
    "tools-prod": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--env-file", ".env.prod"],
      "cwd": "${workspaceFolder}",
      "when": "${config:environment} == 'production'"
    }
  }
}

Task Integration

Create tasks for MCP server management:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MCP Server",
      "type": "shell",
      "command": "python -m arcade_mcp --reload --debug",
      "problemMatcher": [],
      "isBackground": true
    },
    {
      "label": "Test Tools",
      "type": "shell",
      "command": "python -m arcade_mcp --tool-package ${input:package} --debug",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "package",
      "type": "promptString",
      "description": "Tool package name"
    }
  ]
}

Debugging Tools

Debug your tools with Cursor's debugger:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug MCP Tools",
      "type": "python",
      "request": "launch",
      "module": "arcade_mcp",
      "args": ["--debug", "--reload"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}

Best Practices

Project Structure

Organize your MCP tools effectively:

my-project/
 .cursor/
    settings.json    # Cursor-specific settings
 .env                 # Environment variables
 .env.example         # Example environment file
 tools/
    __init__.py
    data_tools.py    # Data processing tools
    api_tools.py     # API interaction tools
    utils.py         # Utility tools
 requirements.txt
 README.md

Tool Development Tips

1. Use Type Hints: Enable better IDE support

   from typing import Annotated
   
   @tool
   def process(
       data: Annotated[str, "Input data to process"],
       format: Annotated[str, "Output format"] = "json"
   ) -> Annotated[dict, "Processed data"]:
       """Process data in the specified format."""
       pass
   

2. Provide Clear Descriptions: Help Cursor understand tool usage

3. Handle Errors Gracefully: Return helpful error messages

4. Use Logging: Enable debug mode for troubleshooting

5. Test Incrementally: Use Cursor's integrated terminal

Performance Optimization

1. Lazy Loading: Import heavy dependencies inside tools
2. Cache Results: Use caching for expensive operations
3. Async Support: Use async tools for I/O operations
4. Resource Management: Clean up resources properly

Troubleshooting

Common Issues

Tools Not Loading

1. Check Python path and virtual environment
2. Verify arcade-ai installation
3. Enable debug logging to see errors
4. Check for import errors in tool files

Permission Errors

1. Ensure proper file permissions
2. Check working directory access
3. Verify environment variable access

Connection Issues

1. Restart Cursor after configuration changes
2. Check for conflicting MCP servers
3. Verify stdio transport is working

Debugging Steps

1. Enable debug mode in your configuration
2. Check Cursor's output panel for MCP logs
3. Test tools using the command line first
4. Use Cursor's Developer Tools for detailed logs

Example: Complete Setup

Here's a full example of setting up a Cursor workspace with MCP:

1. Create workspace structure:

   my-workspace/
    .cursor/
       settings.json
    .vscode/
       tasks.json
    tools/
       my_tools.py
    pyproject.toml
   

2. Configure .cursor/settings.json:

   {
     "mcp.servers": {
       "workspace-tools": {
         "command": "python",
         "args": ["-m", "arcade_mcp", "stdio", "--debug"],
         "cwd": "${workspaceFolder}",
         "env": {
           "PYTHONPATH": "${workspaceFolder}"
         }
       }
     }
   }
   

3. Create tools/my_tools.py:

   from arcade_tdk import tool
   from typing import Annotated
   import json
   
   @tool
   async def format_json(
       data: Annotated[str, "JSON string to format"]
   ) -> Annotated[str, "Formatted JSON"]:
       """Format JSON data with proper indentation."""
       parsed = json.loads(data)
       return json.dumps(parsed, indent=2)
   
   @tool
   def analyze_code(
       file_path: Annotated[str, "Path to analyze"]
   ) -> Annotated[dict, "Analysis results"]:
       """Analyze Python code quality."""
       # Implementation here
       pass
   

4. Restart Cursor and start using your tools!