@jonathanyee/ms-decision-mcp

v0.1.1

Published

17 days ago

A typed decision API for agents, powered by Microsoft-Decision-1 on Azure.

0High
0Medium
0Low

jonathanyee

mcp azure microsoft-decision agents

Decision API for agents

A stdio MCP server wrapping Microsoft-Decision-1 on Azure Foundry. Agents use one decide tool to make fast, bounded, schema-validated evaluations without generating or parsing prose.

Use it for routing, classification, verification against supplied evidence, prioritization, and rubric grading. It is not a chat model, deterministic rules engine, or authorization service. Type safety ensures valid answer structure and labels, not correct judgments.

Setup

Requires Node.js 22+ and a Microsoft-Decision-1 deployment. If you are starting without Azure resources, follow Deploy Microsoft-Decision-1 from scratch first.

Run the npm package without cloning or building the repository:

export AZURE_DECISION_ENDPOINT=https://your-resource.services.ai.azure.com
export AZURE_DECISION_DEPLOYMENT=your-deployment-name
export AZURE_DECISION_AUTH=azure-cli
az login
npx --yes @jonathanyee/[email protected]

Use npx --yes @jonathanyee/[email protected] --help to view options without Azure configuration or an inference request. The version is pinned for reproducibility; update it deliberately when upgrading.

If you previously used the unscoped ms-decision-mcp npm package, update your installation and MCP client configuration to @jonathanyee/ms-decision-mcp. Existing installations are not migrated automatically. The executable remains named ms-decision-mcp.

For a source checkout, install dependencies and build before launching:

The source setup below uses your normal Azure CLI profile. To keep that profile unchanged, run the build commands and set the endpoint/deployment variables below, but replace the bare az login and npm start commands with the login and launch commands in Dedicated Azure CLI login. The same profile isolation works with npx: prefix it with AZURE_CONFIG_DIR="$HOME/.azure-ms-decision".

npm install
npm run build

export AZURE_DECISION_ENDPOINT=https://your-resource.services.ai.azure.com
export AZURE_DECISION_DEPLOYMENT=your-deployment-name
export AZURE_DECISION_AUTH=azure-cli
az login
npm start

The endpoint must be the resource base URL, not a Foundry project endpoint. The server appends /providers/microsoft/v1/systemone. The request model is your deployment name; the response identifies the underlying model.

Deploy Microsoft-Decision-1 from scratch

This walkthrough uses the Foundry portal to create the resource and project, then deploys the model. You do not need Python or an Azure SDK to use this MCP server.

Prepare your account and local tools. You need an Azure subscription, access to Microsoft Foundry, Node.js 22+, and the Azure CLI. Creating resources requires permission on the subscription or resource group; model deployment requires a role such as Cognitive Services Contributor. Assigning roles requires separate role-assignment permission, such as Owner or Role Based Access Control Administrator. Ask your Azure administrator if these permissions are missing. Review the deployment's quota before proceeding.
Create a Foundry resource and project. Sign in to the Foundry portal with the intended account and directory. In the new Foundry experience, choose Create new project (from the project selector if a project is already open). Use the advanced options to select the intended subscription, create a dedicated resource group, and choose a location. The portal creates the parent Foundry resource along with the project. See Microsoft's project creation guide for the current UI and permission requirements.
Deploy the model. Open the project's Model catalog, search for Microsoft-Decision-1, and choose Deploy. Give the deployment a name, for example decision-1, and select a supported deployment type and capacity. Microsoft's current guide documents model version 1, GlobalStandard, and DataZoneStandard in selected regions. Availability and quota vary by subscription and region; if deployment is unavailable, check these before creating another resource. GlobalStandard can process inference globally; use an available DataZoneStandard deployment when data-zone locality is required. Wait for deployment to succeed.
Record the resource settings. On the deployment details page, copy the resource endpoint and deployment name. Also record the parent Foundry resource's name and resource group from its Azure portal overview. The endpoint must be a base URL such as https://your-resource.services.ai.azure.com, not the project URL ending in /api/projects/..., an OpenAI URL ending in /openai/..., or the full decision API URL. The deployment name is the name you chose (decision-1 in this example), not necessarily Microsoft-Decision-1.
Grant inference access to the runtime identity. Open the parent Foundry resource in the Azure portal, then Access control (IAM) → Add role assignment. Assign Cognitive Services User to the user or service principal that will run the MCP server. Deployment-management permission alone is not a substitute for inference permission. If you use a dedicated CLI login, assign the role to that login's identity, which may differ from the account that created the deployment. Allow time for the assignment to propagate. For API-key authentication, use the resource key instead (see below).
Sign in locally and configure the server. Use az login --tenant <tenant-id> and az account set --subscription <subscription-id>, or follow the dedicated-login section below. A portal browser login and a local CLI login are separate sessions. Set the variables described in Find and supply the configuration values, then run npm install and npm run build from this repository.
Optionally verify inference, then connect your MCP client. npm run test:live makes one inference request against the configured deployment and prints the result. Then use the MCP client configuration below. npm start launches a stdio MCP server; it is not an interactive chat or an HTTP server.

