ELWIS Data MCP

ELWIS Data MCP is a local STDIO server that lets an MCP client read and build ELWIS applications, folders, data types, attributes, artifact types, records, links, pages, and workflows through the ELWIS HTTP API.

It acts as the signed-in ELWIS user. Backend authentication, ACL, tenant isolation, validators, and soft delete remain authoritative.

Everything you need is on this page. The same guides also ship as separate files under docs/ inside the installed package.

Contents

• Set up with an AI assistant (fastest)
• Install
• Verify the connection
• Update
• Remove
• Troubleshooting
• Safety model
• Session behavior
• Daily use
• Tools
• Configuration
• Development

Set up with an AI assistant (fastest)

Paste the block below into a terminal-capable AI assistant (Claude Code, Cursor, Codex, or similar) on the target computer. It performs every non-secret step itself and pauses only for elevation, npm browser sign-in, hidden ELWIS password entry, and the client restart.

Set up ELWIS Data MCP on this computer from start to finish. Windows is the primary path.

Rules:
1. Do every non-secret terminal and configuration step yourself. Do not give me a list of commands when you can run and verify them.
2. Never ask me to paste an ELWIS password, npm token, ELWIS session token, .npmrc, or full client configuration into this conversation.
3. Pause only when Windows requests elevation, npm opens a browser login, ELWIS setup requests the hidden password, or the MCP client must be restarted. Tell me exactly what action is required, then continue after it is complete.
4. Do not disable Defender, SmartScreen, Avast, another antivirus, TLS validation, or PowerShell security policy. If security software blocks a verified file, diagnose the exact file and follow the vendor's false-positive process.
5. Back up every existing client configuration before changing it. Change only the server entry named elwis-data. Preserve all unrelated entries and settings.
6. Preserve existing ELWIS_WRITE_ENABLED, ELWIS_DELETE_ENABLED, ELWIS_ALLOWED_APPS, ELWIS_REQUIRE_CONFIRMATION, DATA_MCP_BUILDERS, ELWIS_AUDIT_LOG, proxy, and CA settings during repair or update.
7. Never copy a rotating saved-session token into an environment variable, script, test, or second process.

Procedure:
1. Detect the operating system, shell, current user home, installed MCP clients, and whether this is a managed company computer. Report only non-secret facts.
2. On Windows, use PowerShell-compatible commands and call npm.cmd and npx.cmd explicitly. Check node.exe, npm.cmd, and npx.cmd. On macOS and Linux, use node, npm, and npx.
3. Require Node.js 22 or newer. If it is absent on Windows, install the current Node.js LTS with WinGet using the exact package id OpenJS.NodeJS.LTS. If WinGet is unavailable, use only the official Node.js Windows installer from nodejs.org and pause for the user to complete the installer. On macOS and Linux, use the official installer from nodejs.org or the approved package manager for the computer. Close and reopen the terminal after installation, then verify Node and npm versions.
4. Verify npm authentication with npm whoami and package access with npm view @softacus-software/elwis-data-mcp version. If needed, run npm login --scope=@softacus-software --registry=https://registry.npmjs.org/ and pause for browser sign-in. Distinguish E401, E403, and private-package E404. Do not continue until the published version is visible.
5. Check the package that will execute with:
   npx --yes --package @softacus-software/elwis-data-mcp@latest -- elwis-data-mcp --version
   Compare it with npm view. If source control claims a newer version than npm, report release drift and stop instead of pretending the update is available.
6. Run:
   npx -y @softacus-software/elwis-data-mcp@latest setup
   Let me type the ELWIS domain, email, and hidden password directly into the setup process. Do not capture or repeat them.
