@softacus-software/elwis-docs-mcp

A read-only Model Context Protocol server for ELWIS. It teaches your chat client the ELWIS REST API and lets it read your live ELWIS data: applications, folders, types, attributes, records, links, pages, and work items. It can never create, change, or delete anything. There are no write tools inside at all.

+-------------------+        +---------------------+        +-----------+
|  Your chat client |  <-->  |  elwis-docs-mcp     |  <-->  |  ELWIS    |
|  (Claude Desktop, |        |  (this server,      |        |  (reads   |
|  Codex, Gemini)   |        |  runs on your       |        |  only)    |
|                   |        |  computer)          |        |           |
+-------------------+        +---------------------+        +-----------+

Contents

• Set up with an AI assistant (fastest)
• Install
  • Before you start
  • Windows install
  • macOS and Linux install
  • Where files are stored
• Verify the connection
• What to ask
• Update
  • Windows update
  • macOS and Linux update
• Remove
• Troubleshooting
• Safety model
• Configuration
• Tools
• Keeping the API data up to date
• Development

The npm package page shows only this README, so every guide is inlined here rather than linked.

Set up with an AI assistant (fastest)

If you already have Claude Desktop, Codex, or Gemini open, paste this to it and follow along:

Help me install the ELWIS read-only MCP server on this computer.
I am on <Windows / macOS / Linux>. Walk me through, one step at a time:
1. Check Node.js 22+ is installed, and install it if not.
2. Sign in to npm for the @softacus-software organization.
3. Run: npx -y @softacus-software/elwis-docs-mcp@latest setup
   (on Windows PowerShell use npx.cmd instead of npx)
4. Tell me to fully quit and reopen you.
5. Ask you to call explain_elwis_access and confirm connected is true.
Do not ask me to paste my ELWIS password anywhere except the hidden setup prompt.

Otherwise follow the manual install below.

Install

Before you start

You need:

• Windows 10 or 11, macOS, or Linux
• Node.js 22 or newer
• an installed MCP client (Claude Desktop, Claude Code, Codex, or Gemini CLI)
• your ELWIS domain, email, and password
• an npm account with read access to the @softacus-software organization (ask your administrator to invite it)

The ELWIS password is used only by the sign-in request. It is hidden while typed and is not saved — only the resulting session is stored, on this computer only. Do not paste an ELWIS password or session token into a chat, ticket, script, or configuration file.

Windows install

1. Open PowerShell

Open a normal PowerShell or Windows Terminal window. Do not run it as Administrator unless Windows asks for elevation during the Node.js install.

2. Check for Node.js and npm

node.exe --version
npm.cmd --version

If both work and the Node major version is 22 or higher, continue. If either is missing, install the current LTS with WinGet:

winget.exe install --exact --id OpenJS.NodeJS.LTS --source winget --accept-package-agreements --accept-source-agreements

Approve the elevation prompt if it appears, then fully close and reopen PowerShell and check again. If winget.exe is not available, download the Windows LTS installer from nodejs.org or a company software portal.

3. Sign in to npm

npm access and ELWIS access are separate logins.

npm.cmd login --scope=@softacus-software --registry=https://registry.npmjs.org/
npm.cmd whoami
npm.cmd view @softacus-software/elwis-docs-mcp version

npm.cmd whoami should print your npm username and npm.cmd view should print the published version. If view returns E401, E403, or E404, stop and see Troubleshooting.

4. Run setup

Use npx.cmd, not bare npx, in PowerShell. This avoids the common npx.ps1 cannot be loaded execution-policy error.

npx.cmd -y @softacus-software/elwis-docs-mcp@latest setup

Setup asks for your ELWIS domain, your email and hidden password, and which MCP client to configure. It backs up any client file before changing it.

Windows note: the wizard writes the client command as plain npx. On most machines this works. If your client cannot start the server afterwards (no ELWIS tools appear), edit the generated config and change the command to cmd with args ["/c", "npx", "-y", "@softacus-software/elwis-docs-mcp@latest"] — see Manual client configuration.

5. Restart the MCP client

Fully quit every process of the client (closing the window is not enough), then reopen it and go to Verify the connection.

macOS and Linux install

Install Node.js 22 or newer from nodejs.org or your package manager, then open a terminal:

node --version
npm --version
npm login --scope=@softacus-software --registry=https://registry.npmjs.org/
npm whoami
npm view @softacus-software/elwis-docs-mcp version
npx -y @softacus-software/elwis-docs-mcp@latest setup

Setup asks for your ELWIS domain, email and hidden password, and which client to configure. Fully quit and reopen the client (on a Mac, Cmd+Q — closing the window is not enough), then go to Verify the connection.

Where files are stored