If the resource and project already exist, you can replace the catalog deployment step with Microsoft's CLI command. Set these shell variables to your parent resource name and resource group, then choose a deployment name:

FOUNDRY_RESOURCE_NAME="your-foundry-resource"
AZURE_RESOURCE_GROUP="your-resource-group"
export AZURE_DECISION_DEPLOYMENT="decision-1"

az cognitiveservices account deployment create \
  --name "$FOUNDRY_RESOURCE_NAME" \
  --resource-group "$AZURE_RESOURCE_GROUP" \
  --deployment-name "$AZURE_DECISION_DEPLOYMENT" \
  --model-name Microsoft-Decision-1 \
  --model-format Microsoft \
  --model-version 1 \
  --sku-name GlobalStandard \
  --sku-capacity 1

This command creates a model deployment, not the resource or project. For the authoritative deployment instructions and regional availability links, see Microsoft's Microsoft-Decision-1 guide.

Find and supply the configuration values

| Value | Where to find it | Server setting | | --- | --- | --- | | Resource endpoint | Foundry deployment details; copy the resource base endpoint, not the project endpoint | AZURE_DECISION_ENDPOINT or --endpoint | | Deployment name | Foundry deployment details; the name chosen during deployment | AZURE_DECISION_DEPLOYMENT or --deployment | | Authentication mode | Your choice: explicit CLI login, credential chain, or resource key | AZURE_DECISION_AUTH or --auth | | Resource API key (optional) | Resource Keys and Endpoint in Azure portal, when key authentication is enabled | AZURE_DECISION_API_KEY (environment only) | | Tenant/directory ID | Azure portal Microsoft Entra ID → Overview | az login --tenant; not a wrapper-specific setting | | Subscription ID | Azure portal Subscriptions → your subscription → Overview | az account set --subscription; not a wrapper-specific setting | | Resource name / resource group | Parent Foundry resource's Azure portal Overview | Used by administrative CLI commands; not required by the MCP server |

For example, supply nonsecret settings in the shell that launches the server:

export AZURE_DECISION_ENDPOINT="https://your-resource.services.ai.azure.com"
export AZURE_DECISION_DEPLOYMENT="decision-1"
export AZURE_DECISION_AUTH="azure-cli"

# Confirm the CLI identity and selected subscription (does not test inference):
az account show --query '{user:user.name,tenant:tenantId,subscription:id}' --output json

# Look up deployment names on the parent resource:
# Set these even if you created the deployment through the portal.
FOUNDRY_RESOURCE_NAME="your-foundry-resource"
AZURE_RESOURCE_GROUP="your-resource-group"
az cognitiveservices account deployment list \
  --name "$FOUNDRY_RESOURCE_NAME" \
  --resource-group "$AZURE_RESOURCE_GROUP" \
  --query '[].{deployment:name,model:properties.model.name}' --output table