7. Confirm setup created a timestamped backup when a client file already existed. On Windows, verify the elwis-data entry starts with cmd /c npx and includes ELWIS_SESSIONS_DIR. Verify it does not contain a rotating ELWIS_SESSION_JWT after interactive setup. Do not print environment values that may be sensitive.
8. Ask me to fully quit and reopen the MCP client. Account for background and tray processes.
9. Call explain_elwis_access through the configured MCP connection. Require connected true, authenticated true, tenantBinding.matches true, and the expected appScope, writeEnabled, and writeConfirmation. A System Admin must be rights system-admin. Never describe a System Admin as guest. Stop if rights is guest or unknown.
10. Run one read-only ELWIS request as the final smoke test. Do not create, update, or delete anything during installation verification.
11. Return a short completion report containing OS, Node version, npm version, published package version, executed package version, changed config path, backup path, connection result, role, tenant match, gates, and any remaining action. Redact secrets.

For any failure, read docs/INSTALL.md, docs/UPDATE.md, docs/REMOVE.md, and docs/TROUBLESHOOTING.md shipped inside the installed package. Prefer official Node.js, Microsoft, npm, Defender, and antivirus vendor documentation. Do not weaken security to make installation pass.

Install

Before you start

You need:

• Windows 10 or 11, macOS, or Linux
• an installed MCP client
• your ELWIS domain, email, and password
• an npm account with read access to the @softacus-software organization
• permission to install Node.js, or an administrator who can approve the prompt

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

Node.js 22 or newer is required on every platform.

Windows clean install

1. Open PowerShell

Open a normal PowerShell or Windows Terminal window. Do not start 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 commands work and the Node major version is 22 or higher, continue to step 3.

If either command is missing, install the current LTS release with WinGet:

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

Approve the Windows elevation prompt if it appears. Fully close PowerShell, open a new PowerShell window, and run:

node.exe --version
npm.cmd --version
node.exe -e "process.exit(Number(process.versions.node.split('.')[0]) >= 22 ? 0 : 1)"

The last command should return to the prompt without an error.

If winget.exe is not available, install or update Microsoft App Installer, or download the Windows LTS installer directly from nodejs.org. Use only the official Node.js site or a company-managed software portal.

3. Sign in to npm

Browser access to ELWIS and browser access to npm are separate logins.

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

The login command opens a browser. Complete the npm sign-in there, then return to PowerShell.

Expected result:

• npm.cmd whoami prints your npm username.
• npm.cmd view prints the published package version.

If npm.cmd view returns E401, E403, or E404, stop and use Troubleshooting. A restricted package can return E404 when the account is signed out or lacks organization access.

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-data-mcp@latest setup

Setup asks for:

1. The ELWIS domain copied from the browser.
2. The ELWIS email and hidden password.
3. The MCP clients to configure.

Setup verifies that ELWIS returned an authenticated user and tenant. A guest-only response is rejected. Existing client configuration is backed up before it is changed. Re-running setup preserves existing write gates, application allowlists, confirmation settings, audit paths, proxy certificates, and other network settings.

The generated Windows command starts through cmd /c npx, and the configuration stores the exact session directory. This prevents PowerShell command resolution and Windows home-directory differences from dropping the saved login.

5. Restart the MCP client

Fully quit every process of the MCP client, then open it again. Closing only the current window may leave the old MCP process running. Then follow Verify the connection.

macOS and Linux install

Install Node.js 22 or newer from nodejs.org or the approved package manager for the computer. 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-data-mcp version
npx -y @softacus-software/elwis-data-mcp@latest setup

Fully quit and reopen the MCP client, then follow Verify the connection.

What is stored on Windows

• Saved ELWIS sessions: %USERPROFILE%\.elwis\sessions
• Default write audit log: %USERPROFILE%\.elwis\data-mcp-audit.jsonl
• MCP connection entry: the selected client's normal configuration file
• ELWIS password: not stored

Use a separate Windows account for each person on a shared computer. File mode 0600 is a Unix permission concept and does not replace Windows ACL review. Windows Credential Manager storage is a planned improvement, not current behavior.

