Quick start

This guide gets swsd-mcp running locally via npx. For Microsoft Copilot Studio, see Deployment → Copilot Studio — it uses HTTP transport, which is a different setup.

What you need

• An MCP client installed — any MCP-compatible client works (client compatibility matrix)
• Node.js 24.15.0 or newer (for npx; current LTS line, matches package.json engines)
• A SolarWinds Service Desk admin token — see below

Generate an SWSD admin token

In the SWSD web UI, navigate:

1. Setup → Users & Groups → Users
2. Click your user to open the detail page
3. Click Actions → Generate JSON Web Token
4. Copy the token (it’s a long JWT string)

Service Desk administrator rights required

Only users with a Service Desk administrator license can generate tokens. If you don’t have admin rights, your administrator needs to generate one for you. The token inherits your permissions — when your role changes, the token’s permissions change with it.

Install in VS Code

1. Open the Command Palette with Ctrl+Shift+P on Windows/Linux or Shift+Command+P on macOS.
2. Run MCP: Add Server….

Choose one of these four routes.

Command (stdio)

This is the recommended local install.

1. Select Command (stdio).

2. Enter npx -y swsd-mcp.

   

3. Enter swsd as the server name.

4. Choose Global to use it throughout the current VS Code profile, or Workspace to add it to the current project’s .vscode/mcp.json.

5. Apply the secure token configuration below.

NPM Package

1. Select NPM Package.
2. Enter swsd-mcp.
3. Check the confirmation carefully: the package must be swsd-mcp and the publisher must be mikimatsub. Select Allow only when both match.
4. Follow the prompts, choose Global or Workspace, and review the generated configuration before starting the server.
5. Make sure the token is handled as a password input, as shown below, rather than stored directly in JSON.

HTTP

Use this only for an swsd-mcp instance that has already been deployed with HTTP transport. Select HTTP (HTTP or Server-Sent Events) and enter its full MCP endpoint, including /mcp, such as https://swsd-mcp.example.com/mcp. Do not enter this documentation site, the GitHub repository, the npm page, or the deployment’s /healthz URL.

After choosing a name and scope, add the per-user token as an authorization header:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "swsd-token",
      "description": "SolarWinds Service Desk admin JWT",
      "password": true
    }
  ],
  "servers": {
    "swsd": {
      "type": "http",
      "url": "https://swsd-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:swsd-token}"
      }
    }
  }
}

The deployment supplies SWSD_BASE_URL, SWSD_PROFILE, and the other server-side settings. See Deployment for the HTTP setup.

Add from another application

Select Add from another application… to open the chat.mcp.discovery.enabled setting. Enable the source that already contains your working swsd server:

• Claude Desktop
• Windsurf
• Cursor global configuration
• Cursor workspace configuration

VS Code then discovers and reuses MCP server configurations from the selected source. Discovery is off by default. Review the discovered server before starting it, especially if the original configuration contains a token directly.

Secure VS Code token configuration

For a Global install, run MCP: Open User Configuration. For a Workspace install, open .vscode/mcp.json. Replace the generated swsd entry with this configuration so VS Code requests the JWT as a password input instead of storing it in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "swsd-token",
      "description": "SolarWinds Service Desk admin JWT",
      "password": true
    }
  ],
  "servers": {
    "swsd": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "swsd-mcp"],
      "env": {
        "SWSD_TOKEN": "${input:swsd-token}",
        "SWSD_BASE_URL": "https://api.samanage.com"
      }
    }
  }
}

EU tenants should use https://apieu.samanage.com for SWSD_BASE_URL. A Workspace file containing this placeholder is safe to commit because the JWT itself is not in the JSON.

Other MCP clients

Add the MCP config

The clients listed below use this common JSON shape. Add it under mcpServers in your client’s config file:

{
  "mcpServers": {
    "swsd": {
      "command": "npx",
      "args": ["-y", "swsd-mcp"],
      "env": {
        "SWSD_TOKEN": "your-jwt-here",
        "SWSD_BASE_URL": "https://api.samanage.com"
      }
    }
  }
}

Replace your-jwt-here with the token from the previous step. EU tenants use https://apieu.samanage.com instead.

Customize behavior

Any variable from the Configuration page goes into this same env block. The most common one to add is SWSD_PROFILE to switch from the default agent profile (37 tools) to triage (14), knowledge (15), operations (64), or full (66):

"env": {
  "SWSD_TOKEN": "your-jwt-here",
  "SWSD_BASE_URL": "https://api.samanage.com",
  "SWSD_PROFILE": "full"
}

When testing write-heavy workflows, add SWSD_WRITE_MODE: "dry-run" to preview create/update payloads without sending write requests to SWSD. Set it to disabled when a deployment should remain read-only even if a write tool is present in the profile.

Find the right config file

Client	Config file path
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop (Linux)	~/.config/Claude/claude_desktop_config.json
Claude Code	~/.claude.json (or use the shortcut below)
Cursor	~/.cursor/mcp.json
Continue, Cline, other clients	check your client’s docs — same JSON shape

Create the file if it doesn’t exist. Then restart your client so it picks up the new server.

Claude Code shortcut

Skip editing the file manually. This single line pastes verbatim into any shell (bash, zsh, PowerShell, cmd):

claude mcp add swsd --env SWSD_TOKEN="your-jwt-here" --env SWSD_BASE_URL="https://api.samanage.com" -- npx -y swsd-mcp

This writes the same config block as above to ~/.claude.json.

Verify it works

In your MCP client, ask the agent:

“Use swsd to check if you can connect.”

The agent should call the swsd_health_check tool and report success. Once you see that, you’re set up.

If something doesn’t work, see Configuration for the full env-var reference and common troubleshooting.

What you can do now

Try asking the agent things like:

• “What tickets are assigned to me?” → calls swsd_get_me + swsd_list_my_incidents (the agent identifies you from the JWT, no manual email entry; renders the incident-list widget in MCP Apps-capable hosts)
• “Show me incident 60310 with comments and audit trail.” → calls swsd_get_incident + swsd_list_incident_comments + swsd_get_record_audits. Id-keyed tools accept either the internal id or the human-facing number visible in the SWSD UI.
• “List incidents updated in the last 7 days.” → uses swsd_list_incidents with updated_within: "7d" (also "24h", "1w", "30d").
• “What’s blocking ticket 60310?” → calls swsd_list_incident_tasks (sub-tasks new in v2.1).
• “Search the knowledge base for ‘VPN troubleshooting’.” → calls swsd_search_solutions.
• “What services can I request through the catalog?” → calls swsd_list_catalog_items.
• “Submit a Software Request for Adobe Acrobat Pro.” → calls swsd_get_catalog_item to read the form schema; in MCP Apps-capable hosts the catalog-item-form widget submits via swsd_create_service_request directly.
• “What custom fields are available on incidents?” → calls swsd_describe_custom_fields (with a searchable explorer UI in capable hosts).
• “Show changes planned this week and the affected configuration items.” → use the operations profile to expose change/release plus CMDB tools.
• “Preview creating a change for the weekend firewall update without writing it.” → set SWSD_WRITE_MODE=dry-run, then call swsd_create_change to inspect the payload.

The full tool catalog is in Tools reference.

Next steps

• Tighten or expand the tool set — see Configuration to switch from the default agent profile to triage (read-heavy), knowledge (KB authoring), operations, or full
• Hosting for a team — see Deployment for the HTTP-transport setup
• Microsoft Copilot Studio integration — see Deployment → Microsoft Copilot Studio