Heimdall

Heimdall is a lightweight service that manages local MCP Servers on your device. It lets you authorize and configure specific MCP tools for your MCP clients and makes the same configuration available to all MCP clients on your machine, simplifying setup and governance across tools and servers.

How to use

Set up Heimdall to manage your MCP servers locally. You can run Heimdall via NPX to quickly initialize a managed environment, or install a local instance and run the setup to generate a centralized config. Once configured, you control which tools are authorized for each server and these settings become available to all your MCP clients on the device.

How to install

Prerequisites: you need Node.js and a package manager (npm, pnpm, or npx) installed on your machine.

Via NPX (recommended) install and set up Heimdall with an optional path to your current MCP config. Run the setup command below. If you omit the path, Heimdall generates an empty config.

npx @shinzolabs/heimdall setup <optional: path/to/current/config.json>

Additional configuration and notes

Edit the list of servers by updating the central configuration file at the Heimdall config location. You can add or update available servers in ~/.heimdall/config.json. To limit the tools available to each server, modify ~/.heimdall/controls.json. Heimdall will refresh its internal config after a short delay.

To control which tools are authorized for each server, add them to the corresponding server entry in ~/.heimdall/controls.json. If your MCP client supports dynamic tool list caching, you should see updates automatically. Other clients may require a restart to reflect changes.

If you run multiple MCP clients on the same device, you can reuse Heimdall by configuring each client with a shared Heimdall entry in their mcpServers config. The example below shows how to enable the same authorized tools across all clients.

{
  "mcpServers": {
    "heimdall": {
      "command": "npx",
      "args": [
        "@shinzolabs/heimdall"
      ]
    }
  }
}

Available tools

authorizeTools

Manage the set of tools each MCP server is allowed to use by editing the controls.json and applying the changes to Heimdall so all MCP clients reflect the updated authorization.

updateServerConfig

Update the ~/.heimdall/config.json to add or modify available MCP servers; Heimdall reads this to expose servers to MCP clients.