magicsword-mcp
OfficialThis MCP server lets you conversationally inspect and manage MagicSword endpoints, alerts, events, policies, and intelligence through MCP-aware clients using a local API key.
Identify the organization, key, and granted scopes with
whoami.List/show endpoints and computer groups, list agent releases, request check-ins, queue upgrades, mint enrollment tokens, and get install instructions.
Find and investigate alerts and normalized audit/block events; triage alerts by acknowledging or dismissing them.
List/show/create/clone/download policies and manage policy rules from explicit rules or selected telemetry events.
Preview and confirm policy assignment to endpoints, hostnames, or groups, and flip policies from audit to enforcing with confirmation tokens.
Manage private intelligence feeds and items, list intel sources, attach/detach intel feeds to policies, and bulk upsert IOCs.
Use safety annotations and two-step confirmation flows for destructive or safety-critical operations; writes are not automatically retried, and secrets remain local.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@magicsword-mcp list critical alerts from the last 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Generate an API key in Magic Portal → Settings → API Keys. Start with read scopes for endpoints, alerts, and policies.
In Claude Desktop, open Settings → Extensions → Advanced settings → Install Extension…, then select the downloaded
.mcpbfile.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.
Start a new conversation, then ask MagicSword to call
whoamifollowed bylist_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 configureAlready know your client? Run the matching one-liner:
Client | Install and configure |
Claude Desktop |
|
Cursor |
|
Claude Code |
|
OpenAI 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-mcpThese 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 manualThen click your client's button and approve its installation prompt:
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 configureSetup 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.jsonThe 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.
In Copilot Studio, open your agent's Tools → Add a tool → New tool → Model Context Protocol.
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.Choose OAuth 2.0 → Dynamic discovery, then Create → Next.
Select Create a new connection, sign in to MagicSword, choose your organization, and approve read permissions first. Select Add to agent.
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.
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 |
| Returns organization, key id, and scopes. Always call first when troubleshooting. |
| Lists organization computer groups and parent group IDs for assignment previews. Requires |
| Lists endpoints with optional platform / status / hostname-glob filtering. |
| Fetches one endpoint with OS, policy, compliance, upgrade, heartbeat, and AMSI details. |
| Lists available agent versions and per-platform latest releases. |
| Searches alerts by severity / ack state / since / hostname / MITRE technique. |
| Searches Investigate events by name, filename, path, hash, publisher, computer, or package family, with type/status/policy/endpoint/time filters. |
| Fetches one alert directly with triggering events, metadata, and file context; optionally acknowledges or dismisses it. |
| Lists policies with current version + mode. |
| Creates a new empty audit policy for Windows, macOS, or Linux without assigning devices. Requires |
| Copies a policy into an independent audit policy with its rules, settings, intelligence links and collection links; no computers assigned. |
| Downloads the current Windows policy as a complete WDAC XML ZIP or AppLocker XML; local MCP saves to Downloads or a requested directory. Requires |
| Shows one policy by id. |
| Lists rules or adds explicit / event-derived rules to a policy by id or name. Avoid explicit flat hash rules for Windows WDAC. |
| Previews assignment to computer IDs, hostname matches, or groups; a server-issued |
| Two-step preview/confirm flip with a server-issued one-time confirm token. Safety-critical. |
| Discovers enabled global and organization-owned intel sources and IDs, with platform and pagination filters. |
| Lists private intel feeds or feed items. |
| Creates or updates feeds; deletion requires a preview followed by |
| Edits feed items; deletion requires a preview followed by |
| Adds indicators extracted from reports into a private feed. |
| Lists, attaches, or detaches intel feeds on a policy. |
| Previews upgrades for an endpoint selection; |
| Queues an endpoint check-in command. |
| Mints a one-time agent enrollment token. |
| 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 |
| Complete WDAC XML ZIP; |
| 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 | Body / purpose |
POST |
|
|
GET |
|
|
POST |
| One selector and its options; returns concrete targets and a confirmation token. |
POST |
|
|
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:
list_policies platform=windowsidentifies the policy name and ID.list_intel_sources platform=windowsreturns available source names and IDs. It defaults to enabled sources; useis_enabled=falseto inspect disabled ones. Uselimit(up to 100) andoffsetto discover additional pages.manage_policy_intel_sources action=list policy_id=...shows current attachments.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.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
MAGICSWORD_API_KEY/MAGICSWORD_BASE_URLenv vars (set by the MCP host).~/.magicsword/mcp.json(or$MAGICSWORD_CONFIG).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_enforcingis 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 useshow_policyto 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=truecall. Policy assignment requires a concrete preview followed by its server-issuedconfirmation_token;confirm=truealone cannot commit an assignment.Windows WDAC policy edits should not use explicit flat file hashes. Use
manage_policy_ruleswithevent_idswhen approving audit events so the Portal can derive supported path / publisher / filename rules, or useupsert_customer_intel_itemsfor 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 configuredMAGICSWORD_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 --versionTests 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.mjsUse 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 toolsagent_install_instructionsShow the MagicSword agent install one-liner for a platformARead-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 assignmentADestructive
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 alertsARead-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 enforcingADestructive
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 releasesARead-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 feedsARead-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 groupsARead-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 endpointsARead-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 eventsARead-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 sourcesARead-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 policiesARead-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 feedADestructive
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 itemADestructive
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 policyADestructive
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 rulesADestructive
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 endpointARead-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 policyARead-onlyIdempotent
Returns the active version + status for one policy by id.
Inputs: policy_id (required).
triage_alertTriage a single MagicSword alertADestructive
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 upgradesADestructive
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 keyARead-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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables Claude Code sessions to query fleet status, focus terminals, and manage sessions programmatically via MCP tools.2MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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

gaiadesk-mcpofficial
AlicenseNot gradedqualityBmaintenanceEnables 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 npm1MIT- FlicenseNot gradedqualityAmaintenanceEnables 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.-