FOUNDRY_RESOURCE_NAME and AZURE_RESOURCE_GROUP above are convenience shell variables for Azure administration, not settings consumed by this server. Microsoft examples sometimes use AZURE_ENDPOINT and DEPLOYMENT_NAME; this wrapper reads AZURE_DECISION_ENDPOINT and AZURE_DECISION_DEPLOYMENT instead.

A desktop MCP client may not inherit variables exported in your terminal. Put the settings in the client's server env configuration (shown below), or use the nonsecret command-line flags. .env.example is only a template: copying it to .env does not load it automatically. With Node.js 22+, you can explicitly load a private file with node --env-file=/absolute/path/decision.env dist/index.js; never commit files containing keys or client secrets.

Dedicated Azure CLI login

Use this when your normal az login is for another user, tenant, or subscription. Azure CLI's AZURE_CONFIG_DIR isolates its configuration and token cache. No code changes or additional server flags are required.

Log in and select a subscription in a dedicated profile. These per-command settings leave your normal CLI profile unchanged:

AZURE_CONFIG_DIR="$HOME/.azure-ms-decision" az login --tenant <tenant-id>
AZURE_CONFIG_DIR="$HOME/.azure-ms-decision" \
  az account set --subscription <subscription-id>
AZURE_CONFIG_DIR="$HOME/.azure-ms-decision" \
  az account show --query '{user:user.name,tenant:tenantId,subscription:id}' --output json

Select the intended user during browser sign-in; use az login --use-device-code --tenant <tenant-id> with the same AZURE_CONFIG_DIR if browser login is inconvenient. Selecting a subscription does not sign in as a different user. Protect the profile directory because it contains authentication state.

Launch the server with the same directory and explicit CLI authentication:

AZURE_CONFIG_DIR="$HOME/.azure-ms-decision" \
  AZURE_DECISION_AUTH=azure-cli npm start

The endpoint and deployment variables must also be set. The profile above is selected per command, not exported for the whole shell: a later bare az command or npm start still uses your normal profile. Prefix deployment, lookup, and live-test commands with the same AZURE_CONFIG_DIR when they should use the dedicated identity (for example, AZURE_CONFIG_DIR="$HOME/.azure-ms-decision" AZURE_DECISION_AUTH=azure-cli npm run test:live; this makes one inference request). For an MCP client, use this complete configuration with your actual paths and values:

{
  "mcpServers": {
    "decision": {
      "command": "node",
      "args": ["/absolute/path/ms-decision-mcp/dist/index.js"],
      "env": {
        "AZURE_DECISION_ENDPOINT": "https://your-resource.services.ai.azure.com",
        "AZURE_DECISION_DEPLOYMENT": "decision-1",
        "AZURE_DECISION_AUTH": "azure-cli",
        "AZURE_CONFIG_DIR": "/home/your-user/.azure-ms-decision"
      }
    }
  }
}

Use an absolute path in JSON: ~ and $HOME generally are not expanded by MCP clients. The server process needs access to this directory and to az on its PATH. Restart the MCP server after changing its environment. This login does not automatically grant access to the deployment: the dedicated identity still needs the inference role on the target resource.

Command-line settings

You can supply nonsecret settings as arguments instead of environment variables:

node dist/index.js \
  --endpoint https://your-resource.services.ai.azure.com \
  --deployment your-deployment-name \
  --auth azure-cli \
  --timeout-ms 30000

# With npm, use -- to forward arguments:
npm start -- --endpoint https://your-resource.services.ai.azure.com \
  --deployment your-deployment-name --auth azure-cli

Arguments override the corresponding environment variables; omitted options use the environment settings and existing defaults. Both --option value and --option=value are supported. Unknown options, positional arguments, missing values, and invalid settings are rejected. Use node dist/index.js --help for usage (written to stderr to keep MCP stdout clean).

API keys remain environment-only via AZURE_DECISION_API_KEY; there is deliberately no --api-key flag, to avoid exposing secrets in process arguments or shell history.

