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.

Related MCP server: technitium-mcp-secure

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. “Would cdn.example.net be blocked?” check_domain answers immediately, with the filter, service, or rule that decides it, without waiting for real traffic.

5. “Create a temporary bypass for cdn.example.net on Global for 30 minutes.”

6. The assistant shows the exact proposed mutation and asks for approval before calling the confirmed write tool.

Existing custom rules can be switched off and back on with set_rules_enabled, which keeps their action and redirect target.

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. list_profile_services takes a search term to find a service without returning the whole catalog.

Security design

• No generic HTTP/API passthrough tool.

• API and analytics hosts are constrained to Control D. check_domain queries the endpoint's own public resolver at dns.controld.com and sends no token.

• 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