Latent Defense MCP Server

MCP server that connects Claude Code to your Latent Defense deployment. Map GitHub repositories into an infrastructure graph, discover attack paths with the JEPA energy model, and triage findings — all from your terminal.

Quick start

# 1. Install
pip install git+https://github.com/latent-defense/mcp-server-public.git

# 2. Scaffold config and skills into your project
cd your-project
latent-defense-mcp-init

# 3. Edit .mcp.json — set your API key and portal URL
# 4. Start Claude Code (or restart if already running)
# 5. Type: "Map all repositories in our GitHub org"

Setup

Step 1 — Install the MCP server

pip install git+https://github.com/latent-defense/mcp-server-public.git

Step 2 — Get your portal URL and API key

1. Log in to your Latent Defense portal
2. Go to Settings → API Keys
3. Click Generate API Key — it starts with sk_ld_
4. Copy the key (it's only shown once)

Your portal URL is the base URL you use to access the portal (e.g. https://portal.acme.latentdefense.ai).

Step 3 — Add a GitHub PAT to the credential broker

The mapper needs a GitHub Personal Access Token to clone your repositories.

1. Create a GitHub PAT with repo scope (or fine-grained with read access to your target repos)
2. In the portal, go to Settings → Credentials
3. Select a profile from the dropdown (e.g. github) or create a new one
4. Under Source Code, add a GitHub PAT credential and paste your token
5. Click Verify All — it should show a green verified status

Remember the profile name (e.g. github) — you'll need it when mapping.

Step 4 — Configure Claude Code

Run latent-defense-mcp-init in your project directory:

latent-defense-mcp-init

This creates:

• .mcp.json — MCP server configuration
• .claude/skills/map/ — guided mapping workflow skill
• .claude/skills/research/ — interactive JEPA inference skill

Now edit .mcp.json and replace the placeholder values:

{
  "mcpServers": {
    "latent-defense": {
      "command": "latent-defense-mcp",
      "env": {
        "LATENT_DEFENSE_API_KEY": "sk_ld_your_key_here",
        "LATENT_DEFENSE_URL": "https://portal.your-deployment.com"
      }
    }
  }
}

If your portal uses a self-signed certificate, add "LATENT_DEFENSE_VERIFY_SSL": "false" to the env block.

If latent-defense-mcp is not on your PATH, use the full path — run which latent-defense-mcp to find it.

Step 5 — Start Claude Code

Start Claude Code (or restart if already running). You should see latent-defense appear in the MCP server list. If it doesn't, check the API key and portal URL in .mcp.json.

Mapping your infrastructure

Start a mapping run

Tell Claude what to map:

Map all repositories in the acme-corp GitHub org

Or use the /map skill for a guided workflow — it will ask you for repositories, credential profile, and scope.

Claude will:

1. Ask which credential profile to use (the one you set up in Step 3, e.g. github)
2. Create the mapping run and show you the run ID
3. Monitor progress — you'll see agent counts and completion status
4. Report results when done — node count, edge count, and the repository/branch IDs

What gets mapped

The mapper clones each repository and builds a semantic graph of your infrastructure:

• IaC (Terraform, CloudFormation, Helm charts) → cloud resources, networking, IAM
• Kubernetes manifests → deployments, services, RBAC, network policies
• CI/CD pipelines (GitHub Actions, GitLab CI) → workflows, secrets, deployment targets
• Application code → HTTP endpoints, service-to-service calls, auth checks
• Dockerfiles → container images, base images, exposed ports
• Configuration files → environment variables, secret references, database connections

A mapping of ~50 repositories takes 15-30 minutes.

Troubleshooting mapping

Error	Cause	Fix
"Repository not accessible without a VCS credential"	No GitHub PAT in the credential profile	Add a PAT in Settings → Credentials and verify it
"No scope target is accessible"	Wrong credential profile name	Check the profile dropdown in Settings → Credentials for the correct name
401 Unauthorized	Bad or expired API key	Generate a new key in Settings → API Keys
Run stuck in routing for >10 min	Large scope, planner is working	Normal for 50+ repos — wait for it

Finding attack paths

Once you have a mapped graph, use the /research skill to discover attack paths.

Start a research session

Find attack paths in our infrastructure

Or use /research for the guided workflow. Claude will:

1. Load your graph into the JEPA engine (takes 2-5 minutes for large graphs — Claude will tell you when it's ready)
2. Survey the attack surface — find entry points, high-value targets, credential stores
3. Build threat models — hypothetical attack chains targeting your infrastructure
4. Match against real infrastructure — the JEPA model scores each hop based on the full graph structure
5. Validate against compensating controls — high-energy hops indicate the model detected a security control blocking that transition
6. Submit confirmed paths to triage — only paths that survive validation

Understanding results

The JEPA model assigns energy scores to each hop in an attack path:

Energy	Meaning
< 0.5	Easy — minimal barriers, attacker can traverse freely
0.5 - 2.0	Medium — some controls present but traversable
> 2.0	Hard — significant compensating control detected (network policy, RBAC boundary, security group, etc.)

Lower energy = easier for an attacker = higher risk.

When Claude finds a high-energy hop, it inspects the nodes on both sides to identify the specific control — a network policy, a pod security context, an RBAC binding — and names it in the analysis.

Research modes

Mode	When to use	Example prompt
Proactive scan	Find the most dangerous paths that exist	"Find attack paths in our infrastructure"
Detection triage	Investigate a specific CVE or alert	"Is CVE-2024-1234 exploitable in our infrastructure?"
Query	Answer a security posture question	"Is our production database reachable from the public internet?"

Example: full workflow

1. "Map all repositories in our GitHub org"
   → Claude creates a mapping run, monitors progress, reports results

2. "Find attack paths in our infrastructure"
   → Claude loads the graph into JEPA, surveys entry points and targets

3. Claude builds threat models and matches them:
   → "CI/CD pipeline → GitHub Actions secrets → Terraform → K8s secret → production database"
   → Path energy: -0.85 (easy traversal)
   → 3/3 nodes matched, all hops confirmed

4. Claude validates each hop:
   → "The deploy workflow writes ANTHROPIC_API_KEY to secrets.tfvars — no environment gate"
   → "K8s secret bundles 4 keys in one object — compromise of any consumer yields all"

5. Claude submits the validated path to triage with remediation guidance

Skills

This repo includes two Claude Code skills:

Skill	Command	What it does
Map	/map	Guided mapping — asks for repos, credential profile, monitors progress, reports results
Research	/research	Interactive JEPA inference — loads graph, builds threat models, matches, validates, submits paths

Skills are installed by latent-defense-mcp-init into .claude/skills/. They guide Claude through each workflow step by step.

Environment variables

Variable	Required	Default	Description
LATENT_DEFENSE_API_KEY	Yes	—	API key from portal (starts with sk_ld_)
LATENT_DEFENSE_URL	No	https://portal.latentdefense.ai	Portal base URL
LATENT_DEFENSE_VERIFY_SSL	No	true	Set to false for self-signed certs

Tool reference

Mapping

Tool	Description
create_mapping_run	Create a mapping run — accepts repos, cloud accounts, k8s clusters, domains, CIDRs, web endpoints
get_mapping_run	Get run status: routing → planning → running → committing → completed. Shows agent counts and progress
list_mapping_runs	List recent mapping runs with status and trigger type
list_mapping_agents	List agents spawned by a run (planner, modality agents) with per-agent status
cancel_mapping_run	Cancel a running or stuck mapping run
trigger_scan	Trigger a scan via map-trigger (adds dedup + rate limiting — use for production scheduled scans)
list_trigger_events	List recent trigger events (manual scans, webhooks, scheduled)
trigger_stats	Active runs, rate limiting state, failure counts
list_scan_schedules	List cron-based recurring scan schedules
run_scan_schedule	Manually trigger a scheduled scan now

Infrastructure graph

Tool	Description
list_repositories	List all InfraDB repositories with node/edge counts
get_repository	Get repository details
list_branches	List branches in a repository (each branch is an independent graph state)
get_branch	Get branch details — head commit, graph stats
get_graph	Get the full materialized graph (all nodes + edges) for a branch
create_branch	Create a new branch (fork from existing for analysis)
list_commits	List commits on a branch (newest first) — each commit is a graph delta
diff_commits	Diff two commits — shows added/removed/modified nodes and edges
search_nodes	Full-text search for nodes in a repository
list_branch_attack_paths	List raw JEPA attack paths stored on a branch (pre-triage)
infra_stats	Overall InfraDB stats — repo count, total nodes/edges, storage

JEPA inference

Tool	Description
run_inference	Trigger a batch JEPA inference run on a branch — discovers attack paths automatically
list_inference_runs	List recent inference runs
get_inference_run	Get inference run status and results
ingest_detection	Ingest a security detection from an external tool (scanner, SIEM) to trigger targeted inference
list_inference_schedules	List JEPA inference schedules (cron-based recurring runs)
create_inference_schedule	Create a recurring inference schedule (e.g. nightly on all branches)
delete_inference_schedule	Delete an inference schedule

Triage

Tool	Description
list_attack_paths	List attack paths — filter by status (new/acknowledged/validated/escalated) and min risk score
get_attack_path	Get full path details — steps, MITRE ATT&CK mappings, risk score, energy breakdown
update_path_status	Update triage status (acknowledge, close, etc.)
validate_path	Dispatch a path for sandbox validation (Parser → Exploit → Grader agents in an isolated container)
escalate_path	Escalate a validated path to the ticketing system
triage_stats	Triage statistics — counts by status, severity, repository

Webhooks

Tool	Description
register_webhook	Register a webhook for triage events (e.g. Slack notification on new attack paths)
list_webhooks	List registered webhooks
delete_webhook	Delete a webhook
test_webhook	Send a synthetic test event to verify delivery
webhook_deliveries	Get delivery history — success/failure per attempt
validate_webhook_template	Validate a Jinja2 webhook template against sample data

Connectors

Tool	Description
list_connectors	List data source connectors (GuardDuty, Inspector, Qualys, Tenable, etc.)
create_connector	Create a new connector for automated artifact ingestion
get_connector	Get connector details — status, last poll time, config
update_connector	Update connector config or enable/disable
delete_connector	Delete a connector
poll_connector	Trigger an immediate poll (fetch latest data from the source now)
test_connector	Test connectivity without persisting artifacts
connector_health	Health summary across all connectors — sorted unhealthy-first
list_connector_types	List available connector types and their required config fields
ingest_stats	Ingestion stats — total artifacts, connector health, last poll times

Validation & ticketing

Tool	Description
get_validation_status	Get validation run status — step counts, progress, verdict
list_tickets	List remediation tickets
get_ticket	Get ticket details — linked attack path, status, external ticket URL

Graph-oracle (interactive JEPA tools)

These tools power the /research skill. They auto-manage an oracle session — no manual session creation needed.

Tool	Description
oracle_load_branch	Load a branch graph into the JEPA engine. Returns immediately — encoding runs in background (2-5 min for large graphs)
oracle_load_status	Check if graph encoding is complete (encoding → loaded)
oracle_graph_info	Get loaded graph stats — node/edge counts, type distribution, available edge types
oracle_list_nodes	Browse nodes by type (e.g. all k8s_ingress nodes)
oracle_get_node	Semantic node lookup — returns best match with full neighbor details
oracle_search_nodes	Search nodes by text similarity using MiniLM embeddings
oracle_tm_add_node	Add a node to the threat model
oracle_tm_add_edge	Add an edge to the threat model
oracle_tm_show	View the current threat model (nodes and edges)
oracle_tm_clear	Clear the threat model and start fresh
oracle_tm_match	Match threat model against real infrastructure — returns Mermaid diagram with node matches (cosine scores), BFS paths (energy scores), and implicit edges
oracle_tm_match_refine	Iterative energy-scored refinement — returns per-iteration Mermaid diagrams with entry candidates, per-hop transition energy, and convergence status
oracle_submit_attack_path	Submit a discovered attack path as a chain of node descriptions (e.g. "API gateway → auth service → database")
oracle_submit_matched_path	Submit all matched paths from the current threat model to triage
oracle_tm_list_templates	List built-in threat model templates (identity, network, data, supply chain, cloud)
oracle_tm_load_template	Load a template into the threat model (replaces current)
oracle_tm_save	Save the current threat model as a reusable template
oracle_reset_session	Destroy the oracle session and start fresh