Authentication

| Environment variable | Meaning | | --- | --- | | AZURE_DECISION_ENDPOINT | Required HTTPS resource base URL | | AZURE_DECISION_DEPLOYMENT | Required deployment name | | AZURE_DECISION_AUTH | default, azure-cli, or api-key | | AZURE_DECISION_API_KEY | Required only with api-key | | AZURE_DECISION_TIMEOUT_MS | Default 30000; range 1–300000 |

Without an explicit auth mode, a configured API key selects api-key; otherwise the server uses DefaultAzureCredential (managed identity, environment credentials, developer credentials, etc.). azure-cli uses your current az login explicitly. Entra credentials request https://cognitiveservices.azure.com/.default; the identity needs inference permission on the resource, typically via Cognitive Services User.

For automation without a user CLI session, select default and supply service-principal credentials through AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET in the server process's environment. On supported Azure hosting, default can also use managed identity without a stored client secret. These identities still need inference permission. For resource-key authentication, explicitly select api-key and supply AZURE_DECISION_API_KEY; this bypasses the CLI login and requires key authentication to be enabled on the resource.

Keep API keys and client secrets in your environment or secret manager, never in tool arguments or source control. .env.example is a template; the server does not automatically load .env files. Endpoint and deployment configuration are operator-controlled, not agent-controlled.

MCP client configuration

To use the npm package, configure the client to launch npx:

{
  "mcpServers": {
    "decision": {
      "command": "npx",
      "args": ["--yes", "@jonathanyee/[email protected]"],
      "env": {
        "AZURE_DECISION_ENDPOINT": "https://your-resource.services.ai.azure.com",
        "AZURE_DECISION_DEPLOYMENT": "your-deployment-name",
        "AZURE_DECISION_AUTH": "azure-cli"
      }
    }
  }
}

For a dedicated Azure CLI profile, add AZURE_CONFIG_DIR with its absolute path to env. The client needs npx and, for azure-cli authentication, az on its PATH.

Alternatively, build a source checkout first and substitute your absolute repository path:

{
  "mcpServers": {
    "decision": {
      "command": "node",
      "args": ["/absolute/path/ms-decision-mcp/dist/index.js"],
      "env": {
        "AZURE_DECISION_ENDPOINT": "https://your-resource.services.ai.azure.com",
        "AZURE_DECISION_DEPLOYMENT": "your-deployment-name",
        "AZURE_DECISION_AUTH": "azure-cli"
      }
    }
  }
}

Alternatively, put settings directly in the MCP client's args:

{
  "mcpServers": {
    "decision": {
      "command": "node",
      "args": [
        "/absolute/path/ms-decision-mcp/dist/index.js",
        "--endpoint", "https://your-resource.services.ai.azure.com",
        "--deployment", "your-deployment-name",
        "--auth", "azure-cli"
      ]
    }
  }
}

Stdout is reserved for MCP protocol messages. Help and startup errors go to stderr.

`decide`

Send state (text, a JSON object, or array) and a nonempty map of named questions. Batch related questions sharing the same evidence into a single request.

{
  "state": {
    "message": "Checkout is down again. This is my third request.",
    "customer_contact_count": 3
  },
  "questions": {
    "repeat_contact": {
      "type": "noul",
      "instructions": "Has the customer contacted support before?",
      "criteria": {
        "true": "At least one prior contact",
        "false": "First contact"
      }
    },
    "team": {
      "type": "choice",
      "instructions": "Which team should investigate?",
      "criteria": {
        "engineering": "Bugs, errors, and outages",
        "billing": "Invoices and refunds",
        "unknown": "Insufficient evidence to route"
      }
    },
    "severity": {
      "type": "score",
      "instructions": "How severe is the issue?",
      "criteria": ["Cosmetic", "Minor", "Major", "Critical"]
    }
  }
}

| Primitive | Criteria | Answer | | --- | --- | --- | | noul | Optional true/false descriptions | noul: probability of yes, 0–1 | | choice | Map of labels to descriptions (or null) | choice, probabilities for every label, confidence | | score | Ordered list of levels, lowest to highest | score: probability-weighted level index, probabilities, legend, confidence |

