Skip to main content
Glama
magicsword-mcp

magicsword-mcp

Official

magicsword-mcp

A Model Context Protocol server for MagicSword. Lets users running Claude Desktop, Cursor, or any MCP-aware client manage MagicSword conversationally — list endpoints, query alerts, triage findings, mint enrollment tokens, and preview / commit policy changes.

The server is a thin, opinionated wrapper around the /api/public/v1/* customer API exposed by the Magic Portal. It runs on the user's machine, holds an msk_… API key, and speaks MCP over stdio.

For Microsoft Copilot Studio, use the portal's hosted Streamable HTTP connector with OAuth instead. Hosted access must be enabled by your MagicSword administrator; the npm package remains a local stdio server.

Quick start

Free to use. MagicSword MCP and the customer API are available on the Free plan, as well as Enterprise. Get started with a Free account and an API key; no Enterprise subscription is required. Your key's scopes and plan determine which operations are available; strict policy mode requires Enterprise.

Claude Desktop installer

For Claude Desktop on macOS or Windows, download magicsword-mcp.mcpb from GitHub Releases. The installer is included starting with version 0.1.4. If that release is not available yet, use terminal setup below.

  1. Generate an API key in Magic Portal → Settings → API Keys. Start with read scopes for endpoints, alerts, and policies.

  2. In Claude Desktop, open Settings → Extensions → Advanced settings → Install Extension…, then select the downloaded .mcpb file.

  3. Review the extension and enter your API key in its secure configuration field. Claude stores this sensitive field using the operating system's secure storage. The installer does not save a separate MagicSword key file.

  4. Start a new conversation, then ask MagicSword to call whoami followed by list_endpoints. Confirm the organization and scopes.

The installer includes the server and production dependencies and uses Claude Desktop's bundled Node runtime (22+). It requires no npm installation or JSON editing. Its SHA256 checksum is published beside the installer. A privately downloaded extension must be updated by installing a newer .mcpb file; automatic directory updates require a reviewed directory listing.

Terminal setup

Requires Node.js 22+, an installed MCP client, and a MagicSword API key from Magic Portal → Settings → API Keys.

Recommended: install and connect your client in one command. Setup prompts for your key privately and lets you choose Claude Desktop, Codex, Claude Code, or Cursor:

npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure

Already know your client? Run the matching one-liner:

Client

Install and configure

Claude Desktop

npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client claude-desktop

Cursor

npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client cursor

Claude Code

npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client claude-code

OpenAI Codex

npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client codex

Prefer your client's own registration command? After saving your key locally, these also work without a global server install:

codex mcp add magicsword --env MAGICSWORD_BASE_URL=https://www.magicsword.io -- npx -y @magicsword-io/magicsword-mcp
claude mcp add --scope user --transport stdio magicsword --env MAGICSWORD_BASE_URL=https://www.magicsword.io -- npx -y @magicsword-io/magicsword-mcp

These are also a fallback when automatic registration cannot launch a client's CLI on Windows. Desktop launch still requires Node/npx to be available to that client; the recommended setup uses absolute paths instead.

Install buttons: Cursor and VS Code

First save your API key locally (once per machine):

npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client manual

Then click your client's button and approve its installation prompt:

Install in Cursor Install in VS Code Install in VS Code Insiders

These buttons register a local npx server pointing at production. They contain no API key; the server reads ~/.magicsword/mcp.json. They require npx on the client's PATH. If a desktop app cannot find Node or npx, use the recommended setup above for absolute launch paths, or copy the absolute command and args printed by configure --client manual into its configuration.

Manual JSON fallback

After saving your key above, merge this entry into Claude Desktop's claude_desktop_config.json or Cursor's ~/.cursor/mcp.json, preserving your other servers:

{
  "mcpServers": {
    "magicsword": {
      "command": "npx",
      "args": [
        "-y",
        "@magicsword-io/magicsword-mcp"
      ],
      "env": {
        "MAGICSWORD_BASE_URL": "https://www.magicsword.io"
      }
    }
  }
}

For VS Code / Insiders, run MCP: Open User Configuration and merge this configuration (VS Code uses servers, not mcpServers):

{
  "servers": {
    "magicsword": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@magicsword-io/magicsword-mcp"
      ],
      "env": {
        "MAGICSWORD_BASE_URL": "https://www.magicsword.io"
      }
    }
  }
}

Restart your client or start a new session, then ask it to call whoami and list_endpoints. Both must succeed to verify authentication and read access.

The official MCP Registry identifier is io.github.magicsword-io/magicsword-mcp. Client-specific details follow below.

Related MCP server: Phosphor

Configure

magicsword-mcp configure

Setup asks for an API key with hidden input (mint one in Magic Portal → Settings → API Keys) and which client to connect: Claude Desktop, Codex, Claude Code, Cursor, or manual configuration. It saves the key only in ~/.magicsword/mcp.json (mode 600). The Portal defaults to https://www.magicsword.io, replacing any saved preview origin. A custom origin requires an explicit --base-url option.

Setup registers the selected client at its standard user-level location, preserves other servers and settings, and creates a private backup of existing client configuration. It updates an existing magicsword entry for JSON clients and Codex. Claude Code requires that name to be available; use its own MCP commands to remove an old registration before retrying. Codex and Claude Code registration require their respective CLIs to be installed.

To choose a client directly, or reuse a saved key without prompting:

magicsword-mcp configure --client codex
magicsword-mcp configure --non-interactive --client claude-desktop
magicsword-mcp configure --client cursor --client-config /path/to/mcp.json

The launch entry uses absolute Node and installed server paths so desktop apps can start it without inheriting your terminal's PATH. Re-run setup if you move your Node installation or install the package under a different Node version. Manual setup prints a credential-free launch entry for other local stdio MCP clients. Unattended setup without --client writes only the MagicSword file.

Restart the selected client or start a new session to load magicsword and its 26 tools. Ask it to call whoami and then list_endpoints to verify access; discovery alone does not verify API-key scopes. Claude Desktop logs are at ~/Library/Logs/Claude/mcp*.log on macOS. Browser-only clients require a remote MCP transport; this package provides a local stdio server.

If you need a per-client override instead of ~/.magicsword/mcp.json, set MAGICSWORD_API_KEY and optionally MAGICSWORD_BASE_URL in that MCP host's environment. Keep API keys out of shared config snippets and screenshots.

Microsoft Copilot Studio

Use the hosted connector shown at Magic Portal → Settings → API Keys → MCP setup, or on your portal's /mcp page. If that environment does not show a connector URL, hosted access has not been enabled there. A local npm install cannot make the server reachable from Copilot Studio.

  1. In Copilot Studio, open your agent's Tools → Add a tool → New tool → Model Context Protocol.

  2. Set Server name to MagicSword. For Server description, use: Investigate MagicSword endpoints, alerts, policies, and intelligence using the permissions you approve. Paste the exact enabled portal connector URL into Server URL.

  3. Choose OAuth 2.0 → Dynamic discovery, then Create → Next.

  4. Select Create a new connection, sign in to MagicSword, choose your organization, and approve read permissions first. Select Add to agent.

  5. In the added tool's Authentication settings, choose User authentication (End user credentials) and use a supported channel. Each person must connect with their own MagicSword account rather than sharing the author's grant.

  6. In the agent's test chat, ask:

    Use MagicSword to call whoami, then list_endpoints. Show the connected organization, my approved permissions, and my devices. Do not make any changes.

Copilot Studio uses Streamable HTTP. Do not select API-key authentication or paste a Settings API key into the hosted connector; it accepts OAuth access tokens. Each user should connect with their own account. Your Power Platform data policies must allow the connector.

See the Copilot Studio connection and verification guide and Microsoft's setup documentation. Native tenant verification is required before announcing tested compatibility. See Microsoft's user-authentication guidance for supported channels and connection behavior.

Tools

Tool

What it does

whoami

Returns organization, key id, and scopes. Always call first when troubleshooting.

list_endpoint_groups

Lists organization computer groups and parent group IDs for assignment previews. Requires endpoints:read.

list_endpoints

Lists endpoints with optional platform / status / hostname-glob filtering.

show_endpoint

Fetches one endpoint with OS, policy, compliance, upgrade, heartbeat, and AMSI details.

list_agent_releases

Lists available agent versions and per-platform latest releases.

find_alerts

Searches alerts by severity / ack state / since / hostname / MITRE technique.

list_events

Searches Investigate events by name, filename, path, hash, publisher, computer, or package family, with type/status/policy/endpoint/time filters.

triage_alert

Fetches one alert directly with triggering events, metadata, and file context; optionally acknowledges or dismisses it.

list_policies

Lists policies with current version + mode.

create_policy

Creates a new empty audit policy for Windows, macOS, or Linux without assigning devices. Requires policies:write.

clone_policy

Copies a policy into an independent audit policy with its rules, settings, intelligence links and collection links; no computers assigned.

download_policy

Downloads the current Windows policy as a complete WDAC XML ZIP or AppLocker XML; local MCP saves to Downloads or a requested directory. Requires policies:read and Enterprise agentless export.

show_policy

Shows one policy by id.

manage_policy_rules

Lists rules or adds explicit / event-derived rules to a policy by id or name. Avoid explicit flat hash rules for Windows WDAC.

apply_policy_to_endpoints

Previews assignment to computer IDs, hostname matches, or groups; a server-issued confirmation_token commits the approved snapshot.

flip_to_enforcing

Two-step preview/confirm flip with a server-issued one-time confirm token. Safety-critical.

list_intel_sources

Discovers enabled global and organization-owned intel sources and IDs, with platform and pagination filters.

list_customer_intel_feeds

Lists private intel feeds or feed items.

manage_customer_intel_feed

Creates or updates feeds; deletion requires a preview followed by confirm=true.

manage_customer_intel_item

Edits feed items; deletion requires a preview followed by confirm=true.

upsert_customer_intel_items

Adds indicators extracted from reports into a private feed.

manage_policy_intel_sources

Lists, attaches, or detaches intel feeds on a policy.

upgrade_endpoints

Previews upgrades for an endpoint selection; confirm=true queues them after approval.

request_endpoint_checkin

Queues an endpoint check-in command.

mint_enrollment_token

Mints a one-time agent enrollment token.

agent_install_instructions

Returns the install one-liner for macOS / Linux / Windows. No API call.

Write tools require matching Customer API scopes in Magic Portal, such as alerts:write, policies:write, endpoints:write, or intel:write. Event review uses alerts:read; turning selected events into policy rules uses policies:write. Cloning requires policies:write; group discovery requires endpoints:read; assignment preview and commit require both policies:write and endpoints:read. Policy download uses policies:read and requires Enterprise agentless export access.

Tools publish standard MCP safety annotations. Read-only discovery tools are marked read-only and idempotent; enforcement, deletion, policy assignment, rule changes, and agent upgrades are marked destructive so MCP clients can apply appropriate confirmation UX. Local download_policy is marked as a non-destructive write because it creates a file; hosted download is read-only and returns a resource.

Downloading policies for agentless deployment

Ask “Download my Finance policy as WDAC and put it in Downloads” or “Download its AppLocker XML to Downloads.” The client finds the Windows policy with list_policies, then calls:

{ "policy_id": "<Windows policy UUID>", "format": "wdac" }

Use "format": "applocker" for AppLocker. With the local stdio server, files go to ~/Downloads on the machine running the MCP server. To choose another folder:

{
  "policy_id": "<Windows policy UUID>",
  "format": "applocker",
  "output_directory": "~/Downloads/Finance"
}

Absolute Windows paths work too (escape backslashes in JSON). The directory is created if needed. Downloads use new filenames, so existing files are preserved. The result includes the saved path, SHA256, byte count and policy version ID. A failed or invalid response is not saved. Downloading does not install, assign, activate, or change the policy's audit/enforcing mode.

WDAC downloads contain all generated XML files for that version: base and supplementals when applicable, plus signer, customer and intelligence block policies. These are XML source files, not compiled .cip files. Review and compile them with Windows tooling before deployment. AppLocker is the same blocklist projection used by the Portal's Compatible Windows download; it cannot reproduce WDAC strict allowlisting. Review its returned projection summary for omitted rules and weaker or broader matches before deploying it. Policies with no compatible AppLocker rules return an error instead of a clearing policy.

Downloads require policies:read and Enterprise agentless deployment access. The API exports the current Windows version and rejects a change detected while preparing it; macOS and Linux exports are not supported by this tool.

Hosted MCP: download_policy returns an attached resource for the client to save, with the same version/hash metadata. It cannot write to your computer and does not accept output_directory. Client attachment support varies. Hosted attachments are limited to 2 MiB so the base64 response fits the hosting limit; use local MCP or the authenticated API for larger artifacts. API/local WDAC archives include up to 4,096 XML files and are capped at 32 MiB (30 MiB XML). Every generated member must fit these bounds; an over-limit export fails as a whole rather than dropping files. AppLocker exports must be below 4,000,000 bytes. Nothing is extracted or executed by the tool.

Direct API: agentless customers can call either endpoint with a Customer API key; no installed MagicSword agent is required:

Request

Response

GET /api/public/v1/policies/{policyId}/download?format=wdac

Complete WDAC XML ZIP; format defaults to wdac.

GET /api/public/v1/policies/{policyId}/download?format=applocker

AppLocker XML with projection summary headers.

For example, with MAGICSWORD_API_KEY set privately and POLICY_ID set to your Windows policy UUID, create a new download directory and fetch the archive:

download_dir="$(mktemp -d "$HOME/Downloads/magicsword-policy.XXXXXX")"
curl --fail --silent --show-error \
  --header "Authorization: Bearer $MAGICSWORD_API_KEY" \
  --dump-header "$download_dir/headers.txt" \
  --output "$download_dir/policy.zip" \
  "https://www.magicsword.io/api/public/v1/policies/$POLICY_ID/download?format=wdac"

For AppLocker, change format=applocker and the output name to policy.xml. Check the command succeeds before using its output. Headers include X-MagicSword-Policy-Version-ID, X-MagicSword-Policy-Xml-File-Count, and X-MagicSword-Policy-Artifact-Format; AppLocker also includes X-MagicSword-AppLocker-Projection-Summary. Responses are private, streamed attachments with Cache-Control: no-store. No public Storage URL or API key is included in the downloaded artifact.

The API uses the same generators as the Portal's download buttons. Agent-delivery artifacts may also be cached in Supabase Storage; this customer export generates from the current policy rows without writing to that cache or changing policy metadata. Existing stored policy GUID metadata is reused when available; an export is not a device synchronization protocol.

Creating a policy

Ask “Create a Windows policy named Block LOLBAS.” The agent calls:

{
  "name": "Block LOLBAS",
  "platform": "windows",
  "policy_mode": "blocklist"
}

create_policy creates a new empty policy and version 1 in audit mode in the organization selected by your API key or connection. It returns the policy ID for subsequent rule and intelligence-source additions. It does not assign devices, make the policy a default, attach feeds, or switch enforcement on. Existing organization collection settings can be inherited.

The name must contain 1–200 characters. platform is required; policy_mode defaults to blocklist. Windows/macOS strict mode requires Enterprise; Linux strict is unsupported. Free accounts can create blocklist policies. Creation requires policies:write; later list/show calls also require policies:read.

For “Create Block LOLBAS and attach LOLBAS”, first create the policy, then use list_intel_sources to resolve the feed and manage_policy_intel_sources with the returned policy ID. Use manage_policy_rules for explicit or selected-event rules. Creation is a separate operation from building and deploying the policy. Every successful create call makes a new policy, including repeated names. Writes are not automatically retried: if the connection drops or the response cannot be verified, list policies before trying again.

Deploy the Portal policy-creation route and migration before using this tool. Hosted Portal MCP includes the tool when the connection has policy write scope.

Cloning and assigning to computers or groups

You can ask: “Clone Workstations as Finance pilot, then assign the copy to FINANCE-01,” “assign it to these three computers,” or “assign it to the Finance group.” The client discovers the source policy and targets, creates a copy, and shows an assignment preview before committing after your approval.

Call clone_policy with the source ID from list_policies and a new name:

{ "policy_id": "<source-policy-uuid>", "name": "Finance pilot" }

The returned policy.id is the new policy ID. The copy starts at version 1 in audit mode even if the source enforces. It preserves supported policy and version settings, all rules (including signer/file-attribute relationships), intelligence links and sync watermarks, and analytics collection links. Feeds and collections remain shared; their underlying data is not duplicated. The source, device assignments, organization defaults, version history, and generated policy artifacts are not copied or changed. If your plan cannot preserve the content, the request fails instead of silently removing protections. A clone may inherit the organization's collection settings, as with other new policies.

Cloning alone assigns no computers. Find device IDs using list_endpoints, or get group IDs and hierarchy using list_endpoint_groups:

{ "limit": 100, "offset": 0 }

Group pages include id, name, parent_group_id, and description, with total, limit, and offset. Maximum page size is 500; page through the full list when resolving a group name. Names must resolve unambiguously before use.

Preview with apply_policy_to_endpoints using one selector. Replace the placeholders below with real UUIDs and use the newly returned clone ID:

{ "policy_id": "<cloned-policy-uuid>", "endpoint_ids": ["<computer-uuid>"] }
{
  "policy_id": "<cloned-policy-uuid>",
  "endpoint_ids": ["<computer-1-uuid>", "<computer-2-uuid>", "<computer-3-uuid>"]
}
{
  "policy_id": "<cloned-policy-uuid>",
  "group_ids": ["<finance-group-uuid>"],
  "include_descendants": true
}

You can also use hostname_pattern, such as FINANCE-*, with an optional platform filter. Select at most 50 groups and 500 resolved computers per preview. Subgroups are included by default; set include_descendants=false for direct members only. Overlapping groups resolve each computer once. Foreign, missing, incompatible-platform, agentless, or uninstalled targets reject the whole request. An empty or oversized selection is not deployed.

The preview shows the exact computers, previous assignments, policy status and mode, plus a five-minute confirmation token. Assignment replaces the previous desired policy set; it is not additive. An audit copy can remove existing blocking protection, and assigning an enforcing policy can cause applications to be blocked. Review that change with the human before committing.

After approval, call the same tool with only the policy ID and the returned confirmation.token:

{
  "policy_id": "<cloned-policy-uuid>",
  "confirmation_token": "<token-from-preview>"
}

The server binds approval to the key, organization, policy content and concrete computer snapshot. Expired/reused tokens, changed policy content or previous assignments, and newly ineligible computers require a fresh preview. Membership changes do not expand the approved set. This is a one-time assignment to members at preview time, not a persistent rule for computers added later.

Success means policy_id and desired_policy_ids were saved atomically for all targets, pending agent check-in; it does not prove device installation. Use show_endpoint and subsequent check-ins to inspect actual deployment. This flow does not itself change the policy's audit/enforcement status.

confirm=true alone no longer authorizes this tool. Existing callers must use the server token; sending selectors with a token is rejected. Writes are never retried automatically. If a clone or assignment response is missing/malformed, reconcile with list_policies or endpoint desired state before retrying: the operation may already have committed.

The customer API exposes the same workflow:

Method

Route under /api/public/v1

Body / purpose

POST

/policies/{sourceId}/clone

{ "name": "Finance pilot" }; returns 201 with the new audit policy, source IDs and copied counts.

GET

/endpoint-groups

limit and offset query parameters; tenant-scoped group discovery.

POST

/policies/{policyId}/assignment-preview

One selector and its options; returns concrete targets and a confirmation token.

POST

/policies/{policyId}/assign

{ "confirmation_token": "..." }; returns desired-state count and endpoint IDs, assignment_status=pending_checkin.

Deploy the Portal migrations and routes first. Hosted MCP includes these calls after that deployment; then merge the MCP PR to trigger its automatic npm release. Upgrade existing local MCP installs and restart their client to load the new tools. Do not point a new client at a Portal that lacks these routes.

Adding and listing policy rules

manage_policy_rules accepts one input source per add: rules for explicit rules, or event_ids for rules derived from telemetry. Each accepts 1–100 items. Use policy_id, or policy_name with an optional platform to resolve a name. The policy must already exist; ambiguous names require an ID or platform.

For example, to block the filenames from issue #5 on a Windows blocklist policy:

{
  "action": "add",
  "policy_name": "Workstations",
  "platform": "windows",
  "rules": [
    { "type": "filename", "value": "rustdesk.exe", "status": "blocked" },
    { "type": "filename", "value": "mshta.exe", "status": "blocked" },
    { "type": "filename", "value": "wscript.exe", "status": "blocked" }
  ]
}

Explicit rules use type and value, with optional status (defaults to blocked). Unknown rule fields are rejected; rule_type / file_name are not substitutes. Filename and path values must be non-empty strings or supported value objects. Publisher values require publisherName (or publisher) and a valid tbsHash (or tbs_hash / certificate_thumbprint). Optional rule metadata includes name, mode, version bounds, signer/file-attribute references, package_version, and target_platforms. The Portal validates whether a rule can be enforced on the resolved policy's platform. Flat Windows WDAC hashes remain unsupported; use telemetry-derived rules or private intelligence feeds.

For telemetry, use event_ids with top-level status (defaults to allowed) and an optional type override. Top-level status and type cannot be used with explicit rules; set those fields on each rule instead.

Adds preserve existing rules and intelligence-source links. Matching customer rules with a different status are updated; rules already at the requested status are reported as unchanged duplicates. Feed-owned rules retain their provenance; unsupported conflicts with a feed rule return an API error. The tool reports the Portal's actual added_count, updated_count, and duplicate_count, and retains its version information in structured output. An unchanged duplicate batch reports “No changes needed.” Unexplained zero changes or malformed responses are errors: inspect the current rules/version before retrying because the request may have created a version. Writes are never retried automatically. For event-derived batches, a count total smaller than the number of unique requested events is also an error: some events may not have produced rules. Successful changes and version details remain available in structured output.

To verify the current version's stored rules:

{ "action": "list", "policy_id": "<policy UUID>", "limit": 500, "offset": 0 }

List requires an ID and policies:read. It returns stored customer rules and materialized feed rules for the current version, with total, limit, and offset. The default page size is 100, maximum 500; increase offset until all total rows have been read. An empty page does not describe other versions or indicators that have not been materialized into this version.

Example transcript

User:   Show me unack'd critical alerts from the last 24h.
Claude: [calls find_alerts severity=critical acknowledged=false since=...]
        → 3 critical alerts on 2 endpoints. Want me to triage the top one?

User:   Yes.
Claude: [calls triage_alert]
        → Evidence chain: cmd.exe spawned by winword.exe with -enc base64.
          MITRE T1059.001. Acknowledge with comment "office macro chain — under investigation"?

User:   Yes, and extract the IOCs from this report into our SOC feed.
Claude: [calls upsert_customer_intel_items]
        → Upserted 47 indicators into feed 8d6...

User:   Show me audited or blocked events from the last day.
Claude: [calls list_events hours=24 status=audited,blocked]
        → 31 events. Here are the file paths, publishers, and hashes.

User:   Allow the first 5 on the Workstations policy.
Claude: [calls manage_policy_rules action=add policy_name=Workstations event_ids=[...] status=allowed]
        → Created a new policy version with 5 allowed rules.

Investigate events and attach intelligence

Ask “Show audited filename events for image.png from the last week.” The agent calls list_events with type=filename, status=audited, file_name=image.png, and hours=168. file_name is an exact, case-sensitive match, including literal punctuation. For broader discovery, q searches the same seven fields as Portal Investigate: name, filename, path, hash, publisher, computer, and package family. It is a case-insensitive literal substring search accepting up to 120 characters, including Unicode, quotes, commas, parentheses, and Windows backslashes. %, _, and * are literal characters; wildcard and field-query syntax are not supported. Control characters are rejected. A blank query applies no text filter. Filters combine, so type=filename selects filename events rather than all event types that happen to include a filename. Omit type to search across event types.

For example, “Find events from publisher Contoso, Inc. (R&D)” uses list_events q="Contoso, Inc. (R&D)". To block a file found in those results, review the returned IDs and rule context, choose the intended rule type, and call manage_policy_rules action=add policy_id=... event_ids=["<selected-event-id>"] status=blocked type=filename. Search does not change policies or automatically block every match. Searching a publisher does not imply blocking that publisher; the selected rule type determines what is blocked. Event IDs can also derive other supported rules when appropriate, subject to Portal platform validation.

The default window is 24 hours with statuses audited,blocked; use since for an explicit lower bound. The window uses the last observation time, falling back to creation time. Results include file paths, publishers, hashes, computers, occurrence counts, rule context, and pagination. Use limit and offset for additional pages. This is normalized event data rather than a raw event log.

For “Attach LOLDrivers intel to my Windows policy”, the workflow is:

  1. list_policies platform=windows identifies the policy name and ID.

  2. list_intel_sources platform=windows returns available source names and IDs. It defaults to enabled sources; use is_enabled=false to inspect disabled ones. Use limit (up to 100) and offset to discover additional pages.

  3. manage_policy_intel_sources action=list policy_id=... shows current attachments.

  4. After identifying the intended policy and sources, use manage_policy_intel_sources action=attach policy_id=... source_ids=[...]. The result reports new attachments and sources already attached separately.

  5. List the policy attachments again to verify the result.

Source discovery requires intel:read, policy discovery/attachment listing requires policies:read, and attachment requires policies:write. Source visibility does not guarantee premium entitlement; the API checks it when attaching. Attachments create a policy version and take effect as endpoints receive it.

Configuration sources, in order of precedence

  1. MAGICSWORD_API_KEY / MAGICSWORD_BASE_URL env vars (set by the MCP host).

  2. ~/.magicsword/mcp.json (or $MAGICSWORD_CONFIG).

  3. Default base URL https://www.magicsword.io.

Optional transport controls are MAGICSWORD_REQUEST_TIMEOUT_MS (default 30 seconds), MAGICSWORD_RESPONSE_MAX_BYTES (default 4 MiB), and MAGICSWORD_GET_RETRIES (default 2, maximum 3). Only idempotent GET requests are retried; write actions are never retried automatically.

Safety notes

  • flip_to_enforcing is two-step. The first call returns a server preview and one-time confirmation token; you must show the preview to a human and pass the token back to commit. Tokens are short-lived and single-use. This is not MFA or server-verified human approval: the same API key can perform both calls. The MCP host must obtain human approval before committing. A commit response must confirm success for the requested policy and identify its new version; otherwise use show_policy to verify the outcome before retrying. Success confirms the server policy version change. Endpoint enforcement takes effect through check-in; this response does not confirm endpoint delivery.

  • Intel attachments use enabled sources in batches of at most 60. Capture requests share the API key creator's rate budget with the Portal UI. A 429 response includes retry guidance; wait before submitting another batch. Attachment summaries report newly attached and already-attached counts separately. Invalid or incomplete counts require listing attachments before retrying.

  • Fleet changes and deletion are explicit. Endpoint upgrades and private-intel deletion require a preview followed by an approved confirm=true call. Policy assignment requires a concrete preview followed by its server-issued confirmation_token; confirm=true alone cannot commit an assignment.

  • Windows WDAC policy edits should not use explicit flat file hashes. Use manage_policy_rules with event_ids when approving audit events so the Portal can derive supported path / publisher / filename rules, or use upsert_customer_intel_items for hash, AuthentiHash, page-hash, and TBS intelligence in a private feed.

  • Secrets stay on the user's machine. The MCP server is a local stdio process; the API key is read from ~/.magicsword/mcp.json (mode 600) or an env var passed by the MCP host. Nothing is sent off-machine except the requests to the configured MAGICSWORD_BASE_URL.

  • Remote Portal URLs must use HTTPS. Plain HTTP is accepted only for localhost development. Configured URLs cannot contain credentials, paths, query strings, or fragments.

Develop

npm install
npm run build
npm test
npm run test:package
npm run release:verify
node dist/index.js --version

Tests validate --help, --version, production-default migration, private client registration, preservation and rollback, configure validation, secret redaction, modern and legacy MCP startup, focused mutation confirmation, retry and timeout semantics, response-size bounds, malformed responses, write non-retry behavior, all 26 tools' HTTP contracts and confirmation flows over modern and legacy stdio, explicit filename round trips, invalid rule shapes, ambiguous inputs, actual mutation counts, and npm pack contents. test:package installs a production-only tarball and checks the installed CLI and MCP tool discovery; release:verify checks all release metadata. Merging to main now creates the next patch release after main CI succeeds and automatically publishes npm, MCP Registry metadata and the desktop installer. No manual version bump or npm command is needed. See docs/RELEASING.md for checks, settings and recovery.

An opt-in live policy test is also available after npm run build:

MAGICSWORD_LIVE_TEST=1 MAGICSWORD_TEST_POLICY_ID="<disposable-policy-uuid>" node scripts/live-policy-rules.mjs

Use your private saved credentials or MAGICSWORD_API_KEY; do not put keys in commands or shared logs. This test writes policy versions and requires a disposable, unassigned Windows audit policy named with the prefix MCP issue 5 disposable verification, seeded with more than 1,000 baseline rules with at least one attached intelligence source, and no existing rustdesk.exe, mshta.exe, or wscript.exe customer rules. It verifies append behavior, pagination, intelligence-source preservation, repeat adds, status updates, invalid inputs, and event-derived filenames when suitable telemetry exists. It also exercises discovery and read tools through stdio. It prints assertion names/counts only. Remove the disposable policy and its versions after inspection; the test does not create or delete the fixture. Set MAGICSWORD_TEST_PROTOCOL=legacy to exercise the legacy live transport.

With the same disposable policy and opt-in environment, run node scripts/live-demo-tools.mjs to check assignment, upgrade, and enforcement previews, all three platforms' installer instructions, and a disabled temporary feed's create/update/upsert/list/item-delete/attach/detach/feed-delete flows. The feed is removed in finally; the policy fixture still requires manual cleanup. These checks never commit endpoint assignments, upgrades, or enforcement. Actual endpoint commands, enrollment tokens, and alert acknowledgements/dismissals are covered by the local HTTP fixtures.

Available Tools

26 tools
agent_install_instructionsShow the MagicSword agent install one-liner for a platformA
Read-onlyIdempotent

Returns the install + enroll commands for the MagicSword agent on a given platform. No API call. Useful when the LLM is helping a user onboard a new endpoint and wants to hand them the exact one-liner.

Inputs: platform (required).

apply_policy_to_endpointsPreview or confirm a policy assignmentA
Destructive

Requires policies:write and endpoints:read. Preview exactly one selector: endpoint_ids for one/many computers, hostname_pattern, or group_ids. Groups include current subgroup members by default, capped at 500 eligible computers; no future-member binding. Show the concrete computers, policy status/mode and replacement warning to the human. After approval call again with ONLY policy_id and confirmation_token from that preview. confirm=true alone cannot commit. The one-time server token freezes the target IDs; stale policy/assignments or ineligible computers reject the whole operation. This replaces desired assignments and may remove existing protections or schedule an enforcing policy. Success means desired state is saved, not that computers have installed it. Never automatically retry writes.

Inputs: policy_id (required), confirm, platform, group_ids, +4 more.

clone_policyClone a MagicSword policyA

Copies the current version of a policy into a new, independent policy with the requested name. Preserves supported rules, settings, intelligence source links and collection links; starts at version 1 in audit mode. Does not assign devices, change the source, make a default, or enable enforcement. Requires policies:write and access to all copied content. Use apply_policy_to_endpoints with the returned policy ID to preview a later assignment. Never automatically retry cloning: list policies if the outcome is uncertain.

Inputs: name (required), policy_id (required).

create_policyCreate a MagicSword policyA

Creates a new empty policy in the authenticated organization with version 1 in audit mode. Requires a name, platform, and policies:write. Defaults to blocklist; strict requires Enterprise and is supported only for Windows/macOS. Does not add rules, attach feeds, make it the default, assign devices, or enable enforcement. Use the returned policy ID with manage_policy_rules and manage_policy_intel_sources to build the policy. Each successful call creates a new policy, even with the same name. If the outcome is uncertain, list policies before retrying.

Inputs: name (required), platform (required), policy_mode.

download_policyDownload a generated Windows policyA

Download the current Windows policy as a WDAC XML ZIP (format=wdac, default) or compatible AppLocker XML (format=applocker). Requires policies:read and Enterprise agentless deployment access. Saves on the machine running this local MCP server, in ~/Downloads by default or an explicitly requested absolute output_directory. Creates a new file without overwriting existing files. Returns the saved path, SHA256, version and byte count. AppLocker is a blocklist projection: review omitted rules before deployment. Preserves audit/enforcing mode; downloading does not install, assign, compile or enforce a policy. Never execute the downloaded file.

Inputs: policy_id (required), format, output_directory.

find_alertsFind MagicSword alertsA
Read-onlyIdempotent

Search MagicSword alerts by severity, ack state, time window, hostname, or MITRE technique. All filters run server-side before pagination, so total and page counts describe the actual result set. Use this for triage queries like "unack'd critical alerts in the last 24h".

Inputs: limit, since, offset, hostname, +3 more.

flip_to_enforcingFlip a policy from audit to enforcingA
Destructive

Promotes a MagicSword policy from audit to enforcing mode through the Portal server confirmation flow. First call without confirmation_token to get readiness, blockers, endpoint count, and a one-time token. Show the preview to the human. Second call with confirmation_token to commit. Requires policies:write. This is two-step API confirmation, not MFA: the same API key can perform both calls. Human approval must be obtained by the MCP host.

Inputs: policy_id (required), confirmation_token, acknowledge_blockers.

list_agent_releasesList MagicSword agent releasesA
Read-onlyIdempotent

Lists available MagicSword agent releases and per-platform latest markers before an upgrade is queued. Requires endpoints:read.

Inputs: latest, platform.

list_customer_intel_feedsList private intelligence feedsA
Read-onlyIdempotent

Lists private intelligence feeds and, optionally, a page of items for one feed. Requires intel:read.

Inputs: limit, offset, feed_id.

list_endpoint_groupsList computer groupsA
Read-onlyIdempotent

Lists paginated endpoint groups in the authenticated organization, including their parent group IDs. Requires endpoints:read. Use selected group IDs with apply_policy_to_endpoints to preview current members (including subgroups by default). Group assignment is a one-time snapshot, not an automatic rule for future members.

Inputs: limit, offset.

list_endpointsList MagicSword endpointsA
Read-onlyIdempotent

Lists endpoints (devices) enrolled in the MagicSword org. Filter by platform (windows/macos/linux), status, or hostname pattern (glob: "*", "?"). All filters run server-side before pagination. Returns up to limit endpoints (default 100, max 500). Use this to find endpoint IDs for other tools.

Inputs: limit, offset, status, platform, +1 more.

list_eventsInvestigate MagicSword audit/block eventsA
Read-onlyIdempotent

Searches normalized Investigate events across name, filename, path, hash, publisher, computer, and package family, with optional type, status, policy, and endpoint filters. For “show filename audit events for image.png”, use type=filename, status=audited, file_name=image.png. Defaults to audited and blocked events over the last 24 hours, based on when they were last observed. Returns file paths, publishers, hashes, endpoint names, occurrence counts, timestamps, and rule context without raw telemetry. Search is read-only. To create rules, review the results and pass selected event IDs to manage_policy_rules with an explicit status and optional rule type. Requires alerts:read.

Inputs: q, type, hours, limit, +7 more.

list_intel_sourcesList available intelligence sourcesA
Read-onlyIdempotent

Discovers global and organization-owned intelligence sources and their IDs for attaching to a policy. Returns enabled sources by default; is_enabled=false lists disabled sources. Filter by the policy platform. Includes creation, update, sync, and last successful collection check timestamps when available; unknown dates remain unknown. Use list_policies to find the policy ID, then manage_policy_intel_sources action=list to inspect attachments or action=attach with the selected source_ids. Premium sources may require a paid plan. Requires intel:read.

Inputs: limit, offset, platform, is_enabled.

list_policiesList MagicSword policiesA
Read-onlyIdempotent

Lists policies in the MagicSword org, including each policy's current published version (name, version, status, policy mode). Filter by platform if you only care about windows / macos / linux. The current_version block tells you status (audit/enforcing/disabled) separately from policy_mode (blocklist/strict).

Inputs: platform.

manage_customer_intel_feedCreate, edit, or delete a private intel feedA
Destructive

Creates, updates, or deletes private intelligence feeds. Organizations are limited to 3 feeds. Requires intel:write.

Inputs: action (required), name, confirm, feed_id, +3 more.

manage_customer_intel_itemEdit or delete a private intel feed itemA
Destructive

Edits or deletes one item in a private intelligence feed. Requires intel:write.

Inputs: action (required), feed_id (required), item_id (required), item, +1 more.

manage_policy_intel_sourcesList, attach, or detach intel feeds on a policyA
Destructive

Lists, attaches, or detaches global/customer-owned intel feeds on a policy current version. First use list_policies to find policy_id and list_intel_sources to discover source IDs for that platform. Customer feeds only affect endpoints in that org with the feed attached. Attach/detach changes the policy version; show the selected policy and sources to the user before making the requested change. List requires policies:read; attach/detach require policies:write.

Inputs: action (required), policy_id (required), source_id, source_ids.

manage_policy_rulesList or add policy rulesA
Destructive

Lists rules stored on the current policy version, including materialized feed rules, or appends/updates explicit or event-derived rules while preserving existing rules and feed links. Use event_ids with status=allowed for “allow all these audit events on my policy”; the Portal will derive supported policy rules when possible. Use list_events with q to find events across supported search fields, then pass only the selected IDs here; search terms are not rule values. Do not add explicit flat file-hash rules for Windows WDAC. Requires policies:read for list and policies:write for add.

Inputs: action (required), type, limit, rules, +6 more.

mint_enrollment_tokenMint a MagicSword agent enrollment tokenA

Mints a one-time enrollment token used to register a new MagicSword agent against the org owning the API key. The returned token is bearer-equivalent for enrollment — surface it to the human and instruct them to use it within the TTL. Default TTL is 1 hour; min 5 minutes; max 24 hours.

Inputs: ttl_seconds.

request_endpoint_checkinRequest endpoint check-inA

Queues a check-in command for one endpoint. Requires endpoints:write.

Inputs: endpoint_id (required).

show_endpointShow a single MagicSword endpointA
Read-onlyIdempotent

Fetches one endpoint directly by UUID with OS, architecture, policy, compliance, agent version, upgrade state, heartbeat, and AMSI details. Requires endpoints:read.

Inputs: endpoint_id (required).

show_policyShow a single MagicSword policyA
Read-onlyIdempotent

Returns the active version + status for one policy by id.

Inputs: policy_id (required).

triage_alertTriage a single MagicSword alertA
Destructive

Fetches one alert directly by id and returns its severity, endpoint, MITRE mapping, triggering events, file context, and metadata for analyst review. Optionally acknowledges or dismisses it.

Inputs: alert_id (required), ack, dismiss, ack_comment, +1 more.

upgrade_endpointsQueue MagicSword agent upgradesA
Destructive

Previews or queues agent upgrades for one endpoint, explicit endpoint IDs, all endpoints on a platform, or endpoints matching a hostname glob. The first call previews the request; rerun with confirm=true after human approval. Requires endpoints:write.

Inputs: limit, confirm, platform, endpoint_id, +4 more.

upsert_customer_intel_itemsAdd or update indicators in a private intel feedA

Bulk upserts up to 100 indicators into a private feed. This is the MCP path for “extract IOCs from this report and add them to MagicSword.” Requires intel:write.

Inputs: items (required), feed_id (required).

whoamiIdentify the MagicSword org and keyA
Read-onlyIdempotent

Returns the MagicSword organization, API key id, and granted scopes for the configured key. Call this first when troubleshooting access — it answers "who am I and what can this key do?". Useful before any other tool to confirm the key is still valid.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools target distinct resources/actions, but the intel cluster is easy to confuse: list_customer_intel_feeds vs list_intel_sources and manage_customer_intel_feed/item vs upsert_customer_intel_items have overlapping concepts. Descriptions clarify them enough, but an agent may still hesitate between feed/source/item operations.

    Naming Consistency4/5

    The set is mostly consistent snake_case verb_noun (list_endpoints, show_endpoint, create_policy, apply_policy_to_endpoints). Minor deviations like whoami and the noun-phrase agent_install_instructions, plus mixed manage_/create/update/upsert verbs, keep it from being perfect.

    Tool Count3/5

    At 26 tools, the surface is heavy and clusters around policy/intel administration with several granular operations. The count is justified by the broad security-platform domain, but it sits at the upper boundary and some intel feed/item tools could be consolidated.

    Completeness4/5

    Coverage is broad: identity, endpoints, groups, policies, rules, intel sources/feeds, alerts, events, upgrades, and enrollment are all represented. Gaps remain around endpoint group lifecycle management, policy delete/update, and bulk alert operations, but core workflows are supported.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients such as Claude Code, Claude Desktop, and Cursor to list hosts, read metrics, inspect containers, follow logs, and, when permitted, run commands, restart containers, manage authorized_keys, and edit host lists under per-host policy, Touch ID-backed credentials, deny-lists, rate limits, and an audit log.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and MCP clients to execute commands, copy/move files, manage background jobs and port forwarding, and optionally view and control remote screens using scoped, expiring agent tokens.
      21 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables Claude Desktop, Claude Code, and other MCP clients to manage firewall rules, VPNs, NAT, DNS, DHCP, routing, certificates, and diagnostics through natural language, with guardrails, rate limits, and config-revision backups that make destructive changes reversible.
      -