This article provides information, recommendations, and instructions for registering the SystemWeaver MCP Server with your AI Host. 


Registering the MCP Server

The MCP server speaks MCP over stdio. You will need to register it with your host's MCP config.


Claude Code (.mcp.json), pointing at the server's executable:

{
  "mcpServers": {
    "systemweaver": {
      "command": "C:\\path\\to\\SystemWeaverMCP.exe"
    }
  }
}


Important: Register SystemWeaverMCP.exe directly. Do not use "dotnet exec SystemWeaverMCP.dll".  When launched through dotnet exec, the process is dotnet.exe. Consequently, resources that the SystemWeaver client resolves relative to the executable or working directory (the Entra sign-in helper, the rich-text converter's native libraries) may be searched for in the .NET installation directory rather than alongside the MCP Server. 


This can cause:

  • Entra ID sign-in failures because the sign-in helper cannot be located.
  • Description content to be truncated at the first image because the rich-text converter's native libraries cannot be located.

Do not "simplify" this back to the dotnet form.


Environment variables

No env block is needed for normal operation. The server automatically reads:

  • appsettings.json from the directory containing the server assembly.
  • The encrypted credential store from the current Windows user's profile.

Only add SYSTEMWEAVER_ environment variables when using the debugging override described in Optional: Debug Override for Troubleshooting.


Other MCP-capable hosts

For other MCP-capable hosts, configure the same command/args in that host's MCP server settings.

Startup on a Slow Connection

At startup the server waits up to 20 seconds for the broker login before it answers the host, because the license decides which tools are offered. Keep the host's own startup timeout above that: Claude Code waits 30 seconds by default (MCP_TIMEOUT, in milliseconds) - do not lower it below 20000.


At startup, the MCP Server waits up to 20 seconds for the server login to complete before responding to the host. This is necessary because the user's license determines which tools the server makes available.


Ensure that the host's startup timeout exceeds this initial wait period. For example, Claude Code has a default startup timeout of 30 seconds, controlled by MCP_TIMEOUT (in milliseconds). Do not set this value below 20,000 milliseconds.


What happens if the broker login takes longer?

On slow or unstable connections, such as mobile or train networks, broker login may exceed the 20-second startup wait. In this situation:

  1. The MCP session starts with only the mcp_server_info tool available.
  2. When the broker login completes, the server immediately notifies the host that its tool list has changed.
  3. Hosts that support this notification will automatically refresh the tool list and display the full set of licensed tools. If the full tool list does not appear:
    • Call mcp_server_info to trigger a connection and license recheck.
    • If the full tool list still does not appear, start a new session.

How the Tools Are Called

The sw_* tools are MCP tools: the host calls them directly over this stdio connection. There is NO command-line equivalent - no "mcp call" form, no script to run - so a model that tries to reach them through a shell cannot succeed. The server states this in its MCP initialize response, which most hosts place in the model's context.

Recommended for Deployments Using Smaller Models

If your host also exposes generic shell or sub-agent tools alongside the SystemWeaver MCP Server, consider restricting them for sessions that use this server. 


Example

In Claude Code, you can disable these tools using:


        --disallowedTools Bash PowerShell Agent Task


This is a recommendation, not something the server can enforce. The SystemWeaver MCP Server cannot see or restrict what else the host offers.


Why this is recommended?

Validation revealed that some smaller models repeatedly attempted to invoke SystemWeaver MCP tools through a shell rather than using the MCP connection directly. In one full validation matrix, a smaller model generated:

  • 16 denied Bash/PowerShell attempts.
  • 13 references to a non-existent claude mcp call command.

These attempts came from one smaller model, not the two larger models tested. The shell attempts were denied, causing the model to stall on tasks it was otherwise capable of completing.


After removing the shell escape hatch, the validation results improved from a cluster of failures to 45 of 46 scenarios passing.


The MCP tools themselves remained accessible throughout. The problem was that the model repeatedly routed tool calls through the wrong interface.


So, for deployments using smaller models, restricting generic shell and sub-agent tools can significantly improve reliability. This was the single largest reliability improvement identified during validation, and it requires a configuration change rather than a code change.