Skip to main content

Windsurf Setup

Prerequisites​

  • Windsurf IDE
  • Unizo API key and SCM integration ID
  • Node.js v20 or higher

Setup Instructions​

  1. Install @mcp-remote if not already installed:

    npm i mcp-remote

  2. Locate Windsurf's MCP configuration:

    • macOS/Linux: ~/.windsurf/mcp_settings.json
    • Windows: %USERPROFILE%\.windsurf\mcp_settings.json

  3. Add Unizo SCM configuration:

{
  "mcpServers": {
    "unizo": {
      "command": "/Users/{user_name}/.nvm/versions/node/v18.x.x/bin/node",
      "args": [
        "/Users/{user_name}/.nvm/versions/node/v18.x.x/bin/mcp-remote",
        "https://api.unizo.ai/mcp",
        "--header",
        "apikey:${UNIZO_API_KEY}",
        "--header",
        "x-mcp-scopes:ticketing"
      ],
      "env": {
        "UNIZO_API_KEY": "your_api_key"
      }
    }
  }
}
  1. Restart Windsurf to load the MCP server

Flags: If npx is producing errors, consider adding -y as the first argument to auto-accept the installation of the mcp-remote package.

{
  "mcpServers": {
    "unizo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.unizo.ai/mcp",
        "--header",
        "apikey:${UNIZO_API_KEY}",
        "--header",
        "x-mcp-scopes:ticketing"
      ],
      "env": {
        "UNIZO_API_KEY": "your_api_key"
      }
    }
  }
}

Available Tools​

Once configured, you'll have access to:

  • scm_list_integrations - Get integrations for a specific SCM service
  • scm_list_organizations - Browse SCM organizations with pagination
  • scm_get_organization - Retrieve detailed organization information
  • scm_list_repositories - Browse repositories within an organization
  • scm_get_repository - Retrieve detailed repository information
  • scm_list_branches - Browse branches within a repository
  • scm_get_branch - Retrieve detailed branch information
  • scm_list_commits - Browse commit history with pagination
  • scm_get_commit - Retrieve detailed commit information
  • scm_list_pull_requests - Browse pull requests with pagination
  • scm_get_pull_request - Retrieve detailed pull request information
  • scm_create_pull_request - Create a new pull request
  • scm_update_pull_request - Update an existing pull request

Cascade AI Integration​

Enable Cascade AI to use MCP tools:

{
  "cascade.mcp.enabled": true,
  "cascade.mcp.autoConnect": true
}

Multiple Integrations​

To work with multiple categories or integrations, add them as a comma-separated list under the x-mcp-scopes header:

{
  "mcpServers": {
    "unizo": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.unizo.ai/mcp",
        "--header",
        "apikey:${UNIZO_API_KEY}",
        "--header",
        "x-mcp-scopes : scm,incident,ticketing"
      ],
      "env": {
        "UNIZO_API_KEY": "your_api_key"
      }
    }
  }
}

Troubleshooting​

MCP not detected​

  • Check Windsurf logs: View → Output → MCP
  • Ensure Node.js v20+ is installed

Authentication errors​

  • Verify your API key in Unizo dashboard
  • Check that the integration ID is correct
  • Ensure the integration is active

Debug mode​

Enable debug logging in settings.json:

{
  "args": [
  "--debug"
]
}