magicsword-mcp
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MAGICSWORD_CONFIG | No | Path to the MagicSword config file. Defaults to ~/.magicsword/mcp.json. This file stores the API key and base URL when not using environment variables. | |
| MAGICSWORD_API_KEY | Yes | MagicSword API key (format: msk_...). Mint one in Magic Portal → Settings → API Keys. Can be set as a per-client override instead of using ~/.magicsword/mcp.json. This is the primary secret required to authenticate with the MagicSword API. | |
| MAGICSWORD_BASE_URL | No | Portal base URL. Defaults to https://www.magicsword.io. Remote URLs must use HTTPS; plain HTTP is accepted only for localhost development. Configured URLs cannot contain credentials, paths, query strings, or fragments. | |
| MAGICSWORD_GET_RETRIES | No | Number of retries for idempotent GET requests. Default 2, maximum 3. Write actions are never retried automatically. | |
| MAGICSWORD_REQUEST_TIMEOUT_MS | No | Request timeout in milliseconds. Default 30000 (30 seconds). | |
| MAGICSWORD_RESPONSE_MAX_BYTES | No | Maximum response size in bytes. Default 4194304 (4 MiB). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
MagicSword MCP exposes EDR management as conversational tools. Start with whoami to confirm the organization, key, and scopes. Use find_alerts, triage_alert, and list_events for triage; list_endpoints then show_endpoint to inspect a fleet; list_agent_releases before upgrades; upsert_customer_intel_items to load report IOCs; create_policy for an empty audit policy or clone_policy for an audit copy. Use list_endpoint_groups to discover groups and apply_policy_to_endpoints to preview assignment, then pass its server confirmation token only after human approval. Group assignment uses the preview snapshot, not future members; desired assignments replace existing protections and are not proof of installation. Use download_policy to save generated Windows policy files locally; it does not deploy them. Downloads default to the machine running this server. For Windows WDAC, do not create explicit flat file-hash policy rules; use event_ids so the Portal can derive supported rules, or use private intel feeds for hash/AuthentiHash/page-hash/TBS IOCs. Fleet-wide and destructive operations require an explicit confirmation; show the preview to the human first.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| whoamiA | 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. |
| list_endpointsA | 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 |
| list_endpoint_groupsA | 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. |
| show_endpointA | Fetches one endpoint directly by UUID with OS, architecture, policy, compliance, agent version, upgrade state, heartbeat, and AMSI details. Requires endpoints:read. |
| list_agent_releasesA | Lists available MagicSword agent releases and per-platform latest markers before an upgrade is queued. Requires endpoints:read. |
| find_alertsA | 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". |
| list_eventsA | 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. |
| triage_alertA | 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. |
| list_policiesA | 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). |
| create_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. |
| clone_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. |
| show_policyA | Returns the active version + status for one policy by id. |
| download_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. |
| manage_policy_rulesA | 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. |
| apply_policy_to_endpointsA | 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. |
| flip_to_enforcingA | 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. |
| list_customer_intel_feedsA | Lists private intelligence feeds and, optionally, a page of items for one feed. Requires intel:read. |
| list_intel_sourcesA | 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. |
| manage_customer_intel_feedA | Creates, updates, or deletes private intelligence feeds. Organizations are limited to 3 feeds. Requires intel:write. |
| manage_customer_intel_itemA | Edits or deletes one item in a private intelligence feed. Requires intel:write. |
| upsert_customer_intel_itemsA | 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. |
| manage_policy_intel_sourcesA | 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. |
| upgrade_endpointsA | 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. |
| request_endpoint_checkinA | Queues a check-in command for one endpoint. Requires endpoints:write. |
| mint_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. |
| agent_install_instructionsA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.