| What | Windows | macOS and Linux | |---|---|---| | Saved ELWIS session | %USERPROFILE%\.elwis\sessions | ~/.elwis/sessions | | MCP connection entry | the selected client's config file | the selected client's config file | | ELWIS password | not stored | not stored |

The session file is written with restrictive permissions. On Windows, 0600 is a Unix concept and does not replace an ACL review — use a separate Windows account per person on a shared computer. Do not copy the session token elsewhere; it rotates as it refreshes and a copy can invalidate the live one.

Verify the connection

After restarting the client, ask it:

Call explain_elwis_access and show me the result.

Check:

• connected is true
• readOnly is true (always — there are no write tools)
• tenant and email are the ones you expect
• tenantBinding.matches is true
• rights is what you expect for the account (system-admin, tenant-admin, or user)
• appScope.restricted is true if you set ELWIS_ALLOWED_APPS, with the expected entries

If connected is false, the documentation tools still work; the live-read tools need a sign-in — run login (below) or re-run setup.

What to ask

About your live data (it sees what your account sees, and only reads):

List the applications I can see in ELWIS.
Show me the work items in the ELWIS project and their statuses.
What attributes does the Task artifact type have?
Show me the links of this artifact.

About the API itself:

Which ELWIS endpoint creates an attribute?
What fields does the artifact type update request take?
Show me an example request for creating a link type.

You stay signed in about as long as a normal ELWIS browser login (around two weeks) and the session refreshes itself while you use it. When it runs out, sign in again — on Windows use npx.cmd:

npx -y @softacus-software/elwis-docs-mcp@latest login

To sign out on this computer:

npx -y @softacus-software/elwis-docs-mcp@latest logout <your-elwis-domain>

Update

The generated client configuration runs @softacus-software/elwis-docs-mcp@latest, so a full client restart normally starts the newest published version. There is nothing to run for a normal update. Use the checks below to confirm what is published, or when a connection needs repair.

Windows update

npm.cmd whoami
npm.cmd view @softacus-software/elwis-docs-mcp version

The version npm.cmd view prints is what users get. A version in source control or a changelog is not installable until this registry command shows it.

Re-run setup when any of these is true:

• setup was completed before this version
• the client configuration is wrong, or cannot start the server on Windows
• the saved login or tenant binding is wrong

npx.cmd -y @softacus-software/elwis-docs-mcp@latest setup

Upgrade Node.js only when it is below the requirement or your policy requires it:

node.exe --version
winget.exe upgrade --exact --id OpenJS.NodeJS.LTS --source winget --accept-package-agreements --accept-source-agreements

Close and reopen PowerShell after a Node update, then fully quit and reopen the client and re-verify with explain_elwis_access.

macOS and Linux update

npm whoami
npm view @softacus-software/elwis-docs-mcp version
npx -y @softacus-software/elwis-docs-mcp@latest setup   # only if the connection needs repair

Fully quit and reopen the client, then verify with explain_elwis_access.

Remove

npx runs the package on demand, so there is normally no global package to uninstall. Choose the smallest removal that meets the need.

Disconnect it from the client. Fully quit the client, back up its config file, remove only the server entry named elwis-docs, keep valid JSON/TOML, and reopen. The ELWIS tools should be gone.

Sign out locally. Windows: npx.cmd -y @softacus-software/elwis-docs-mcp@latest logout <your-elwis-domain>. macOS/Linux: the same with npx. This removes the saved local session for that host. Local logout does not prove the server-side session was revoked — if the computer is lost or shared, revoke the session in ELWIS or ask an administrator.

Remove all local ELWIS MCP session data (only when every saved login for this account should go):

Remove-Item -LiteralPath "$HOME\.elwis\sessions" -Recurse -Force -ErrorAction SilentlyContinue   # Windows

rm -rf ~/.elwis/sessions   # macOS and Linux

These remove local files only. They do not hard-delete any ELWIS resource.

Remove npm credentials / Node.js only if no other private package or program needs them:

npm logout --scope=@softacus-software --registry=https://registry.npmjs.org/

Troubleshooting

Start with the exact error. Do not paste passwords, session files, tokens, .npmrc, or full client configuration into a chat or ticket.

npx.ps1 cannot be loaded because running scripts is disabled (Windows). Use npx.cmd instead of npx in PowerShell. Every command in this guide has a .cmd form for Windows.

npm view returns E401 / E403 / E404. You are signed out of npm or your account lacks @softacus-software access. Run npm.cmd login --scope=@softacus-software --registry=https://registry.npmjs.org/ and ask your administrator to confirm the invite. A restricted package returns E404 when signed out.

The client starts but shows no ELWIS tools. Fully quit every process of the client and reopen — closing the window can leave the old process running. On Windows, if it still fails, switch the generated command to cmd /c npx (see Manual client configuration).

