> For the complete documentation index, see [llms.txt](https://skyforgeai.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://skyforgeai.gitbook.io/docs/extend/claude-desktop.md). # SkyForge in Claude Desktop Use SkyForge's ServiceNow expertise and tooling directly inside Claude Desktop chat. Two pieces are involved, and you need both: | Piece | What it gives Claude | How it gets there | | ----------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------ | | **SkyForge skill** | The instructions — scope handling, Update Set workflow, build patterns, review protocol | Uploaded as a Claude Skill (`.zip`) | | **SkyForge MCP server** | The tools — `tool_search`, `tool_execute`, `sn_load_skill` and every ServiceNow tool behind them | Registered in `claude_desktop_config.json` | The skill alone knows *how* to build; the MCP server is what actually talks to your instance. *** ## Before you start * Claude Desktop installed, with access to **Settings → Developer**. * SkyForge installed and on your PATH — see [Getting Started](/docs/start-here/getting-started.md). * Node.js 22+, and `mcp-remote` installed globally (`npm install -g mcp-remote`) — Step 3 covers this. * A ServiceNow instance URL and credentials. * On **Australia release or newer**, the account used for Basic Auth needs the `snc_basic_auth_api_access` role, or every call returns **401** — see [Connecting to ServiceNow → Basic Auth](/docs/connect/servicenow-connection.md#basic-auth). *** ## 1 — Export the SkyForge skill ```bash skyforge export-skills ``` This writes the **orchestrator skill** to `~/skyforge-skills/_zips/skyforge.zip`. That one zip is all you upload — the orchestrator pulls in domain skills (`servicenow-dev`, `business-rule-patterns`, `reviewer`, …) on demand through the `sn_load_skill` MCP tool, so there's no need to upload all 73 individually. | Command | Result | | ------------------------------------ | ---------------------------------------------------------------- | | `skyforge export-skills` | Orchestrator skill only → `~/skyforge-skills/_zips/skyforge.zip` | | `skyforge export-skills --all` | Orchestrator + reviewer + all 71 domain skills (one zip each) | | `skyforge export-skills ./my-skills` | Export to a custom directory | ![Export output confirming the skill location and generated .zip](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-89e1512e62c31d03c9d26a988b8c6e706c94f9b2%2Fclaude-desktop-export-skills.png?alt=media) *** ## 2 — Upload the skill to Claude Desktop In Claude Desktop: **Settings → Skills → Upload a Skill**, then select the `skyforge.zip` from Step 1 and confirm. ![Settings → Skills in Claude Desktop](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-bebd8f7f575668bb3987fc14b99603af868f04de%2Fclaude-desktop-settings-skills.png?alt=media) ![The Upload a Skill option](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-d1987e74243a2d4762228132ed275567a1b2ab21%2Fclaude-desktop-upload-skill.png?alt=media) > Re-uploading an updated skill (after a SkyForge update, for example) requires a Claude Desktop restart to take effect. *** ## 3 — Install `mcp-remote` Claude Desktop can't speak HTTP MCP natively, so it needs `mcp-remote` as a stdio→HTTP bridge. **This is a required step** — without it Claude Desktop shows the server as **failed** with `Server disconnected`. ```bash npm install -g mcp-remote ``` Verify it landed, and note the path it prints — you'll need it below: ```bash which mcp-remote # macOS / Linux where mcp-remote # Windows ``` Empty output means the install didn't take. Re-run it and check for permission errors. > **Install it globally — don't put `npx mcp-remote` in your config.** `npx` re-resolves and re-downloads the package on every launch. On a slow or unhealthy npm cache (common on locked-down corporate Windows machines) that cold start can exceed Claude Desktop's connection timeout, and the server never gets a chance to respond — Claude Desktop just reports the MCP server as failed to connect, with no useful error. ### Which path to use for `command` Claude Desktop is a GUI app, so it launches with a minimal `PATH` and **does not inherit your shell's environment**. If your global npm bin lives somewhere non-standard — nvm, Homebrew, fnm, Volta — the bare name `mcp-remote` will not resolve and the server fails to start. | Situation | `command` value | | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `which mcp-remote` returns a path under `/usr/bin` or `/usr/local/bin` | `mcp-remote` | | `which mcp-remote` returns anything else (nvm, Homebrew, fnm, Volta) | the **absolute path** it printed | | Windows | `%APPDATA%\npm\mcp-remote.cmd`, expanded — e.g. `C:\\Users\\\\AppData\\Roaming\\npm\\mcp-remote.cmd` | When in doubt, use the absolute path. It always works and costs nothing. *** ## 4 — Start SkyForge ```bash skyforge ``` Leave this running — Claude Desktop connects to it. Alongside the web UI on `:4096`, this starts the HTTP MCP server on `:3006`. ``` MCP endpoint: http://localhost:3006/mcp Health check: http://localhost:3006/health Bound to: 127.0.0.1 (this machine only) ``` ![SkyForge running locally, exposing its MCP endpoint on port 3006](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-e3731b4b548cad155740529eea626bf470676fab%2Fclaude-desktop-mcp-serve.png?alt=media) The banner prints the config for both clients ready to paste — the VS Code / Claude Code one-liner, and the full `claude_desktop_config.json` block with `mcp-remote`. If you're following along, copy from your own terminal rather than from this page: it fills in the port you're actually running on. **`Bound to:`** tells you where the MCP server is listening. `127.0.0.1 (this machine only)` is the default and what you want. Anything else prints a warning underneath, because that endpoint can act on your ServiceNow instance using the credentials stored on this machine — see [Running SkyForge → Custom hostname](/docs/use/running-skyforge.md#custom-hostname). > Don't want the web UI? `skyforge serve` runs headless and still exposes the MCP server on `:3006`. Confirm it's alive before touching Claude: ```bash curl http://localhost:3006/health ``` Using a custom port (`skyforge --mcp-port 9000`)? Substitute it everywhere below. *** ## 5 — Register the server in `claude_desktop_config.json` **Settings → Developer → Edit Config** opens the folder containing `claude_desktop_config.json`. Open the file in a text editor and add the `skyforge-nexus` block inside `mcpServers`. ![The Developer section of Claude Desktop settings](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-59d84ad4ba4af28921cab43ee8bd8590ee464268%2Fclaude-desktop-developer-settings.png?alt=media) ![Edit Config reveals the claude\_desktop\_config.json file](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-0da116358243f4ecf753ce48005ce71059bf48c2%2Fclaude-desktop-edit-config.png?alt=media) **Basic Auth:** ```json { "mcpServers": { "skyforge-nexus": { "command": "mcp-remote", "args": [ "http://localhost:3006/mcp", "--header", "X-SN-Instance:.service-now.com", "--header", "X-SN-Username:", "--header", "X-SN-Password:" ] } } } ``` **OAuth 2.0:** ```json { "mcpServers": { "skyforge-nexus": { "command": "mcp-remote", "args": [ "http://localhost:3006/mcp", "--header", "X-SN-Instance:.service-now.com", "--header", "X-SN-Client-Id:", "--header", "X-SN-Client-Secret:" ] } } } ``` **Already connected in SkyForge — the cleanest option:** If the instance is already connected on this machine (`skyforge auth login`, or through the Hub), name it and let SkyForge supply the credentials: ```json { "mcpServers": { "skyforge-nexus": { "command": "mcp-remote", "args": [ "http://localhost:3006/mcp", "--header", "X-SN-Instance:.service-now.com" ] } } } ``` No password in the config, and it works whether that instance is connected with Basic Auth, OAuth, or SSO. > **Prefer this over passing credentials.** `mcp-remote` writes its `--header` values verbatim to its own log file, so a password passed that way ends up in plaintext on disk. Naming the instance avoids that entirely. The instance can be written any of these ways — they all resolve to the same connection: ``` dev12345 dev12345.service-now.com https://dev12345.service-now.com ``` > ⚠️ **Use your instance's real domain, not always `.service-now.com`.** Most instances are `.service-now.com`, but some regional or government ServiceNow deployments live on a different domain entirely — for example `.servicenowcloud.com.`. Check the URL bar when you're logged into the instance and use that exact domain, not the generic placeholder shown above. `X-SN-Instance` is required whenever your instances were added through the Hub — SkyForge will not guess which of them you meant, since picking wrong means writing to the wrong ServiceNow instance. It can be omitted only on older single-instance setups connected with `skyforge auth login`. If the instance isn't connected, the request is refused — check the spelling against the instances listed in the SkyForge UI. ### Instances connected with SSO An instance connected using a browser session (SSO) needs one extra header: ```json "args": [ "http://localhost:3006/mcp", "--header", "X-SN-Instance:.service-now.com", "--header", "X-SkyForge-Auth-Source:stored" ] ``` Without it the request is refused with a message telling you to add it. The reason for the extra step: an SSO connection is a live browser session belonging to a real, usually privileged, account, and it replays with no password at all. Requiring you to ask for it explicitly means nothing uses it by accident. Basic Auth and OAuth instances don't need this header. {% hint style="info" %} SSO sessions expire — ServiceNow ends them after a period, and SkyForge can't renew one on your behalf. When that happens you'll see a message asking you to reconnect the instance in the SkyForge UI with a fresh **Copy as cURL** paste (labeled **Copy as cURL (bash)** in current Chrome and Edge — see [Browser Session / SSO](/docs/connect/servicenow-connection.md#browser-session-sso)). The reconnection takes effect immediately; no restart of Claude Desktop needed. {% endhint %} ![The skyforge-nexus MCP block added to claude\_desktop\_config.json](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-85dc3205871b4fedbf31c63e175a0b45e1b65cf8%2Fclaude-desktop-config-json.png?alt=media) > On Windows, `command` must be the `.cmd` path: `"command": "%APPDATA%\\npm\\mcp-remote.cmd"` — expanded to the literal path, e.g. `C:\\Users\\\\AppData\\Roaming\\npm\\mcp-remote.cmd`. *** ## 6 — Restart Claude Desktop cleanly 1. Save the config file and quit Claude Desktop. 2. **End the Claude task in Task Manager / Activity Monitor too** — closing the window often leaves the process running, and the config is only re-read on a genuine cold start. 3. Confirm SkyForge is still running in its terminal. 4. Relaunch Claude Desktop. *** ## Verify Under **Settings → Developer**, `skyforge-nexus` should be listed as **running**. In a new chat, both the SkyForge skill and the connector appear in the attachment/tools menu. ![skyforge-nexus listed as a running MCP server](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-35963bce3a1e9ff7bf191cc4b48d9f25b32be856%2Fclaude-desktop-server-running.png?alt=media) ![The SkyForge skill and connector available in a Claude Desktop chat](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-ed4fbf62b3f0a526c9a999c3d72596f80dab9c51%2Fclaude-desktop-chat-ready.png?alt=media) Then try: ``` Find me 3 active incidents ``` ![SkyForge responding to a ServiceNow request inside Claude Desktop](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-d799f38ce7e2f35c8fccc5bb9095adde34691911%2Fclaude-desktop-response.png?alt=media) *** ## How it works The uploaded `skyforge` skill auto-triggers on any ServiceNow task and tells Claude how to work: load `servicenow-dev` first, confirm the application scope, create an Update Set, load the matching domain skill, then build — loading the reviewer protocol before emitting code. ServiceNow tools aren't exposed to Claude one-by-one. Claude finds them with `tool_search` and runs them with `tool_execute({ tool, args })`, while `sn_load_skill` delivers skill content on demand. That's why one uploaded zip is enough for all 73 skills. ### Session Time-Saved classification SkyForge tracks how much developer time each session over MCP saved (visible on the Hub's Overview/Activity tabs). Rule-based classification always runs, free and instant. AI-refined classification is opt-in for MCP sessions specifically — see [Analytics](/docs/use/analytics.md) for the Hub UI walkthrough, or [Configuration → Time Saved & Session Analytics](/docs/reference/configuration.md#time-saved--session-analytics) for the `analytics.aiClassification` / `analytics.classifierModel` / `analytics.mcpSettleMinutes` keys directly. Worth knowing if you're wondering why a session you just finished over Claude Desktop still shows as rule-based: an MCP session needs `analytics.mcpSettleMinutes` (30 min by default) of idle time before it's even eligible, on top of the setting being on — nothing wrong, it just hasn't settled yet. To force it immediately for one session instead of waiting, use the **Run AI** button next to that session in the Hub, or `POST /api/analytics/sessions/:id/analyze?ai=true` directly. *** ## Troubleshooting | Symptom | Fix | | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Connector doesn't appear at all | Claude wasn't fully closed — end the background task, then relaunch | | Shows **failed** — `Server disconnected` | `mcp-remote` isn't installed (`npm install -g mcp-remote`), or it's installed somewhere Claude Desktop's minimal PATH can't reach — use the absolute path from `which mcp-remote` as `command` | | `View Logs` shows `spawn mcp-remote ENOENT` | Same cause — Claude Desktop can't find the binary. Absolute path fixes it | | Server shows as failed to connect | You're using `npx` in the config, or `mcp-remote` isn't installed — see Step 3 | | Still failing after switching off `npx` | Clear the npx cache: `npm cache clean --force`; on Windows also delete `%LOCALAPPDATA%\npm-cache\_npx` | | Config ignored entirely | Invalid JSON — check for trailing commas and unescaped `\` in Windows paths | | Connects, but every ServiceNow call returns 401 | Missing `snc_basic_auth_api_access` role (Australia release+), or wrong credentials in the headers | | `No stored credentials for instance "..."` | That instance isn't connected on this machine — check the spelling against the SkyForge UI, or connect it there | | `No ServiceNow instance selected` | Add `--header "X-SN-Instance:.service-now.com"`. SkyForge won't pick between connected instances for you | | `... is connected using a browser session (SSO)` | Add `--header "X-SkyForge-Auth-Source:stored"` — see [Instances connected with SSO](#instances-connected-with-sso) | | `Unable to authenticate with ... the stored browser session has expired` | Reconnect that instance in the SkyForge UI with a fresh **Copy as cURL** paste — takes effect immediately, no restart | | Connects, then dies mid-session | SkyForge stopped in the terminal — it must stay running the whole time | | `ECONNREFUSED` and SkyForge **is** running — Claude Desktop and SkyForge are on different hosts (WSL2, Docker, a remote dev box) | The MCP server binds `127.0.0.1`. Start SkyForge with `--mcp-hostname 0.0.0.0` (or `SN_MCP_HTTP_HOST=0.0.0.0`) — see [Ports & Server](/docs/use/running-skyforge.md#custom-hostname). Only do this on a network you trust: the endpoint can use the ServiceNow credentials stored on that machine | | Skill edits not showing up | Skills changed through the SkyForge Dashboard propagate to MCP clients within \~5s; a **re-uploaded** skill zip needs a Claude Desktop restart | Server-side logs: ```bash tail -f ~/.skyforge/skyforge-mcp.log ``` For verbose auth output, set `SN_MCP_DEBUG=true` before starting SkyForge — `SN_MCP_DEBUG=true skyforge` on macOS and Linux, `$env:SN_MCP_DEBUG="true"; skyforge` in Windows PowerShell, or `set SN_MCP_DEBUG=true` then `skyforge` in Command Prompt. *** ## Claude Code Claude Code speaks HTTP MCP natively — no `mcp-remote` needed: ```json { "type": "http", "url": "http://localhost:3006/mcp" } ``` The same headers apply — name the instance, and add the SSO opt-in if that instance is connected with a browser session: ```json { "type": "http", "url": "http://localhost:3006/mcp", "headers": { "X-SN-Instance": ".service-now.com", "X-SkyForge-Auth-Source": "stored" } } ``` And skills go in a local folder instead of being uploaded: ```bash skyforge export-skills --all cp -r ~/skyforge-skills/*/ ~/.claude/skills/ ``` *** ## Related * [Getting Started](/docs/start-here/getting-started.md) — install SkyForge and connect an instance * [Running SkyForge → Ports & Server](/docs/use/running-skyforge.md#ports--server) — custom ports, env vars, full MCP client reference * [Custom Skills](/docs/use/custom-skills.md) — write your own skills for SkyForge to load * [Submit an issue →](https://github.com/tryskyforge/skyforgeissues)