Softever.Benefits.Mcp.Local
1.12.0
dotnet tool install --global Softever.Benefits.Mcp.Local --version 1.12.0
dotnet new tool-manifest
dotnet tool install --local Softever.Benefits.Mcp.Local --version 1.12.0
#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:
- Validate inputs.
- Upload the receipt file from its local path to the backend (
POST /api/files) → blob URL. If the upload fails, nothing is created. - Build the request with that blob URL and
POSTit. - 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
--loginfallback. Without it, device code fails withAADSTS7000218/AADSTS90056. - A
http://localhostredirect 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;whoamireports 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 ownreceiptPath.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 | Versions 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. |
This package has no dependencies.