Control D MCP

A local Model Context Protocol server for safely managing Control D by conversation.

It can inspect profiles and endpoints, diagnose recent blocked DNS queries, pause a profile temporarily, create block/bypass/redirect rules, and delete rules. Every live policy change requires confirm: true and is followed by a read-back check.

Setup

Requires Node.js 20 or newer and a dedicated Control D write token. Restrict the token to trusted source IPs in Control D when possible.

npm install
npm run test

Put the token in ~/.config/controld-mcp.env (never in this repository) and set the file mode to 0600:

CONTROL_D_API_TOKEN=your-dedicated-write-token

Example Codex configuration:

[mcp_servers.controld]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/controld-mcp/dist/index.js"]

Restart the MCP host after adding the server. The MCP process can start without the token, but its tools will return a setup error until the token is present and the host is restarted.

Typical flow

1. “Show my Control D profiles.”
2. “I just tried example.com. What was blocked in the last five minutes?”
3. Review the query timestamps and the rule/filter that triggered each block.
4. “Create a temporary bypass for cdn.example.net on Global for 30 minutes.”
5. The assistant shows the exact proposed mutation and asks for approval before calling the confirmed write tool.

For routing: list proxy locations first, then redirect either exact domain rules or a named service with an exact location ID. A service such as YouTube can involve many changing domains, so set_service_policy is usually safer than trying to maintain its hostnames manually.

Security design

• No generic HTTP/API passthrough tool.
• API and analytics hosts are constrained to Control D.
• Tokens are loaded at runtime and never returned or logged.
• Activity-log requests are bounded to 200 rows and are never cached.
• Writes require exact profile resolution and confirm: true.
• Prefer exact domains over wildcards. Inspect results before unblocking anything.

API stability

Control D warns that its API is unversioned. Activity-log and several management operations use current first-party dashboard contracts because they are not all present in the public API reference. See docs/api-contracts.md.

Acknowledgements

Endpoint behavior was cross-checked against Control D's official dashboard and the community Control D Manager Home Assistant integration. This project is an independent implementation.

License

MIT