Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@crab-hole-mcp Is example.com blocked on my Crab-hole right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for inspecting and administering a Crab-hole DNS filter over SSH — so an AI assistant (Claude, or any MCP-compatible client) can check status, query blocklists, manage allow/block rules, and safely roll out config changes on your self-hosted instance.
It talks to a single root-owned helper script on the Crab-hole host over non-interactive SSH. It never reads or forwards SSH keys, and it never gives the model an arbitrary shell — only the fixed set of operations described below.
Read-only tools are enabled by default:
get_crab_hole_config — read the complete active TOML plus its SHA-256 revision
validate_crab_hole — run Crab-hole's native config and blocklist validators
validate_proposed_config — validate proposed TOML without installing it
list_config_backups — list configuration and custom-rule safety backups
crab_hole_status — service state, version, block count, rule counts, refresh time, and memory
check_domain — resolve a domain through the live filter and report whether it is blocked
list_custom_rules — list custom allow or block entries
list_blocklists — list configured remote and local sources
recent_logs — read recent service logs, optionally errors only
Set CRAB_HOLE_MUTATIONS_ENABLED=true to additionally expose:
replace_crab_hole_config — atomically replace the entire validated TOML configuration
restore_crab_hole_config — restore a validated configuration backup
control_crab_hole_service — start, stop, or restart Crab-hole
add_custom_rule — requires ADD ALLOW domain or ADD BLOCK domain
remove_custom_rule — requires REMOVE ALLOW domain or REMOVE BLOCK domain
restart_crab_hole — backward-compatible restart shortcut
Because replace_crab_hole_config replaces the complete TOML, it can add, remove, or
modify blocklist and allow-list sources, blocking mode, subdomain behavior, downstream
listeners, upstream resolvers, TLS settings, timeouts, and any other option supported by
the installed binary. The safe workflow is:
Read get_crab_hole_config and retain its sha256.
Edit the returned TOML.
Call validate_proposed_config.
Call replace_crab_hole_config with the original hash and exact confirmation
REPLACE CRAB-HOLE CONFIG <sha256>.
The expected hash rejects stale edits. Configuration and rule writes are serialized,
backed up under /var/backups/crab-hole-mcp/ on the remote host, and installed
atomically. With applyNow=false, changes wait for a later restart. With
applyNow=true, the MCP restarts Crab-hole, verifies its localhost DNS listener, and
automatically restores the backup if readiness fails. Restores make an additional
safety backup first.
Service confirmations are exact: START CRAB-HOLE, STOP CRAB-HOLE, or
RESTART CRAB-HOLE. Stopping or restarting can interrupt filtered DNS briefly.
Related MCP server: ssh-mcp-server
A Crab-hole instance running on a Linux host you can SSH into.
jq and python3 (with tomllib, stdlib on 3.11+) installed on that host.
A non-interactive SSH key set up from wherever this MCP server runs to that host,
authorized for a user with passwordless sudo access to the helper script (see
below) — not to anything else.
Bun to build/run this project locally.
See SETUP.md for a full walkthrough. Quick version:
git clone https://github.com/papacasper/crab-hole-mcp.git
cd crab-hole-mcp
bun install
bun run typecheck
bun test
bun run buildCopy remote/crab-hole-admin to the Crab-hole host, root-owned and not writable by
anyone else:
sudo install -o root -g root -m 0750 remote/crab-hole-admin /usr/local/sbin/crab-hole-adminIt only accepts a fixed set of subcommands (status, get-config,
validate-proposed, replace-config, add-rule, ...) — it is not an arbitrary shell
interface. Grant your SSH user passwordless sudo scoped to exactly this binary, e.g. in
/etc/sudoers.d/crab-hole-mcp:
your_ssh_user ALL=(root) NOPASSWD: /usr/local/sbin/crab-hole-adminThe helper assumes Crab-hole's config lives at /etc/crab-hole/config.toml, custom
rules at /etc/crab-hole/allowed-custom.txt / blocked-custom.txt, the systemd unit is
crab-hole.service, and the binary is /usr/local/bin/crab-hole listening on localhost
UDP 5354 — adjust the constants at the top of remote/crab-hole-admin if your install
differs.
Copy .env.example to .env and set at minimum CRAB_HOLE_SSH_HOST:
cp .env.example .envNo SSH keys, DNS credentials, or server secrets are stored in this project — SSH
authentication is handled by your normal ssh/agent setup on the machine running the
MCP server.
Use mcp-config.example.json as a starting point for any client that accepts the
common mcpServers format:
{
"mcpServers": {
"crab-hole": {
"command": "crab-hole-mcp",
"env": {
"CRAB_HOLE_SSH_HOST": "your-server-ip-or-hostname"
}
}
}
}If you installed via bun run build in a cloned checkout instead of a package
manager, point command at the generated bin/crab-hole-mcp script instead. Rebuild
after source changes and restart the MCP client after configuration changes.
This MCP fully administers Crab-hole itself, but deliberately does not provide
arbitrary server-file or shell access. Anything outside Crab-hole itself — DNS
forwarders/edges like dnsdist, firewalls, OS packages, certificates, and unrelated
services — is out of scope for its mutation tools. Certificate and private-key paths
may be configured in Crab-hole's TOML, but private-key contents are never returned.
MIT. Crab-hole itself is AGPL-3.0-licensed; this project only talks to it over SSH/CLI and does not link against or embed its code.
Resolve a domain through the live Crab-hole backend and report whether it is blocked.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | A DNS name such as example.com |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it operates against the live backend, implying real-time behavior, but does not disclose output format, potential errors, or rate/load implications. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes: it names the action, the backend, and the expected result.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter, read-only tool with strong annotations, the description provides enough context to know what the tool does and what it returns ('whether it is blocked'). There is no output schema, so the description still leaves the exact response shape to inference, but a boolean-style result is reasonable for this use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'domain' is fully described in the schema ('A DNS name such as example.com'), so schema coverage is 100%. The tool description does not add any additional meaning about the parameter beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Resolve') and names a concrete resource ('the live Crab-hole backend') with a clear outcome ('report whether it is blocked'). This distinguishes check_domain from sibling config/validation tools without requiring schema inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'live Crab-hole backend' implies this is for checking current blocking status rather than inspecting configs or validating proposed changes. However, it does not explicitly state when to use this tool versus siblings like validate_crab_hole or list_blocklists, nor does it provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect service health, version, current block count, rule counts, memory, and the latest blocklist refresh.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description aligns with these by saying 'Inspect'. The description adds useful context by enumerating the specific status fields covered (health, version, block count, rule counts, memory, blocklist refresh). For a read-only status check, this is sufficient behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action verb and resource, then lists the key output areas. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, a clear read-only annotation set, and no output schema, the description fully compensates by listing the main data points returned. An agent can correctly infer what this tool provides and how it differs from config, validation, and listing tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to clarify. The baseline is 4, and the description instead adds value by describing what the status output covers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Inspect') and a clear resource ('service health, version, current block count, rule counts, memory, and the latest blocklist refresh'), making its purpose as a status/diagnostic tool clear. It distinguishes itself from siblings like get_crab_hole_config and validate_crab_hole by focusing on health metrics rather than configuration or validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus the sibling tools. The context implies it is the go-to for a health/status overview, but it does not mention alternatives or exclusion conditions, leaving the agent to infer usage from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the complete active Crab-hole TOML configuration and its SHA-256 revision.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description does not need to restate safety. It adds useful behavior context beyond annotations by specifying that the returned data includes both the full active TOML config and its SHA-256 revision.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes meaning: scope ('complete active'), format ('TOML'), and additional result detail ('SHA-256 revision').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, strongly annotated read-only tool, this description communicates the key facts: what is read and what is returned. It lacks an explicit output shape, but the absence of an output schema is mitigated by the clear statement that the configuration and its SHA-256 revision are returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is already exhaustive. Per the baseline for no-parameter tools, this is adequate; the description correctly avoids inventing parameter details that do not exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and identifies the exact resource ('complete active Crab-hole TOML configuration') plus the associated SHA-256 revision. This clearly distinguishes it from sibling tools like validate_crab_hole, list_config_backups, and crab_hole_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the usage context: it is the tool to call when you need the current, complete active configuration and its revision hash. It does not explicitly mention when to prefer alternatives, but the read-only scope is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the live and local blocklist sources configured in Crab-hole.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety behavior is covered. The description adds useful scoping context ('live and local'), but does not disclose details such as whether network calls are made, what the response structure looks like, or how 'live' vs 'local' differs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the action, resource, and scope without any filler. Every word earns its place and no unnecessary qualifiers are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with comprehensive annotations, the description is nearly complete. It doesn't describe the return format, but the absence of an output schema makes that a minor gap; the core what and where are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is vacuously 100%. The baseline for no parameters is 4; the description does not need to explain parameters, and it doesn't attempt to add irrelevant details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), a clear resource ('blocklist sources'), and adds scope ('live and local', 'configured in Crab-hole'). It is immediately distinguishable from siblings like list_custom_rules and list_config_backups, so an agent can tell them apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is clear enough that an agent can infer when to use it: to view blocklist sources. However, the description gives no explicit guidance on when not to use it or what alternative to choose, though the sibling names are distinct enough that confusion is unlikely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configuration and custom-rule backups created by this MCP.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description's 'List' wording is consistent with these annotations, and no additional behavioral disclosure is needed for such a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the purpose without any filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and strong annotations, the description is nearly complete. The only missing context is what exactly is included in the returned backup entries, but no output schema exists and the resource is already named.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description carries the burden of explaining the 'limit' parameter. However, the schema already provides default, minimum, and maximum values, and the parameter name is self-explanatory, so this is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and clearly identifies the resource: configuration and custom-rule backups created by this MCP. This aligns with the title and makes the operation unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states these backups are 'created by this MCP', providing useful context. While it doesn't explicitly compare to alternatives, the simple read-only nature of the tool makes usage conditions fairly self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List custom allow or block entries currently stored on the DNS server.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare `readOnlyHint: true`, `idempotentHint: true`, and `destructiveHint: false`, so the safety profile is covered. The description adds only a mild behavioral nuance with 'currently stored', implying a live snapshot, but it does not disclose response format, pagination behavior, or ordering semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant wording. Every word serves to identify the operation, scope, and object, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool, the description, schema, and annotations together are mostly sufficient: annotations cover safety, the schema covers the required and optional parameters, and the description states the object being listed. The main omission is the output shape and pagination behavior, especially since there is no output schema, but the risk of mis-invocation is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema description coverage is 0%, so the description should compensate for parameter meaning. It does relate the `kind` parameter through 'allow or block', but it says nothing about `limit`, its default of 200, or its effect on result size. The schema constraints help, but the description itself adds minimal parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List'), a specific resource ('custom allow or block entries'), and the location/scope ('stored on the DNS server'). The word 'custom' helps differentiate from siblings like `list_blocklists`, and the allow/block wording maps directly to the required `kind` parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when the tool should be used: whenever an agent needs to see custom allow or block rules on the DNS server. However, it provides no explicit guidance about when to use this tool instead of a sibling such as `list_blocklists`, and it does not mention any exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read recent Crab-hole service logs, optionally restricted to errors.
| Name | Required | Description | Default |
|---|---|---|---|
| lines | No | ||
| errorsOnly | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already fully cover safety (readOnlyHint, idempotentHint, destructiveHint=false). The description adds the 'recent' scope and optional error filtering, but it does not clarify what 'recent' means or describe the return format. This is modest added value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. Every phrase adds meaning: the resource is identified first, and the optional errors restriction is appended as a secondary qualifier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for selecting this tool among unrelated siblings, but gaps remain: 'recent' is undefined, the 'lines' parameter is unexplained, and there is no output schema or note about the response format. An agent can invoke it with defaults, but not with full understanding of the behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It explains 'errorsOnly' via 'optionally restricted to errors' but does not explain the 'lines' parameter or its numeric bounds/behavior. The description only partially compensates for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and a clear resource ('recent Crab-hole service logs'), plus an optional error filter. This clearly distinguishes it from sibling tools, which are about config, validation, status, domains, rules, and blocklists—none involve reading logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies usage when recent logs are needed, and the errors-only option hints at a debugging context. However, it does not explicitly name alternatives or state when not to use this tool, so the when-to-use guidance is only implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run Crab-hole's native configuration and list validators without changing anything.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destrctiveHint=false, so the bias is covered by structured data. The description adds a small behavioral detail by saying 'native' validators and 'list validators', indicating the tool uses Crab-hole's own mechanism and may produce a list of validators. It does not contradict the annotations, but it also does not reveal any significant new behavioral traits such as output format or system impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action and the non-destructive guarantee. It contains no filler words. The only issue is grammar awkwardness in 'native configuration and list validators', which slightly reduces clarity but does not waste space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with supportive annotations, the description covers the essential operation and safety. However, it does not describe what the tool returns or how it relates to validate_posed_config, which is a relevant sibling. The ambiguity between 'list validators' and running them also leaves a small gap in completenes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema has 100% description coverage. With no params, the description has no additional meaning to provide, so the baseline of 4 applies. The lack of param explanation is irrelevant here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Run' and a resource 'Crab-hole's native configuration and list validators', plus the key constraint 'without changing anything'. It clearly conveys that this validates the active state, and the title 'Validate Active Crab-hole State' reinforces the purpose. However, the phrasing 'configuration and list validators' is slightly awkward and could be misinterpreted as validating a list rather than running validators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without changing anything' implies this is a read-only validation, but it does not explicitely state when to use this tool instead of alternatives like validate_proposed_config or get_crab_hole_config. No exclusion or alternative is named, so the usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate complete proposed Crab-hole TOML without installing or activating it.
| Name | Required | Description | Default |
|---|---|---|---|
| toml | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral detail by explicitly confirming the tool does not install or activate, but it does not describe the validation result, error behavior, or whether it performs full semantic validation versus syntax-only validation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states the action, the object, and the key behavioral constraint in ten words, earning every word's place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, one-parameter, read-only validation tool, the description plus annotations are largely sufficient for an agent to select and invoke it correctly. The only meaningful omission is an explicit description of the return value or validation outcome, which is somewhat mitigated by the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the single 'toml' parameter, so the description must carry meaning. It does so by specifying the parameter should contain a 'complete proposed Crab-hole TOML' — adding the 'complete' and 'proposed' qualifiers that are not present in the schema. It could add more on formatting expectations, but the single simple parameter is adequately characterized.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('validate') with a clear resource ('complete proposed Crab-hole TOML') and immediately scopes the operation as 'without installing or activating it'. This distinguishes it from validating an active/installed configuration and from sibling tools like validate_crab_hole.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when an agent has a proposed TOML and wants to validate it before applying it. It also implies exclusion of install/activate behavior, but it does not explicitly name alternatives such as validate_crab_hole or get_crab_hole_config, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource or action: config reading, validation, backups, status, domain lookup, custom rules, blocklists, and logs. The only overlapping pair is validate_crab_hole and validate_proposed_config, but the descriptions clearly separate native validators from proposed TOML validation.
Most tools use snake_case with verb prefixes like get_, validate_, list_, and check_, but crab_hole_status and recnt_logs are noun phrases without verbs. The mixed conventions are readable but not fully consistent.
Nine tools is a well-scoped size for a DNS configuration and observability server. Each tool serves a distinct purpose without creating reduntant bloat or leaving the surface feeling too thin.
The read, validate, and inspect capabilities are well covered, but there are no tools to apply config, restore backups, add or remove custom rules/blocklists, or toggle blocking. These are notable lifecycle gaps for a tool named as a Crap-hole management server.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Tailscale device, route, DNS, key, user, and ACL management over MCP and CLI.
Read devices, users, keys, ACLs and DNS for a tailnet; manage devices, routes and auth keys.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/papacasper/crab-hole-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