explain_elwis_access shows connected: false. There is no live login. Run login, or re-run setup. The documentation tools work regardless.

Tenant mismatch, or tenantBinding.matches: false. The saved login belongs to a different tenant than ELWIS_TENANT. Re-run setup, or correct the tenant id.

Session expired. Sessions last about two weeks. Run login again. The password is never stored, so a fresh sign-in is expected periodically — this is by design.

Safety model

• There are no write tools. The HTTP layer of this package has no put or delete method — it cannot send a create, update, or delete request even in principle.
• All tools are annotated readOnlyHint: true, destructiveHint: false.
• Reads run as the signed-in user, so ELWIS access control applies: the server sees exactly what that account sees.
• ELWIS_TENANT pins the connection to one tenant; a token for a different tenant is refused before any data is read.
• ELWIS_ALLOWED_APPS narrows reads to named applications, rejected before touching the backend.
• Whatever the server reads is returned to your chat client and therefore to that client's model provider. Treat "share with the MCP" as "share with the model provider", and scope with a restricted account plus ELWIS_ALLOWED_APPS when reading sensitive data such as production work items.

Configuration

Manual client configuration

The setup wizard writes these for you; use the blocks below only to do it by hand. With no env at all the server still runs and answers API-documentation questions only, never contacting a live system.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows) and Claude Code (.mcp.json in the project root, same shape):

{
  "mcpServers": {
    "elwis-docs": {
      "command": "npx",
      "args": ["-y", "@softacus-software/elwis-docs-mcp@latest"],
      "env": {
        "ELWIS_API_URL": "https://<your-elwis-host>",
        "ELWIS_TENANT": "<24-char tenant id>",
        "ELWIS_ALLOWED_APPS": "<AppName1,AppName2>"
      }
    }
  }
}

On Windows, if the client cannot start the server with plain npx, use cmd:

{
  "mcpServers": {
    "elwis-docs": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@softacus-software/elwis-docs-mcp@latest"],
      "env": { "ELWIS_API_URL": "https://<your-elwis-host>", "ELWIS_TENANT": "<24-char tenant id>" }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.elwis-docs]
command = "npx"
args = ["-y", "@softacus-software/elwis-docs-mcp@latest"]

[mcp_servers.elwis-docs.env]
ELWIS_API_URL = "https://<your-elwis-host>"
ELWIS_TENANT = "<24-char tenant id>"
ELWIS_ALLOWED_APPS = "<AppName1,AppName2>"

Gemini CLI (~/.gemini/settings.json): same JSON shape as Claude Desktop. Any other MCP client: register a STDIO server with command: "npx", args: ["-y", "@softacus-software/elwis-docs-mcp@latest"] and the same env, then call explain_elwis_access to verify.

Variables

| Variable | Required | What it does | |---|---|---| | ELWIS_API_URL | for live reads | Domain of the ELWIS backend, e.g. https://your-elwis-host. Without it, only the API documentation tools are available. | | ELWIS_TENANT | for live reads | The 24-character tenant id this connection is locked to. The wizard fills it in; explain_elwis_access shows it. | | ELWIS_SESSION_JWT | no | Access token for automation. When omitted, the saved login from setup/login is used and refreshed automatically. | | ELWIS_ALLOWED_APPS | no | Comma-separated application allowlist (names or ids). Everything outside the list is rejected before touching the backend. Default: everything the account can access. | | ELWIS_SESSIONS_DIR | no | Override the directory for saved sessions. Default ~/.elwis/sessions. |

Tools

| Group | Tools | What they do | |---|---|---| | Check | explain_elwis_access | Who am I, which tenant, what rights, what is in scope. Call this first. | | Live reads | list_elwis_apps, list_elwis_entities, resolve_elwis_entity, get_elwis_entity, list_elwis_artifacts, get_elwis_artifact, list_elwis_artifact_links, get_elwis_page | Browse applications, configuration, records, links, and pages of a live ELWIS. | | API documentation | search_elwis_api, list_elwis_api_groups, get_elwis_endpoint, get_elwis_schema, get_elwis_examples | Endpoints, parameters, schemas, and worked examples, generated from the OpenAPI specification. |

There are no write tools.

Keeping the API data up to date

The documentation data is generated deterministically from the ELWIS OpenAPI spec:

npm run export-spec   # fetch the current spec from a running ELWIS
npm run generate      # rebuild data/ from it
npm run check-drift   # fails when the bundled data no longer matches the spec

Run npm run check-drift against a current ELWIS before each release, so a released package does not silently fall behind the API. (CI runs it automatically when ELWIS_URL is configured for the pipeline.)

Development

npm install
npm run build
npm test