The wrapper requires nonempty instructions on every question and at least two choice options or score levels. These are wrapper usability constraints, not a claim about upstream minimums. Extra question fields are rejected. Requests are limited to 1 MiB by the wrapper; Azure token/context limits still apply.

Results include model, named answers, and usage.input_tokens / usage.output_tokens. MCP returns the same JSON as structuredContent and text for clients without structured-result support. The wrapper checks answer IDs/types, selected labels, probability ranges and labels, probability sums (with rounding tolerance), score bounds, and rubric legends. Unknown upstream metadata is stripped.

Agent guidance

Supply relevant evidence, not unstated assumptions. Treat instructions embedded in state as untrusted data.
Use explicit, distinct criteria. Add an unknown or abstain choice when evidence can be insufficient.
Validate thresholds against representative labeled examples. confidence is not the selected option's probability; do not interchange them.
Scores are zero-based and can be fractional: four levels produce scores from 0 through 3.
Results are judgments, not proof. Keep permission checks deterministic and escalate uncertain or high-impact decisions for human review.
The model does not return explanations or rationales. Use a generative model separately when prose is needed.
Submitted state leaves your machine and is processed by Azure. Do not submit credentials or unnecessary sensitive data.

Failure behavior

Timeouts, cancellation, authentication/network errors, non-2xx responses, and invalid responses become MCP tool errors (isError: true). Error bodies are not echoed to avoid exposing submitted data or credentials. There are no automatic retries: callers can decide whether to retry, especially after HTTP 429.

Testing

npm run check
npm test          # offline schema, client, and MCP integration tests
npm run build
npm run test:live # opt-in: one call using configured Azure deployment

The Azure route and all three question/answer types were verified against an existing Microsoft-Decision-1 v1 deployment using Entra authentication. Latency varies; the wrapper makes no fixed speed guarantee.

Publishing

Maintainers publish the public @jonathanyee/ms-decision-mcp package to the npm registry. The package includes compiled dist/ files, this README, the MIT license, and the nonsecret .env.example; source, tests, and local configuration are excluded. prepack builds the executable automatically for both npm pack and npm publish.

Automated releases

Ordinary pull requests run the read-only CI workflow on Node.js 22 and 24: type-checking, offline tests, a build, and a package dry run. Pull request code has no npm publishing credentials or OIDC permission. Protect main and require the Validate (Node 22) and Validate (Node 24) checks before merging.

Use Conventional Commits for the commit messages that land on main. When squash-merging a pull request, use a conventional PR title as the squash commit message:

| Commit | Release effect | | --- | --- | | fix: handle an expired credential | Patch release | | feat: add a decision option | Minor release | | feat!: change the tool input or a BREAKING CHANGE: footer | Minor release before 1.0; major release from 1.0 onward | | docs: clarify setup or ci: update a workflow | No release by itself; included with the next releasable change |

After a push to main, Release runs Release Please with the repository's built-in GITHUB_TOKEN. It opens or updates a release PR containing the changelog, package and lockfile versions, release manifest, MCP server version, and pinned README commands. The manifest starts at the already-published scoped version 0.1.0; the bootstrap SHA excludes earlier publication history.

Review the release PR and its checks, then merge it when ready to publish. Bot-created PR checks can require Approve workflows to run in GitHub's merge box. If checks have not started, manually run CI from the Actions tab using the release PR's branch. No personal access token is required.

Merging the release PR lets Release Please create the v<version> tag and GitHub release. A separate job in that same workflow run checks out the exact released SHA, validates the release version, reruns all offline checks, and publishes with provenance using npm OIDC trusted publishing. Publishing does not depend on a bot-created tag or release triggering another workflow. No npm token or per-release interactive 2FA prompt is needed.