All ELWIS MCP processes using the same Windows account and host can share the saved rotating session. Do not copy its token into curl, PowerShell variables, test scripts, or another computer. A second consumer can rotate the same token chain without saving the replacement. Use a separate ELWIS login or dedicated automation session for testing.

Verify the connection

Ask the client to call explain_elwis_access before any other ELWIS tool.

Verify all of these values:

• connected is true.
• authenticated is true.
• rights is system-admin, tenant-admin, or user as expected.
• A System Admin is reported as system-admin, never guest.
• tenantBinding.matches is true.
• authenticationSource is saved-session for an interactive setup.
• appScope, writeEnabled, and writeConfirmation match the intended restrictions.

Do not continue with data changes if the result says guest, unknown, disconnected, unauthenticated, or tenant mismatch.

Update

The generated client configuration runs @softacus-software/elwis-data-mcp@latest. A full client restart normally starts the latest published version. Use the checks below instead of assuming the update was published or loaded.

Windows update

Check npm access and the published version:

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

The second command is the version available to users. A version in source control or a changelog is not installable until this registry command shows it.

Check the package that runs now:

npx.cmd --yes --package @softacus-software/elwis-data-mcp@latest -- elwis-data-mcp --version

If the two versions match, the latest package is available on this computer.

If they do not match:

npm.cmd cache verify
npx.cmd --yes --package @softacus-software/elwis-data-mcp@latest -- elwis-data-mcp --version

Do not use an unpublished Git checkout as an end-user update. Fix the release first.

Run setup again when any of these is true:

• setup was completed with version 0.2.1 or older
• the client configuration starts Windows with plain npx instead of cmd /c npx
• the connection has no ELWIS_SESSIONS_DIR
• explain_elwis_access reports configured-token for a normal interactive login
• the saved login or tenant binding is wrong

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

The setup creates a backup before changing a client file. Current setup preserves existing write and delete gates, application allowlists, confirmation behavior, audit path, and network or certificate settings. It replaces connection identity fields and removes an old rotating ELWIS_SESSION_JWT when saved-session mode is configured.

Upgrade Node.js only when it is below the package requirement, unsupported, or your normal update 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 every process of the MCP client and open it again. Call explain_elwis_access and verify connected: true, authenticated: true, correct rights, tenantBinding.matches: true, and unchanged appScope, writeEnabled, and writeConfirmation. Run one read-only request before any write. The first write must still use dryRun: true and the returned confirmation token unless immediate scripted execution was explicitly configured.

macOS and Linux update

npm whoami
npm view @softacus-software/elwis-data-mcp version
npx --yes --package @softacus-software/elwis-data-mcp@latest -- elwis-data-mcp --version
npx -y @softacus-software/elwis-data-mcp@latest setup

Re-run setup only when the saved connection or client entry needs repair. Fully quit and reopen the client, then verify with explain_elwis_access.

Rollback

Client configuration backups are created next to the original configuration file with a timestamp. To roll back a configuration change:

1. Fully quit the client.
2. Keep a copy of the current file for diagnosis.
3. Restore the required timestamped backup.
4. Reopen the client and call explain_elwis_access.

Do not roll back a session token by copying an older session file. Rotating tokens become invalid and can also invalidate another process using the same chain.

Remove

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

Disconnect it from the MCP client

1. Fully quit the MCP client.
2. Back up its configuration file.
3. Remove only the server entry named elwis-data.
4. Keep every unrelated server and client setting unchanged.
5. Reopen the client and confirm the ELWIS Data tools are no longer listed.

For JSON configuration, remove only mcpServers.elwis-data and keep valid JSON syntax.

For TOML configuration, remove only these sections and their values:

[mcp_servers.elwis-data]
[mcp_servers.elwis-data.env]

Do not delete the entire client configuration file.

Sign out locally

Windows:

npx.cmd -y @softacus-software/elwis-data-mcp@latest logout <your-elwis-domain>

