yads-mcp
This MCP server lets an LLM agent drive the YADS security-scanning platform through its HTTP API — managing scan queues, tags, targets, scans, findings, reports, discovery, and integrations under tenant scoping.
Queue & scan control: view queue status and rate-limited modules, pause/resume the fleet-wide queue, cancel tasks, and purge/undo-purge a tenant's queued scans (destructive actions require
confirmand API-key scopes).Tagging: list all tags, add/remove tags on targets, bulk assign/add tags, or delete a tag globally (destructive, no undo).
Scan execution: trigger scans by URL or target id with configurable profiles/modules, queue bulk scans by criteria or selected target ids, preview bulk-scan blast radius, and fetch scan findings.
Target & asset management: list/search targets with filters, get target details, add targets (SSRF-protected), bulk delete with undo window, archive/restore targets, archive dead targets, blocklist targets (destructive), and view target changes, scan status, and network context.
Findings & compliance (read-only): list/filter findings, get a finding, view summary counts, list per-target compliance status, and get per-framework compliance rollups.
Reports & export (read-only): executive posture summary, security trends over time, and flat target export.
OSINT / discovery (read-only): list/get discovery sessions and candidates, list brand watches, and list shadow domains for brand-abuse hunting.
Integrations (read-only, secret-safe): list outbound webhooks (URLs masked), report subscriptions, and external integrations (config key names only, never secret values).
Click on "Deploy 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., "@yads-mcp Check the queue status and list any rate-limited modules."
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.
yads-mcp
MCP server that lets any MCP-capable LLM agent (Claude Code, or another
agent process reachable over the same network as YADS) drive queue
control, tagging, scan execution, and target/asset management through
YADS's own /api/v1 API, without a human at the dashboard.
It's a thin stdio wrapper around YADS's existing HTTP API
(/api/v1/queue/*, /api/v1/tags*, /api/v1/targets/*) — no separate
execution path, no bypassing tenant scoping or the scan-dispatch code
path. Every action taken through here is subject to the same tenant
isolation, concurrent-scan limits, and change-detection logic as the
dashboard.
1. Create an API key
From a machine already logged into YADS (session cookie), via
/developer or the /api-keys/ endpoint, create a key with the scopes
this agent needs:
read— status/list operations (queue_status, tags_list, scan_get_findings, list_targets, get_target, get_target_changes, get_scan_status, get_network_context, ...)write— tag mutations, and target mutations (add_target, undo_bulk_delete_targets, bulk_archive_targets, archive_dead_targets, restore_target)scan_execute— triggering scans (single or bulk)destructive— queue_purge, tags_delete_globally, bulk_delete_targets, bulk_blocklist_targets (also requiresconfirm=Trueon the call itself)
Copy the returned token now — it is never shown again.
Related MCP server: ai-devsecops-agent-mcp-server
2. Install
cd yads-mcp
python -m venv .venv
.venv/bin/pip install -e .Tests
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest tests/ -qtests/conftest.py runs YADS in-process (Starlette TestClient) against
the same test Postgres/Redis stack as the yads repo's own tests
(docker-compose.test.yml in that repo, ports 5433/6380) — start that
stack first if these tests aren't passing.
3. Configure a client
Environment variables the server needs:
YADS_URL— e.g.https://yads.example.comYADS_API_KEY— the token from step 1
Claude Code
claude mcp add yads \
--env YADS_URL=https://yads.example.com \
--env YADS_API_KEY=<token> \
-- /path/to/yads-mcp/.venv/bin/python -m yads_mcp.serveror add to .mcp.json:
{
"mcpServers": {
"yads": {
"command": "/path/to/yads-mcp/.venv/bin/python",
"args": ["-m", "yads_mcp.server"],
"env": {
"YADS_URL": "https://yads.example.com",
"YADS_API_KEY": "<token>"
}
}
}
}Tools
Queue & Scan Control
queue_status()queue_list_rate_limited_modules()queue_pause()/queue_resume()— fleet-wide, not tenant-scopedqueue_cancel_task(task_id)queue_purge(confirm)— destructive, tenant-scoped, 60s undo windowqueue_undo_purge(undo_batch)
Tagging & Organization
tags_list()tags_add_to_target(target_id, tag)/tags_remove_from_target(target_id, tag)tags_bulk_assign(target_ids, tags, action="add"|"remove"|"replace")tags_bulk_add_by_ids(target_ids, tag)tags_delete_globally(tag_name, confirm)— destructive, no undo
Scanning Execution
scan_trigger(target_url, profile="standard")scan_trigger_by_target_id(target_id, scan_types, scan_priority=None)scan_bulk_preview_count(only_roots=False, online_only=False, scanned_before=None)scan_bulk_by_criteria(scan_types, only_roots=False, online_only=False, scanned_before=None)scan_bulk_selected(target_ids, scan_types)scan_get_findings()
Target & Asset Management (Wave 2)
list_targets(tag=None, online=None, scan_status=None, domain_search=None, archived=False, last_scanned_before=None, page=1, limit=20)get_target(target_id)add_target(domain)bulk_delete_targets(target_ids, confirm)— destructive, 60s undo windowundo_bulk_delete_targets(undo_batch)bulk_archive_targets(target_ids)/archive_dead_targets()/restore_target(target_id)bulk_blocklist_targets(target_ids, confirm)— destructive, no undoget_target_changes(target_id, limit=30)get_scan_status(target_id)get_network_context(target_id)
Findings & Compliance (Wave 3, read-only)
list_findings(severity=None, status=None, module=None, domain_search=None, page=1, limit=20)get_finding(yf_id)get_findings_summary()— counts by severity / status / modulelist_compliance_status(framework=None, page=1, limit=50)— per-target scores/grades, worst firstget_compliance_summary()— per-framework rollup (target count, avg score, grade distribution)
Reports & Export (Wave 4, read-only)
get_executive_summary()— posture summary: counts, score/grade, top risks, recommended actionsget_security_trends(days=30)— historical security-score pointsexport_targets(tag=None, online=None, archived=False, page=1, limit=500)— flat targets export
OSINT / Discovery / Intelligence (Wave 5, read-only)
list_discovery_sessions(status=None, page=1, limit=20)get_discovery_session(session_id)list_discovery_candidates(session_id, status=None, page=1, limit=50)list_brand_watches()— brand-keyword watches with shadow-candidate countslist_shadow_domains(status=None, brand_watch_id=None, page=1, limit=50)— DORA brand-abuse hunt output
Integrations / Webhooks / Notifications (Wave 6, read-only, secret-safe)
list_webhooks()— outbound webhooks (URL masked)list_report_subscriptions()— recurring report deliverieslist_integrations()— external integrations; type/active/config-key-names only, never secret values
All four planned domains (Findings & Compliance, Reports & Export, OSINT/Discovery/Intelligence, Integrations/Webhooks/Notifications) are now implemented. Administrative surfaces (tenant/user and system/infra admin) are permanently out of scope.
Troubleshooting
YADS API 403: SSL/TLS Required for API Key authentication — YADS enforces
HTTPS for API-key auth. When YADS runs behind a TLS-terminating reverse proxy
(the normal prod setup), it must honor X-Forwarded-Proto, otherwise every key
is rejected even though YADS_URL is https://. This requires the YADS-side
fix in yads/auth/deps.py (commit 361020f5, 2026-08-25); older YADS builds
reject all API keys behind a proxy. Point YADS_URL at the HTTPS edge, not the
plain-HTTP container port.
Changelog
See CHANGELOG.md.
License
MIT — see LICENSE.
Available Tools
31 toolsadd_targetA
Add a target by domain, or return the existing one if it's already present (find-or-create). Blocked for internal/private-network domains by SSRF protection. Does not trigger a scan -- follow up with scan_trigger_by_target_id() if you want one.
Inputs: domain (required).
archive_dead_targetsA
Archive every target in this key's tenant whose most recent DNS scan returned empty records (i.e. the domain no longer resolves). Tenant-wide sweep, no target_ids needed. Reversible via restore_target().
Inputs: no named parameters.
bulk_archive_targetsA
Archive targets -- stops them from being scanned, but fully reversible via restore_target(). Not destructive.
Inputs: target_ids (required).
bulk_blocklist_targetsA
Add each target's domain to this tenant's Discovery blocklist (exact match -- future Discovery runs won't re-add it) AND archive the target. Requires the 'destructive' scope: unlike plain archiving, reversing this needs both restore_target() and manually removing the blocklist entry (no blocklist-management tool exists yet), so there's no clean single-action undo. Set confirm=True to actually perform this.
Inputs: confirm (required), target_ids (required).
bulk_delete_targetsA
Permanently delete targets and all their scan history/findings -- irreversible beyond a 60-second undo window (see undo_bulk_delete_targets; the domain/tags are restorable, scan history is not). Requires the 'destructive' scope on this API key. Set confirm=True to actually perform this.
Inputs: confirm (required), target_ids (required).
get_network_contextC
Network context captured during a target's scans -- the external IP YADS scanned from and the IPs the target resolved to at scan time.
Inputs: target_id (required).
get_scan_statusA
Current scan status/progress message for a target -- live if a scan is running, otherwise the last known state ("idle", "queued", etc.).
Inputs: target_id (required).
get_targetA
Lean summary of one target: domain, scan status/progress, tags, archive state, when it was created, when it was last scanned, and how many distinct scanner modules have results for it. For per-module scan data, use scan_get_findings() (Wave 1) -- note it returns every finding for the whole tenant, not just this target, so filter its result by target_id client-side. For this target's recent change history, use get_target_changes() instead.
Inputs: target_id (required).
get_target_changesA
Recent detected changes for a target (new/changed/removed findings across scans), newest first. limit capped at 100 server-side.
Inputs: target_id (required), limit. Returns: result
list_targetsC
List targets for this key's tenant, with optional filters (combined with AND). limit is capped at 100 server-side. scan_status accepts "idle"/"queued"/"running"/"failed". last_scanned_before is an ISO date string; matches targets scanned before that date OR never scanned.
Inputs: tag, page, limit, online, +4 more.
queue_cancel_taskA
Cancel a single queued/reserved/active scan task by its Celery task id (see queue_status's active_tasks/reserved_tasks for ids). Only cancels tasks belonging to this key's tenant.
Inputs: task_id (required).
queue_list_rate_limited_modulesA
How many scanner modules are currently being rate-limited by an external target's API (circuit-breaker tripped), if any -- surfaced as part of the same queue-status data queue_status() returns, exposed here as its own discoverable tool for the common "is anything rate-limited right now" question. Only a count is available via the API, not the specific module names.
Inputs: no named parameters.
queue_pauseA
Pause the scan queue -- stops workers from picking up new tasks. NOTE: this is fleet-wide, not scoped to this key's tenant (matches YADS's existing dashboard pause behavior).
Inputs: no named parameters.
queue_purgeA
Clear every queued/running scan for this key's tenant -- irreversible beyond a 60-second undo window (see queue_undo_purge). Requires the 'destructive' scope on this API key. Set confirm=True to actually perform this.
Inputs: confirm (required).
queue_resumeA
Resume the scan queue after a pause. NOTE: like queue_pause, this is fleet-wide, not scoped to this key's tenant.
Inputs: no named parameters.
queue_statusB
Current queue state for this API key's tenant: whether the queue is active (paused/resumed), queued/running target counts, and the tenant's active/reserved Celery tasks.
Inputs: no named parameters.
queue_undo_purgeA
Re-queue the tasks purged by a prior queue_purge call, using the undo_batch id from that call's response. Only works within 60 seconds of the purge, and only for tasks that hadn't started running yet.
Inputs: undo_batch (required).
restore_targetA
Un-archive a target, clearing its archived state so it's scanned again.
Inputs: target_id (required).
scan_bulk_by_criteriaA
Queue a scan for every target matching the given criteria (combined with AND). No target-tag filter exists yet -- to scan only targets without a given tag, list tags_list, resolve target ids yourself, and use scan_bulk_selected instead.
Inputs: scan_types (required), only_roots, online_only, scanned_before.
scan_bulk_preview_countA
Count how many targets match a set of bulk-scan criteria, without queuing anything -- use before scan_bulk_by_criteria to see the blast radius first. scanned_before is an ISO date string ("2026-08-01"); matches targets last scanned before that date OR never scanned.
Inputs: only_roots, online_only, scanned_before.
scan_bulk_selectedC
Queue a scan for an explicit list of target ids.
Inputs: scan_types (required), target_ids (required).
scan_get_findingsA
All scan findings for this key's tenant, newest first.
Inputs: no named parameters. Returns: result
scan_triggerA
Trigger a scan for a URL, finding-or-creating the Target by domain. profile: "quick" (web_analyzer only), "standard" (dns_scanner, web_analyzer, ssl_scanner -- default), or "full" (all 7 modules: dns_cleanup, subdomain_scanner, dns_scanner, web_analyzer, ssl_scanner, crawler, cve_scanner).
Inputs: target_url (required), profile.
scan_trigger_by_target_idB
Trigger a scan for an already-known target by its numeric id, with an explicit module list (e.g. ["catchall_detector"] for a parked-domain-only check). scan_types accepts module names from the scanner registry, plus "full_scan" (expands to every module except subdomain_scanner and catchall_detector) and "dns_cleanup".
Inputs: target_id (required), scan_types (required), scan_priority.
tags_add_to_targetC
Add a tag to one target. Returns the target's full tag list after the change.
Inputs: tag (required), target_id (required). Returns: result
tags_bulk_add_by_idsB
Add a single tag to multiple targets by id (simpler variant of tags_bulk_assign for the common "add one tag to many targets" case).
Inputs: tag (required), target_ids (required).
tags_bulk_assignA
Add, remove, or replace tags on multiple targets at once. action:
"add" (default), "remove", or "replace" (replaces each target's entire
tag list with tags).
Inputs: tags (required), target_ids (required), action.
tags_delete_globallyA
Remove a tag from every target in this key's tenant that has it -- irreversible, no undo. Requires the 'destructive' scope on this API key. Set confirm=True to actually perform this.
Inputs: confirm (required), tag_name (required).
tags_listA
All unique tags currently in use across this key's tenant's targets.
Inputs: no named parameters. Returns: result
tags_remove_from_targetA
Remove a tag from one target. Returns the target's full tag list after the change.
Inputs: tag (required), target_id (required). Returns: result
undo_bulk_delete_targetsA
Re-create targets deleted by a prior bulk_delete_targets call, using the undo_batch id from that call's response. Only works within 60 seconds of the delete -- restores domain/tags only, not scan history.
Inputs: undo_batch (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Most tools have clearly distinct purposes within their domains (queue, tags, scans, targets). Slight overlap exists between tags_bulk_assign and tags_bulk_add_by_ids, and queue_status vs queue_list_rate_limited_modules, but descriptions clarify the differences well.
Tool names follow a consistent snake_case verb_noun pattern with domain prefixes (queue_, tags_, scan_, bulk_). Minor inconsistencies like undo_bulk_delete_targets (vs. queue_undo_purge) and some verbs (archive vs restore) are present but the overall pattern is predictable.
At 31 tools, this exceeds the 25-tool threshold for heavy servers. While the domain is complex and the tools are organized by sub-domains, the count feels bloated for a single MCP server and may overwhelm agents with too many options.
The tool surface covers the core lifecycle for targets (add, list, get, delete, archive, restore), scans (trigger, bulk, findings), queue management, and tags. Notable gaps include no blocklist-management tool (acknowledged) and no tool to list available scan modules, but these are minor and workaroundable.
Maintenance
Related MCP Connectors
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Security firewall for AI agents — scans MCP calls for injection, secrets, and risks.
Credential broker for AI agents: scoped, revocable API access with policy enforcement and audit.
Paid remote MCP for LLM security scans, jailbreak checks, analytics, checkout, and readiness.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides a secure MCP gateway for AI agents to access APIs without exposing raw credentials, with scoped access, audit logging, and OAuth support.MIT
- AlicenseBqualityBmaintenanceEnables LLM clients to access DevSecOps tooling such as CI/CD pipeline status, vulnerability triage, log search, and dependency scanning through MCP, turning AI copilots into security-aware engineering partners.46MIT
- AlicenseAqualityDmaintenanceEnables MCP-capable agents to create and invoke OpenServerless endpoints, manage secrets, and configure integrations such as S3, PostgreSQL, Redis, Milvus, and MongoDB.13Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to perform API testing and security validation through a permission-gated, SSRF-protected, audited MCP tool layer.MIT