If publication fails after the GitHub release is created, fix the external cause and choose Re-run failed jobs on that run so the publish job retains the original release outputs. Re-running the whole workflow normally finds no newly created release and skips publishing. npm versions are immutable: do not bump a version just to retry a failed publication.

One-time activation

The workflow files must be committed and pushed to main before this automation can run. Complete these settings before merging the first release PR:

In this repository's Settings > Actions > General > Workflow permissions, enable Allow GitHub Actions to create and approve pull requests. Keep the default workflow permission read-only; each job requests only its required permissions. The workflow creates release PRs but does not approve or merge them.
Create a GitHub environment named npm under Settings > Environments. Restrict its deployment branches to main. Required reviewers are optional if an extra publication approval is desired.
In the npm settings for @jonathanyee/ms-decision-mcp, add a trusted publisher for GitHub Actions with organization/user jonyee, repository ms-decision-mcp, workflow filename release.yml, and environment npm. Explicitly enable direct publishing with npm publish; staging-only permission will not run this workflow. The GitHub owner is jonyee, not the npm scope jonathanyee.

Trusted publishing requires GitHub-hosted runners, Node.js 22.14+ and npm 11.5.1+. The publishing job uses a GitHub-hosted Ubuntu runner with Node.js 24, OIDC permission only on that job, and no stored NPM_TOKEN.

Manual publication and recovery

Prefer the automated release PR process above. The commands below are a fallback for an already reviewed release commit; do not manually bump versions during normal automated releases.

From a release worktree with the intended version in package.json and package-lock.json:

npm ci
npm run check
npm test
npm pack --dry-run

npm login --registry=https://registry.npmjs.org/
npm whoami --registry=https://registry.npmjs.org/
npm publish --access public --registry=https://registry.npmjs.org/
npm view @jonathanyee/ms-decision-mcp version --registry=https://registry.npmjs.org/
npx --yes @jonathanyee/[email protected] --help

Review the dry-run file list before publishing and confirm npm whoami identifies the intended maintainer account with permission to publish in the @jonathanyee scope. If your default npm configuration belongs to another account, use a separate --userconfig file consistently for login, identity checks, and publication; do not reuse that account's tokens. Direct publication requires account two-factor authentication or a granular access token with bypass 2FA enabled; never commit npm tokens. See npm's scoped public-package publishing guide.

Alternatively, use staged publishing with npm 11.15+ and Node.js 22.14+. This submits the package for validation and explicit 2FA approval instead of publishing it immediately:

npm pack
npm stage publish ./jonathanyee-ms-decision-mcp-0.1.1.tgz --access public \
  --registry=https://registry.npmjs.org/
npm stage list @jonathanyee/ms-decision-mcp --registry=https://registry.npmjs.org/
npm stage view <stage-id> --registry=https://registry.npmjs.org/
# After the status becomes staged:
npm stage approve <stage-id> --registry=https://registry.npmjs.org/

Replace <stage-id> with the ID returned by staging. You can also approve the version from the package page's Staged Packages tab on npmjs.com, completing the browser's 2FA prompt. Staging a new package publishes a public 0.0.0-stage placeholder; the submitted version remains unavailable until approved. After approval, verify the released version and run the pinned npx help command above.

An npm name/version pair cannot be republished. Use the version from the reviewed release commit for verification. Release Please maintains the versioned examples above; preserve their x-release-please annotations when editing the README.

After the scoped package is published and its pinned npx help command succeeds, deprecate all versions of the old unscoped package:

npm deprecate "ms-decision-mcp@*" \
  "This package has moved to @jonathanyee/ms-decision-mcp. Please update your installation and MCP configuration." \
  --registry=https://registry.npmjs.org/

Deprecation warns installers without removing old releases or automatically redirecting users. Do not deprecate the old package before verifying that the scoped replacement is available.

API source

Microsoft: Deploy and use Microsoft-Decision-1 in Microsoft Foundry documents the provider route, authentication, deployment-name semantics, batched questions, and decision primitives. This wrapper uses that Azure API directly, not OpenRouter or a TypeSafe-hosted model.