macOS or Linux:

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

This removes the saved local session for that host. Other ELWIS MCP processes on the same computer may use the same saved session and will also need a new login.

Local logout does not prove the server-side session was revoked. If the computer is lost, shared, or compromised, revoke the session in ELWIS or ask an ELWIS administrator to revoke it.

Remove all local ELWIS MCP session data

Use this only when every saved ELWIS login for the current account should be removed:

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

Remove the audit log only when its retention policy allows deletion:

Remove-Item -LiteralPath "$HOME\.elwis\data-mcp-audit.jsonl" -Force -ErrorAction SilentlyContinue

On macOS and Linux the same files live under ~/.elwis/. These commands remove local files only. They do not hard-delete any ELWIS resource.

Remove npm credentials

Do this only if the npm login is no longer needed for any private package in the same scope:

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

Never share or attach the user .npmrc file. It can contain registry credentials.

Remove Node.js

Node.js can be used by other programs. Remove it only after confirming nothing else needs it:

winget.exe uninstall --exact --id OpenJS.NodeJS.LTS

Node removal is not required to disconnect or remove ELWIS Data MCP.

Full removal verification

• The client has no elwis-data server entry.
• The client no longer lists ELWIS Data tools after a full restart.
• The required local session file or session directory is gone.
• The server-side ELWIS session is revoked when security requires it.
• npm credentials and Node.js are removed only if they are no longer used elsewhere.

Troubleshooting

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

Quick Windows diagnosis

Run these in a new PowerShell window:

Get-Command node.exe, npm.cmd, npx.cmd -ErrorAction SilentlyContinue
node.exe --version
npm.cmd --version
npm.cmd whoami
npm.cmd view @softacus-software/elwis-data-mcp version
npx.cmd --yes --package @softacus-software/elwis-data-mcp@latest -- elwis-data-mcp --version

Then fully restart the MCP client and call explain_elwis_access. Its output is designed for support and never returns the token.

Node, npm, and PowerShell

node, npm, or npx is not recognized

Install Node.js LTS as described in Install. After installation, close every PowerShell window and open a new one so the updated PATH is loaded.

Check the executable locations:

where.exe node
where.exe npm
where.exe npx

npm.ps1 or npx.ps1 cannot be loaded because running scripts is disabled

Use the Windows command wrappers:

npm.cmd --version
npx.cmd -y @softacus-software/elwis-data-mcp@latest setup

Do not weaken a company PowerShell execution policy just to run this package. PowerShell policy can be controlled by Group Policy and should be changed only by the responsible administrator.

winget.exe is not recognized

Install or update Microsoft App Installer, or use the official Windows LTS installer from nodejs.org. Do not download Node.js from an unknown mirror.

Node is installed but the major version is below 22

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

Close and reopen PowerShell after the upgrade.

npm access

E401

The terminal is not authenticated to npm or its credential expired.

npm.cmd login --scope=@softacus-software --registry=https://registry.npmjs.org/
npm.cmd whoami

E403

The npm account is authenticated but does not have package read access. Confirm that the organization invitation was accepted and the account belongs to the team that can read the package.

E404 for the package

E404 can mean any of these:

• the npm account is signed out
• the account lacks organization access
• the requested version was never published
• the package scope is wrong

Use the exact scope and check the registry:

npm.cmd whoami
npm.cmd view @softacus-software/elwis-data-mcp versions --json

If the required version is absent, the release is not available to users yet. A local package.json or changelog entry does not publish it.

Proxy or certificate errors

Common messages include SELF_SIGNED_CERT_IN_CHAIN, UNABLE_TO_VERIFY_LEAF_SIGNATURE, timeout, or proxy authentication errors.

Use the company proxy and CA certificate supplied by the IT team:

npm.cmd config set https-proxy "http://proxy.company.example:8080"
npm.cmd config set cafile "C:\Company\Certificates\root-ca.pem"
npm.cmd config get https-proxy
npm.cmd config get cafile

