Softever.Benefits.Mcp.Local 1.12.0


                    
dotnet tool install --global Softever.Benefits.Mcp.Local --version 1.12.0
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Softever.Benefits.Mcp.Local --version 1.12.0
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Softever.Benefits.Mcp.Local&version=1.12.0
                    
nuke :add-package Softever.Benefits.Mcp.Local --version 1.12.0
                    

Softever Benefits — Local auto-create MCP server

A local stdio MCP server for Claude Code / Cowork that files benefit requests headlessly from files on your machine. Point Claude at a folder of receipts and let it create the requests.

It is a deliberately small sibling of the remote HTTP MCP server (../SofteverBenefits.Mcp):

Remote MCP (SofteverBenefits.Mcp) This (SofteverBenefits.Mcp.Local)
Transport Remote HTTP (Streamable) Local stdio subprocess
Tools Full read/create/edit/cancel/admin Create only
Receipts Browser upload (/u/{ticket} panel) Local file path, uploaded inline
UI MCP Apps interactive panels None (headless)
Auth Entra OAuth (client forwards its token) Entra device-code sign-in (this process)

How a create works

One synchronous tool call, upload-first:

  1. Validate inputs.
  2. Upload the receipt file from its local path to the backend (POST /api/files) → blob URL. If the upload fails, nothing is created.
  3. Build the request with that blob URL and POST it.
  4. Return the new record id / status (or the backend's error).

Quick start (teammates — one command, local backend)

Pulled the repo and just want it working against a local backend? From the repo root:

./scripts/setup-mcp-local.ps1

It builds the server, registers it with Claude Code (user scope), signs you in (device code — follow the prompt), and then starts the local backend (Docker SQL+Azurite → migrations → Functions host on :7075). Leave that window open — it's your backend. Then restart Claude Code, run /mcp, and ask it to call whoami.

Prerequisites: .NET 10 SDK, Docker Desktop (running), Azure Functions Core Tools v4, the Claude Code CLI, and dotnet-ef ≥ 10 (dotnet tool update --global dotnet-ef). Use -Reset to re-seed the DB.

The rest of this document is the manual/explanatory breakdown of what that script does.

Prerequisites (one-time, Entra)

On the configured public client (Azure Portal → App registrations → client → Authentication):

  • "Allow public client flows" = Yes — enables the device-code --login fallback. Without it, device code fails with AADSTS7000218/AADSTS90056.
  • A http://localhost redirect URI under Mobile & desktop applications — enables the on-demand interactive browser sign-in (loopback). Without it, the browser flow fails and the tool falls back to telling the user to run --login.

The default client id ships in appsettings.json; if it can't be configured this way, register a dedicated public client and override Entra:ClientId.

Configuration

Read from environment variables (override the appsettings.json defaults):

Key Default Notes
BenefitsApi__BaseUrl https://func-softever-benefits-prod.azurewebsites.net Embedded default is production; set to http://localhost:7075 for a local backend.
Entra__TenantId (repo tenant)
Entra__ClientId (repo public client) Must allow public-client flows (see above).
Entra__ApiScope api://benefits-api/access_as_user
Auth__CacheDir %LOCALAPPDATA%\SofteverBenefits\mcp-local Encrypted MSAL token cache (DPAPI on Windows).

Note the double-underscore (__) form for nested keys in environment variables.

Sign-in

On a machine with a browser (the normal case), sign-in is automatic. The first tool call with no cached token opens your system browser; sign in with your @softever.co.th account and the token is cached (encrypted, DPAPI on Windows). Subsequent calls are silent until the refresh token expires, then the browser pops again. No separate command, no code to copy.

The browser opens on the machine where the MCP process runs (your workstation, since Claude launches it locally). The tool call pauses while the browser is open, then continues.

Headless machines (no browser) use the out-of-band device-code fallback — run once in a terminal:

dotnet src/SofteverBenefits.Mcp.Local/bin/Release/net10.0/softever-benefits-mcp-local.dll --login

It prints microsoft.com/devicelogin + a code on stderr; sign in on any device. If interactive browser sign-in can't run and no cached token exists, a tool call returns a message telling you to run --login (it does not hang).

Register with Claude Code / Desktop / Cowork

Users (published package): the server ships as the NuGet tool package Softever.Benefits.Mcp.Local (PackageType=McpServer) and runs via dnx — downloaded and cached on first use, auto-updating within major v1. The config is machine-independent:

⚠️ This config points at PRODUCTION (the embedded default) — create tools file real requests. Developers: add "env": { "BenefitsApi__BaseUrl": "http://localhost:7075" } to target the local backend instead; whoami reports which backend you're on.

"mcpServers": {
  "softever-benefits-local": {
    "command": "dnx",
    "args": ["Softever.Benefits.Mcp.Local@1.*"]
  }
}

or, for Claude Code: claude mcp add -s user softever-benefits-local -- dnx Softever.Benefits.Mcp.Local@1.*

The package is standalone — the appsettings.json defaults (Entra tenant/public-client id, production API URL) are embedded as an assembly resource (see LocalConfig), and env entries override them (e.g. "BenefitsApi__BaseUrl": "http://localhost:7075" for a dev backend). The only machine prerequisite is the .NET 10 SDK (dnx ships with it).

Developers (working copy): build and register the DLL — do NOT use dotnet run as the launch command (it prints build output to stdout, which corrupts the JSON-RPC channel):

dotnet build -c Release src/SofteverBenefits.Mcp.Local/SofteverBenefits.Mcp.Local.csproj
"mcpServers": {
  "softever-benefits-local": {
    "command": "dotnet",
    "args": ["src/SofteverBenefits.Mcp.Local/bin/Release/net10.0/softever-benefits-mcp-local.dll"],
    "env": { "BenefitsApi__BaseUrl": "http://localhost:7075" }
  }
}

Or run the published package against the local backend (hybrid — the shipped bits, safely):

"mcpServers": {
  "softever-benefits-local": {
    "command": "dnx",
    "args": ["Softever.Benefits.Mcp.Local@1.*"],
    "env": { "BenefitsApi__BaseUrl": "http://localhost:7075" }
  }
}

To test the packaged experience without publishing, pack to a folder and point dnx at it:

dotnet pack src/SofteverBenefits.Mcp.Local -c Release -o C:\temp\mcp-feed
dnx Softever.Benefits.Mcp.Local --source C:\temp\mcp-feed

Tools

All create tools upload any receipt(s) from local paths first, then file the request in one call.

  • create_expense_request — date, amount, description, receiptPath (+ notes).
  • create_wallet_claim — categoryId, date, amount, receiptPath (+ fundSource, description).
  • create_health_checkup — date, hospital, actualCost, receiptPath.
  • create_leave_request — leaveTypeId, startDate, endDate (+ isHalfDay, halfDayPeriod, reason, medicalCertPath). Working-day count (weekends + public holidays excluded; half-day = 0.5) is computed automatically; the medical certificate is optional (you're told if one is required).
  • create_onsite_trip — tripDate, locationType, transportType, actualTransportFare (+ distanceKm, distanceMapPath, transportReceiptPath, project/client fields, tolls[], accommodations[]). Personal needs a distance-map screenshot; Other needs a fare > 0 + transport receipt; Shared needs neither. Each toll/accommodation carries its own receiptPath.
  • whoami (diagnostic) — confirms the signed-in employee; triggers sign-in on first use.

Office booking/check-in is out of scope.

Supported receipt types: jpg, jpeg, png, pdf, heic, heif, webp, zip (max 10 MB) — matches the backend allowlist.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
1.12.0 110 10/28/2026
1.11.6 99 10/26/2026
1.11.5 99 10/26/2026
1.11.4 147 8/24/2026
1.10.1 146 8/15/2026
1.9.1 149 7/13/2026