Skip to main content
Glama
magicsword-mcp

magicsword-mcp

Official

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
MAGICSWORD_CONFIGNoPath 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_KEYYesMagicSword 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_URLNoPortal 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_RETRIESNoNumber of retries for idempotent GET requests. Default 2, maximum 3. Write actions are never retried automatically.
MAGICSWORD_REQUEST_TIMEOUT_MSNoRequest timeout in milliseconds. Default 30000 (30 seconds).
MAGICSWORD_RESPONSE_MAX_BYTESNoMaximum 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

CapabilityDetails
tools
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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 limit endpoints (default 100, max 500). Use this to find endpoint IDs for other tools.

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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

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