Do not set strict-ssl=false. Fix the trusted CA or proxy configuration instead. Do not put proxy passwords in tickets or shared command history.

See the official npm configuration reference.

Defender, SmartScreen, and Avast

Do not disable antivirus, SmartScreen, or all real-time protection. Do not add broad exclusions for the entire user profile, npm cache, Downloads folder, PowerShell, or Node.js.

If a file is blocked:

1. Record the exact file path, detection name, package version, and time.
2. Confirm Node.js came from nodejs.org, WinGet, or the company software portal.
3. Confirm the package scope is exactly @softacus-software/elwis-data-mcp and npm access is authenticated.
4. Open Windows Security Protection History or Avast Quarantine and review the specific item.
5. Restore or allow only that exact verified item if company policy permits it.
6. Submit the item as a false positive to the security vendor.
7. Run npm.cmd cache verify, then download the package again.

If the publisher, source, or path cannot be verified, leave the file quarantined and contact the security team.

Official help:

• Microsoft Defender Protection History
• Avast Quarantine and false-positive submission

Setup and client startup

Setup hangs at the password prompt

Use a normal interactive PowerShell or Windows Terminal window. Do not pipe input into setup. Confirm the latest published version, then run:

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

Setup says sign-in succeeded but no authenticated user and tenant were returned

The backend returned guest-only or incomplete user information. Stop. Check the ELWIS domain, VPN, account, and tenant. A System Admin must still return a real sessionUser and is reported as system-admin by version 0.2.3 or newer.

No ELWIS tools appear after setup

Fully quit every client process, including tray or background processes, then reopen it. Confirm setup selected the correct client and created a backup plus an elwis-data entry. On Windows, the entry must start through cmd /c npx and include ELWIS_SESSIONS_DIR.

The client still runs an older version

Compare the published and executed versions:

npm.cmd view @softacus-software/elwis-data-mcp version
npx.cmd --yes --package @softacus-software/elwis-data-mcp@latest -- elwis-data-mcp --version
npm.cmd cache verify

If the registry reports the old version, the new release was not published. If the registry is newer, fully stop the client and retry the explicit npx.cmd version command.

ELWIS identity and context

connected: false

Read connectionError from explain_elwis_access. Check the ELWIS domain, DNS, VPN, proxy, TLS certificate, and backend availability. Re-run setup only after the host is reachable.

authenticated: false, rights: guest, or rights: unknown

Do not read or change tenant data. Run setup again with the intended account and restart the client. Confirm no client configuration contains an old rotating ELWIS_SESSION_JWT for an interactive login.

A real System Admin must report rights: system-admin. If it reports guest on version 0.2.3 or newer, keep the safe explain_elwis_access output and the exact package version for investigation.

Context works at first and disappears later

The usual cause is more than one process consuming the same rotating session token chain. The token has a short grace window after rotation.

• Do not read the saved session token into $env:ELWIS_SESSION_JWT.
• Do not reuse the MCP session token in curl, API tests, another computer, or another Windows account.
• Stop duplicate client processes.
• Give QA scripts and automation their own ELWIS session.
• Run the login command again after removing the second consumer.

Windows environment variables set with $env: exist only in that process and its children. They are not a reliable persistent MCP client configuration. Use setup, which writes the client entry and exact saved-session directory.

Tenant mismatch

No request is allowed when the signed-in tenant differs from ELWIS_TENANT. Re-run setup with the correct ELWIS domain and account. Do not copy a tenant id from another environment just to bypass the check.

Applications are missing

Check both appScope from explain_elwis_access and the account's backend ACL. The MCP allowlist can only reduce access. It cannot grant access that ELWIS denied.

Writes are disabled or confirmation is stale

Check writeEnabled and writeConfirmation. Every interactive write uses a new dryRun: true plan. Execute only with the confirmation token returned by that exact plan. A token from an older or changed plan is intentionally rejected.

