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

Visual Studio Code

While VSCode doesn't have native MCP support yet, you can integrate Arcade MCP servers with VSCode through extensions and custom configurations. This guide shows various integration approaches.

Prerequisites

• Visual Studio Code installed
• Python 3.10+ installed
• arcade-mcp package installed (pip install arcade-mcp)
• Python extension for VSCode

Integration Methods

Method 1: Terminal Integration

Use VSCode's integrated terminal to run MCP servers:

1. Open integrated terminal (Ctrl/Cmd + `)
2. Start your MCP server:

   python -m arcade_mcp_server --reload --debug
   

3. Use split terminals for multiple servers

Method 2: Task Runner

Create tasks to manage MCP servers:

Create .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MCP Server",
      "type": "shell",
      "command": "python",
      "args": ["-m", "arcade_mcp_server", "--reload", "--debug"],
      "isBackground": true,
      "problemMatcher": {
        "pattern": {
          "regexp": "^(ERROR|WARNING):\\s+(.+)$",
          "severity": 1,
          "message": 2
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "^Starting.*",
          "endsPattern": "^.*Server ready.*"
        }
      },
      "presentation": {
        "reveal": "always",
        "panel": "dedicated"
      }
    },
    {
      "label": "Start MCP (HTTP)",
      "type": "shell",
      "command": "python",
      "args": [
        "-m", "arcade_mcp_server",
        "--host", "0.0.0.0",
        "--port", "8000",
        "--reload"
      ],
      "isBackground": true,
      "problemMatcher": []
    },
    {
      "label": "Test Tools",
      "type": "shell",
      "command": "python",
      "args": ["${workspaceFolder}/test_tools.py"],
      "problemMatcher": "$python"
    }
  ]
}

Run tasks via:

• Command Palette: Tasks: Run Task
• Terminal menu: Terminal > Run Task

Method 3: Launch Configurations

Debug your MCP tools with VSCode's debugger:

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug MCP Server",
      "type": "python",
      "request": "launch",
      "module": "arcade_mcp_server",
      "args": ["--debug", "--reload"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "ARCADE_API_KEY": "${env:ARCADE_API_KEY}"
      },
      "console": "integratedTerminal"
    },
    {
      "name": "Debug Specific Tool",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/tools/my_tool.py",
      "args": ["--test"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    },
    {
      "name": "Debug with Package",
      "type": "python",
      "request": "launch",
      "module": "arcade_mcp_server",
      "args": [
        "--tool-package", "github",
        "--debug"
      ],
      "env": {
        "GITHUB_TOKEN": "${input:githubToken}"
      }
    }
  ],
  "inputs": [
    {
      "id": "githubToken",
      "type": "promptString",
      "description": "Enter your GitHub token",
      "password": true
    }
  ]
}

Development Workflow

Project Setup

Recommended project structure:

my-mcp-project/
├── .vscode/
│   ├── launch.json      # Debug configurations
│   ├── tasks.json       # Task definitions
│   ├── settings.json    # Workspace settings
│   └── extensions.json  # Recommended extensions
├── .env                 # Environment variables
├── .env.example
├── tools/
│   ├── __init__.py
│   └── my_tools.py
├── tests/
│   └── test_tools.py
├── requirements.txt
└── pyproject.toml

Workspace Settings

Configure .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.formatting.provider": "black",
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"],
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true
  },
  "terminal.integrated.env.linux": {
    "PYTHONPATH": "${workspaceFolder}"
  },
  "terminal.integrated.env.osx": {
    "PYTHONPATH": "${workspaceFolder}"
  },
  "terminal.integrated.env.windows": {
    "PYTHONPATH": "${workspaceFolder}"
  }
}

Recommended Extensions

Create .vscode/extensions.json:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-vscode.live-server",
    "humao.rest-client",
    "redhat.vscode-yaml",
    "ms-azuretools.vscode-docker"
  ]
}

Testing Tools

REST Client Extension

Test HTTP MCP servers using REST Client:

Create test-mcp.http:

### Get Server Info
GET http://localhost:8000/health

### List Tools
POST http://localhost:8000/catalog
Content-Type: application/json
Authorization: Bearer {{$env ARCADE_API_KEY}}

{}

### Call Tool
POST http://localhost:8000/call_tool
Content-Type: application/json
Authorization: Bearer {{$env ARCADE_API_KEY}}

{
  "tool_name": "greet",
  "tool_arguments": {
    "name": "World"
  }
}

Python Test Scripts

Create test scripts for your tools:

# test_tools.py
import asyncio
from arcade_core.catalog import ToolCatalog

async def test_tools():
    # Import your tools
    from tools import my_tools

    # Create catalog
    catalog = ToolCatalog()
    catalog.add_tool(my_tools.greet, "test")

    # Test tool
    result = await catalog.call_tool(
        "test.greet",
        {"name": "Test"}
    )
    print(f"Result: {result}")

if __name__ == "__main__":
    asyncio.run(test_tools())

Debugging Tips

Breakpoint Debugging

1. Set breakpoints in your tool code
2. Launch debugger with "Debug MCP Server"
3. Trigger tool execution
4. Step through code execution

Logging Configuration

Enhanced logging for debugging:

# tools/__init__.py
import logging
from loguru import logger

# Configure loguru
logger.add(
    "debug.log",
    rotation="10 MB",
    level="DEBUG",
    format="{time} {level} {message}"
)

# Intercept standard logging
class InterceptHandler(logging.Handler):
    def emit(self, record):
        logger_opt = logger.opt(depth=6, exception=record.exc_info)
        logger_opt.log(record.levelname, record.getMessage())

logging.basicConfig(handlers=[InterceptHandler()], level=0)

Performance Profiling

Profile your tools:

{
  "name": "Profile MCP Server",
  "type": "python",
  "request": "launch",
  "module": "cProfile",
  "args": [
    "-o", "profile.stats",
    "-m", "arcade_mcp_server",
    "--debug"
  ],
  "cwd": "${workspaceFolder}"
}

Snippets

Create useful code snippets in .vscode/python.code-snippets:

{
  "Arcade Tool": {
    "prefix": "atool",
    "body": [
      "from arcade_tdk import tool",
      "from typing import Annotated",
      "",
      "@tool",
      "def ${1:tool_name}(",
      "    ${2:param}: Annotated[${3:str}, \"${4:Parameter description}\"]",
      ") -> Annotated[${5:str}, \"${6:Return description}\"]:",
      "    \"\"\"${7:Tool description}.\"\"\"",
      "    ${8:# Implementation}",
      "    return ${9:result}"
    ],
    "description": "Create an Arcade tool"
  },
  "Async Tool": {
    "prefix": "atoolasync",
    "body": [
      "from arcade_tdk import tool",
      "from typing import Annotated",
      "",
      "@tool",
      "async def ${1:tool_name}(",
      "    ${2:param}: Annotated[${3:str}, \"${4:Parameter description}\"]",
      ") -> Annotated[${5:str}, \"${6:Return description}\"]:",
      "    \"\"\"${7:Tool description}.\"\"\"",
      "    ${8:# Async implementation}",
      "    return ${9:result}"
    ],
    "description": "Create an async Arcade tool"
  }
}

Integration Examples

Multi-Server Setup

Run multiple MCP servers for different purposes:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start All Servers",
      "dependsOn": [
        "Start API Tools",
        "Start Data Tools",
        "Start Utility Tools"
      ],
      "problemMatcher": []
    },
    {
      "label": "Start API Tools",
      "type": "shell",
      "command": "python -m arcade_mcp_server --port 8001",
      "options": {
        "cwd": "${workspaceFolder}/api_tools"
      },
      "isBackground": true
    },
    {
      "label": "Start Data Tools",
      "type": "shell",
      "command": "python -m arcade_mcp_server --port 8002",
      "options": {
        "cwd": "${workspaceFolder}/data_tools"
      },
      "isBackground": true
    },
    {
      "label": "Start Utility Tools",
      "type": "shell",
      "command": "python -m arcade_mcp_server --port 8003",
      "options": {
        "cwd": "${workspaceFolder}/util_tools"
      },
      "isBackground": true
    }
  ]
}

Environment Management

Handle multiple environments:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "MCP Server (Dev)",
      "type": "shell",
      "command": "python -m arcade_mcp_server --env-file .env.dev",
      "problemMatcher": []
    },
    {
      "label": "MCP Server (Staging)",
      "type": "shell",
      "command": "python -m arcade_mcp_server --env-file .env.staging",
      "problemMatcher": []
    },
    {
      "label": "MCP Server (Prod)",
      "type": "shell",
      "command": "python -m arcade_mcp_server --env-file .env.prod",
      "problemMatcher": [],
      "presentation": {
        "reveal": "always",
        "panel": "dedicated",
        "showReuseMessage": true,
        "clear": true
      }
    }
  ]
}

Best Practices

1. Use Virtual Environments: Always work in isolated environments
2. Version Control Settings: Include .vscode in your repository
3. Environment Files: Use .env files for secrets
4. Consistent Formatting: Configure formatters and linters
5. Test Automation: Set up test tasks and debug configs
6. Documentation: Keep README and docstrings updated
7. Git Hooks: Use pre-commit for code quality

Troubleshooting

Common Issues

1. Python interpreter not found:

   • Select interpreter: Cmd/Ctrl + Shift + P > "Python: Select Interpreter"
   • Ensure virtual environment is activated

2. Module import errors:

   • Check PYTHONPATH in settings
   • Verify package installation
   • Restart VSCode

3. Debug breakpoints not working:

   • Ensure you're using the debug configuration
   • Check that debugpy is installed
   • Verify source maps are correct

4. Task execution fails:

   • Check task definition syntax
   • Verify working directory
   • Review terminal output for errors