{
  "markdown": "# swsd-mcp\n\n[![CI](https://github.com/mikimatsub/swsd-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mikimatsub/swsd-mcp/actions/workflows/ci.yml)\n[![Security](https://github.com/mikimatsub/swsd-mcp/actions/workflows/security.yml/badge.svg)](https://github.com/mikimatsub/swsd-mcp/actions/workflows/security.yml)\n[![npm version](https://img.shields.io/npm/v/swsd-mcp.svg)](https://www.npmjs.com/package/swsd-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.mikimatsub%2Fswsd-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.mikimatsub/swsd)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Provenance](https://img.shields.io/badge/Provenance-SLSA-blue.svg)](https://www.npmjs.com/package/swsd-mcp)\n\n**MCP server for SolarWinds Service Desk (SWSD / Samanage).** Works with any [Model Context Protocol](https://modelcontextprotocol.io) client to handle tickets, service requests, knowledge-base work, change/release workflows, assets/CMDB context, procurement records, risks, time entries, and attachments using each user's own SWSD API token. See the [client compatibility matrix](https://mcp-swsd.pages.dev/compatibility/) for the tested list.\n\n📖 **Full docs:** [mcp-swsd.pages.dev](https://mcp-swsd.pages.dev)\n\nThe server holds **zero credentials at rest**. Tokens are forwarded per-request, never persisted, never logged, and only sent to the configured SWSD API host.\n\n---\n\n## Quick start\n\nYou need:\n\n- An MCP client installed: any MCP-compatible client works ([compatibility matrix](https://mcp-swsd.pages.dev/compatibility/))\n- A SolarWinds Service Desk **admin token (JWT)**: generate one in the SWSD UI: **Setup → Users & Groups → Users** → click your user → **Actions** → **Generate JSON Web Token** (Service Desk administrator rights required)\n\n### VS Code\n\n1. Open the Command Palette: **Ctrl+Shift+P** on Windows/Linux or **Shift+Command+P** on macOS.\n2. Run **MCP: Add Server...**.\n\n<img src=\"./docs-site/public/vscode/vscode-command-palette-add-server.png\" alt=\"MCP: Add Server in the VS Code Command Palette\" width=\"600\">\n\n3. Install with either supported local option:\n\n   - **Command (stdio)**: enter `npx -y swsd-mcp`.\n   - **NPM Package**: enter `swsd-mcp`, confirm that the publisher is **`mikimatsub`**, then select **Allow**.\n\n<img src=\"./docs-site/public/vscode/vscode-stdio-command.png\" alt=\"The swsd-mcp stdio command entered in VS Code\" width=\"600\">\n\n4. Name the server `swsd`, then choose **Global** for your VS Code profile or **Workspace** for the current project.\n5. [Add the SWSD token securely and verify the connection](https://mcp-swsd.pages.dev/quickstart/#secure-vs-code-token-configuration).\n\n### Other stdio clients\n\n### 1. Add the config\n\nThe non-VS-Code clients listed below use this common JSON shape. Add it under `mcpServers` in your client's config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"swsd\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"swsd-mcp\"],\n      \"env\": {\n        \"SWSD_TOKEN\": \"your-jwt-here\",\n        \"SWSD_BASE_URL\": \"https://api.samanage.com\"\n      }\n    }\n  }\n}\n```\n\nReplace `your-jwt-here` with your token. EU tenants use `https://apieu.samanage.com` instead. To customize behavior, add any [configuration variable](https://mcp-swsd.pages.dev/configuration/) (most common: `SWSD_PROFILE` to choose the tool set) into the same `env` block.\n\n### 2. Drop it in the right file\n\n| Client | Config file path |\n|---|---|\n| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop (Windows) | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |\n| Claude Code | `~/.claude.json` (or use the shortcut below) |\n| Cursor | `~/.cursor/mcp.json` |\n| Continue, Cline, other clients | check your client's docs: same JSON shape |\n\nCreate the file if it doesn't exist. Then restart your client.\n\n**Claude Code shortcut**: skip editing the file by hand. This single line pastes verbatim into any shell (bash, zsh, PowerShell, cmd):\n\n```bash\nclaude mcp add swsd --env SWSD_TOKEN=\"your-jwt-here\" --env SWSD_BASE_URL=\"https://api.samanage.com\" -- npx -y swsd-mcp\n```\n\n**Microsoft Copilot Studio**: different path. Copilot Studio can't spawn local processes, so it needs an HTTP-transport server. See [`copilot-studio/README.md`](./copilot-studio/README.md) and the [Azure Container Apps recipe](./docs/deployment/azure-container-apps.md).\n\n### 3. Verify it works\n\nIn your MCP client, ask:\n\n> _\"Use swsd to check if you can connect.\"_\n\nThe agent should call `swsd_health_check` and report success. If it does, you're set up. Try a few more:\n\n- _\"Show me incident 60310\"_: id-keyed tools accept either the internal id (≥7 digits) or the human-facing number visible in the SWSD UI (≤6 digits).\n- _\"List incidents updated in the last 7 days\"_: `updated_within: \"7d\"` (also `\"24h\"`, `\"1w\"`, `\"30d\"`).\n- _\"What tickets are assigned to me?\"_: `swsd_list_my_incidents` calls `swsd_get_me` internally, so you don't have to spell out an email.\n\n---\n\n## Tools (66 across 15 categories)\n\n| Category | Tools |\n|---|---|\n| **Utility** | `swsd_get_server_info`, `swsd_health_check`, `swsd_get_me` |\n| **Incidents** | `swsd_list_incidents`, `swsd_list_my_incidents`, `swsd_get_incident`, `swsd_create_incident`, `swsd_update_incident`, `swsd_assign_incident`, `swsd_update_incident_state`, `swsd_link_solution_to_incident` |\n| **Comments** | `swsd_list_incident_comments`, `swsd_add_incident_comment`, `swsd_update_comment` |\n| **Tasks** | `swsd_list_incident_tasks`, `swsd_create_incident_task`, `swsd_update_task_state` |\n| **Problems** | `swsd_list_problems`, `swsd_get_problem`, `swsd_create_problem` |\n| **Change & Release** | `swsd_list_changes`, `swsd_get_change`, `swsd_create_change`, `swsd_update_change`, `swsd_list_releases`, `swsd_get_release`, `swsd_create_release`, `swsd_update_release` |\n| **Assets & CMDB** | `swsd_list_hardware_assets`, `swsd_get_hardware_asset`, `swsd_list_mobile_devices`, `swsd_get_mobile_device`, `swsd_list_printers`, `swsd_get_printer`, `swsd_list_software_assets`, `swsd_get_software_asset`, `swsd_list_other_assets`, `swsd_get_other_asset`, `swsd_list_configuration_items`, `swsd_get_configuration_item` |\n| **Procurement & Risk** | `swsd_list_contracts`, `swsd_get_contract`, `swsd_list_purchase_orders`, `swsd_get_purchase_order`, `swsd_list_vendors`, `swsd_get_vendor`, `swsd_list_risks` |\n| **Time tracking** | `swsd_list_time_tracks`, `swsd_log_time`, `swsd_update_time_track` |\n| **Attachments** | `swsd_upload_attachment` |\n| **Solutions / KB** | `swsd_search_solutions`, `swsd_get_solution`, `swsd_create_solution`, `swsd_update_solution` |\n| **Service Catalog** | `swsd_list_catalog_items`, `swsd_get_catalog_item`, `swsd_create_service_request` |\n| **Lookups** | `swsd_list_categories`, `swsd_list_sites`, `swsd_list_departments`, `swsd_list_users`, `swsd_list_groups`, `swsd_list_roles` |\n| **Custom fields** | `swsd_describe_custom_fields` |\n| **Audits** | `swsd_get_record_audits` |\n\nEach tool's input schema, description, and output shape is auto-discovered by your MCP client at runtime. See the [Tools reference](https://mcp-swsd.pages.dev/tools/) for full per-tool documentation.\n\n---\n\n## MCP Apps widgets (rich UI)\n\nSeven read tools ship interactive UI bundles using the [MCP Apps capability](https://modelcontextprotocol.io/specification/2025-11-25). On capable hosts (Claude Desktop, Claude Web, VS Code Copilot Chat, ChatGPT, Goose, Postman), the tool returns a rendered widget alongside the structured response. On text-only hosts (Claude Code, LM Studio), the same tools return their normal structured payload.\n\n![incident-list widget rendering a sortable table of synthetic Acme Corp tickets](docs-site/public/widgets/incident-list-dark.png)\n\n*Example: `swsd_list_incidents` rendering the `incident-list` widget. Synthetic data; no real tenant info. See the [full gallery](https://mcp-swsd.pages.dev/widgets/) for screenshots of all seven widgets.*\n\n| Tool | Widget | What it renders |\n|---|---|---|\n| `swsd_get_incident` | `incident-detail` | Single-record card (description, due date, SLA, resolution, custom fields) |\n| `swsd_get_solution` | `solution-detail` | Knowledge-base article with sanitized HTML body |\n| `swsd_list_incidents`, `swsd_list_my_incidents` | `incident-list` | Filterable, sortable table |\n| `swsd_list_incident_comments` | `comment-thread` | Vertical conversation with author chips, public/private badges |\n| `swsd_get_record_audits` | `audit-timeline` | Timeline grouped by day with action chips and field diffs |\n| `swsd_get_catalog_item` | `catalog-item-form` | Form that submits via `swsd_create_service_request` |\n| `swsd_describe_custom_fields` | `custom-fields` | Searchable explorer with scope/module filters |\n\nSee the [Widgets reference](https://mcp-swsd.pages.dev/widgets/) for screenshots and per-widget detail.\n\n---\n\n## Configuration\n\nMost users only need `SWSD_TOKEN` and `SWSD_BASE_URL`:\n\n| Variable | Default | Notes |\n|---|---|---|\n| `SWSD_TOKEN` | None | Required. Your SWSD admin token (JWT). |\n| `SWSD_BASE_URL` | `https://api.samanage.com` | EU tenant: `https://apieu.samanage.com` |\n| `SWSD_PROFILE` | `agent` | `triage`, `agent`, `knowledge`, `operations`, or `full`: see [Profiles](https://mcp-swsd.pages.dev/configuration/#profiles) |\n| `SWSD_WRITE_MODE` | `live` | `live`, `dry-run`, or `disabled`: preview or block write tools without changing profiles |\n| `SWSD_ATTACHMENT_ROOT` | None | Optional real-path boundary for local `file_path` uploads in stdio mode |\n\nFor the full env-var reference (HTTP transport, retries, rate limits, allowlists), see [Configuration](https://mcp-swsd.pages.dev/configuration/).\n\n---\n\n## Profiles\n\nProfiles control which tools are registered at startup. Cannot be changed mid-session.\n\n| Profile | Intent | Tool count |\n|---|---|---|\n| `triage` | Read-heavy first-line support + commenting | 14 |\n| `agent` | Full ticket-handler workflow (default) | 37 |\n| `knowledge` | KB-author workflow + incident reads | 15 |\n| `operations` | Agent workflow plus change/release, ITAM, CMDB, procurement, and risk context | 64 |\n| `full` | Every tool | 66 |\n\nUse `SWSD_ENABLE_EXTRAS=swsd_foo,swsd_bar` to add specific tools on top of a profile.\n\n---\n\n## Hosting an HTTP server (advanced)\n\nQuick Start above runs swsd-mcp on your own machine: your MCP client spawns it on demand via `npx`. **Most users stop there.**\n\nSet up an HTTP-mode server only if you need:\n\n- **Microsoft Copilot Studio integration**: Copilot Studio can't spawn local processes\n- **One shared instance for a team**: one deploy, many users, each providing their own token per-request\n- **Stricter network control**: private VNet, IP allowlist, custom domain\n\nThe Docker image runs anywhere: Azure, AWS, GCP, Render, Fly.io, your own VM. See [Deployment](https://mcp-swsd.pages.dev/deployment/) for the full guide and the [Azure Container Apps recipe](./docs/deployment/azure-container-apps.md) (recommended for Copilot Studio; scale-to-zero pricing).\n\n---\n\n## Documentation\n\n- [`SECURITY.md`](./SECURITY.md): vulnerability reporting via GitHub Security Advisories\n- [`docs/SECURITY-POSTURE.md`](./docs/SECURITY-POSTURE.md): security controls, supply-chain hardening, verification methods\n- [`CONTRIBUTING.md`](./CONTRIBUTING.md): bug reports, PR review criteria, local development setup\n- [`CHANGELOG.md`](./CHANGELOG.md): version history\n- [`copilot-studio/`](./copilot-studio/): Microsoft Copilot Studio Swagger connector specs and import guide\n- [`docs/deployment/`](./docs/deployment/): cloud deployment recipes\n\n---\n\n## License\n\nMIT: see [LICENSE](./LICENSE). Provided \"as is\" without warranty.\n\n## Trademarks\n\nSolarWinds, Samanage, and Service Desk are trademarks of SolarWinds Worldwide, LLC. This project is not affiliated with, endorsed by, or sponsored by SolarWinds. It wraps the publicly documented SWSD REST API.\n",
  "bytes": 11990,
  "sha": "3bb4b8f7e96048fa293bfb310fb0f731a708811d64814495daf63f73bcb22d5b",
  "repo_slug": "mikimatsub/swsd-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mikimatsub_swsd_62fd33e8/readme"
}