Magicsword MCP

What magicsword-mcp does

The magicsword-mcp MCP server exposes MagicSword customer-management functions to MCP clients. It is intended for security teams that need to inspect endpoint state, investigate alerts, review telemetry, manage policies, maintain private intelligence, and perform selected agent operations without building direct API calls into an agent workflow.

Read-only capabilities include checking the authenticated organization and key scopes, filtering endpoints by platform, status, or hostname pattern, and viewing endpoint details such as operating system, policy, compliance, upgrade, heartbeat, and AMSI information. The server can also search alerts by severity, acknowledgement state, time, hostname, or MITRE technique; retrieve an individual alert with related events and file context; and list audit or blocking events.

Policy and intelligence functions include listing policies, viewing a policy, managing policy rules, associating private intelligence feeds with policies, and creating or editing private feed content. Operational tools can preview endpoint policy assignments, preview upgrades, queue endpoint check-ins, create enrollment tokens, and return platform-specific installation commands.

How it works

The package is a local Node.js process that communicates with an MCP host over stdio. It acts as a wrapper around MagicSword’s /api/public/v1/* customer API and uses the Magic Portal origin by default. The server requires Node.js 22 or newer and a MagicSword Enterprise API key. Pilot-tier organizations receive an Enterprise-plan message and cannot use the API functions until the organization is upgraded.

Call whoami first when diagnosing access. It reports the organization, key identifier, and scopes; successful tool discovery alone does not prove that the key has the permissions needed for API calls. A follow-up list_endpoints call provides a basic read-access check.

Several mutating operations deliberately require confirmation. Policy assignment, endpoint upgrades, policy enforcement changes, and deletion of intelligence feeds or items use previews before committing. The enforcement transition also uses a server-issued one-time confirmation token. This design lets an agent show the proposed change before applying it, but operators should still review the target selection and resulting action.

Setup and configuration

Install the package globally with npm, then run magicsword-mcp configure. The setup flow collects the API key with hidden input, lets you select supported clients, and stores credentials in ~/.magicsword/mcp.json with restrictive file permissions. It can configure Claude Desktop, Cursor, Claude Code, or Codex, and a manual mode prints a credential-free launch entry for other local stdio hosts.

The server also supports MAGICSWORD_API_KEY and an optional MAGICSWORD_BASE_URL in the MCP host environment. A custom API origin must be supplied explicitly; otherwise setup uses https://www.magicsword.io. Restart the client or begin a new session after registration. Browser-only MCP clients cannot use this package directly because it provides local stdio rather than a remote transport.

Tools and capabilities

The magicsword-mcp MCP server provides tools for:

• Inspecting organizations, endpoints, releases, alerts, events, policies, and policy rules.
• Triaging, acknowledging, or dismissing alerts.
• Previewing and confirming policy assignments, enforcement changes, and endpoint upgrades.
• Creating, updating, deleting, and populating private intelligence feeds and items.
• Attaching or detaching intelligence sources from policies.
• Requesting endpoint check-ins and minting one-time enrollment tokens.
• Producing macOS, Linux, and Windows agent installation instructions.

The API key’s scopes and the organization’s subscription level determine whether these operations succeed.