Safe support information

Safe to provide:

• Windows version and terminal name
• Node, npm, package, and MCP client versions
• exact error text after checking it contains no credential
• explain_elwis_access output
• client configuration path, but not the file contents
• antivirus product, detection name, file path, and time

Never provide:

• ELWIS password
• session token or any file under .elwis\sessions
• .npmrc
• proxy password
• full client configuration when it contains environment values

Safety model

• Identity and role are verified against /api/tenant/user/info, not inferred from token claims.
• Role precedence is system-admin, tenant-admin, guest, user, then unknown.
• Every tenant operation is pinned to ELWIS_TENANT.
• ELWIS_ALLOWED_APPS can reduce access but cannot grant backend access.
• Every interactive write starts with dryRun: true.
• Execution requires the confirmation token from that exact plan unless immediate scripted execution was explicitly enabled.
• Deletes use ELWIS soft-delete endpoints.
• Executed writes are recorded in the audit log without storing the session token.
• A guest-only login response is rejected by setup.

Session behavior

Interactive setup stores a rotating ELWIS session under the current user's .elwis/sessions directory and writes its exact location into the client configuration. The password is never stored.

Do not copy the saved token into a shell variable, curl command, test, or second computer. A second consumer can rotate the same token chain without persisting the replacement and make the original process stale. Use an independent login for QA and automation.

The server adopts rotated cookies even when a token was configured directly, but a normal interactive setup should use saved-session, not a copied ELWIS_SESSION_JWT.

Daily use

Typical requests:

List the applications I can access.
Show Product records in the selected application.
Create a support-ticket page after showing the dry-run plan.
Rename the Priority attribute to Urgency.

If identity or context becomes uncertain, call explain_elwis_access again before continuing.

Tools

| Group | Tools | Purpose | |---|---|---| | Access | explain_elwis_access | Verify connection, authentication, role, tenant, app scope, gates, session source, and system attributes. | | Read | 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 configuration, records, links, and pages. | | Create | create_elwis_application, create_elwis_folder, build_artifact_type, create_elwis_artifacts, build_links, build_page, build_workflow | Create ELWIS structures and records through validated plans. | | Change | update_elwis_entity, update_elwis_artifacts, update_elwis_page | Update only requested fields. | | Delete | delete_elwis_entity, delete_elwis_artifacts | Preview dependencies and soft delete. | | Design | propose_page_design | Gather the page and data requirements before building. |

Configuration

| Variable | Required | Purpose | |---|---|---| | ELWIS_API_URL | yes | ELWIS backend origin, such as https://elwis.company.example. | | ELWIS_TENANT | yes | 24-character tenant id. All data operations fail closed when it is missing or mismatched. | | ELWIS_SESSIONS_DIR | interactive setup | Exact saved-session directory. Setup writes it automatically. | | ELWIS_SESSION_JWT | automation only | Dedicated token for non-interactive use. An explicit token wins over saved login. Do not use a copied rotating interactive token. | | ELWIS_WRITE_ENABLED | no | true allows write planning and execution. Default is read-only. | | ELWIS_DELETE_ENABLED | no | Enables delete operations when the write gate also permits them. | | ELWIS_ALLOWED_APPS | no | Comma-separated application names or ids. Empty means backend-visible applications. | | ELWIS_REQUIRE_CONFIRMATION | no | Default true. Set false only for controlled scripted execution. | | ELWIS_AUDIT_LOG | no | Write audit path. Default is .elwis/data-mcp-audit.jsonl under the user home. | | DATA_MCP_BUILDERS | no | Set off only for the low-level raw API mode. |

Development

npm ci
npm test
npm run lint
npm run build
npm pack --dry-run

The release pipeline publishes tags to npm and requires a protected NPM_TOKEN. The Git tag must exactly match v plus the package version.