Skip to main content
Glama
yads-mcp
by MrMarco74

yads-mcp

License Language MCP Wave AI generated

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 requires confirm=True on 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/ -q

tests/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.com

  • YADS_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.server

or 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-scoped

  • queue_cancel_task(task_id)

  • queue_purge(confirm) — destructive, tenant-scoped, 60s undo window

  • queue_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 window

  • undo_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 undo

  • get_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 / module

  • list_compliance_status(framework=None, page=1, limit=50) — per-target scores/grades, worst first

  • get_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 actions

  • get_security_trends(days=30) — historical security-score points

  • export_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 counts

  • list_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 deliveries

  • list_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 tools
add_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

    B3.4/5.0

    Scored across 31 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a secure MCP gateway for AI agents to access APIs without exposing raw credentials, with scoped access, audit logging, and OAuth support.
      MIT