Tool reference
Devici MCP exposes 17 tools across five functional groups. This page documents every tool: what it does, the parameters it takes, and the behavior to watch for.
| Group | Tools | Purpose |
|---|---|---|
| Threat models | 6 | Create, update, validate, export, import, and snapshot threat models |
| Threats & mitigations | 2 | Generate threats and add mitigations to existing models |
| Codex content | 4 | Browse the codex and assign attributes / threats / mitigations from it |
| Browse & search | 3 | Search collections, the codex / library, and dashboard reports |
| Gateway | 1 | Direct API request for advanced cases |
| Skills | 1 | Load a workflow runbook on demand |
When to call which tool
For most "build a threat model" requests, use threat_model_import_otm. It produces a fully rendered visual canvas in one call. Use threat_model_create only when you don't need the visual diagram. Use the codex_* tools to attach Devici's curated attributes, threats, and mitigations rather than inventing them off-hand.
Permissions model
Devici MCP doesn't have its own tokens or scopes — it uses the same API tokens you'd issue for direct Devici Standard API access. Each token has the scopes you set at creation, and the Standard API enforces those scopes per tool call (a call outside scope returns 403 Insufficient scope). To restrict what an agent can do, create a token that only has the scopes you want it to have. See Authentication.
Threat models
threat_model_create
Create a complete threat model in one operation. Orchestrates model → canvas → components → threats → mitigations.
| Parameter | Type | Description |
|---|---|---|
name |
string | Threat model name (≤ 64 chars) |
collection_id |
string | Target collection ID |
description |
string | Model description (optional) |
canvas_name |
string | Canvas name (defaults to model name) |
components |
JSON array | Components: [{name, type, ...}] |
threats |
JSON array | Threats: [{name, component_ref, ...}] (component_ref is index or name) |
mitigations |
JSON array | Mitigations: [{name, threat_ref, ...}] (threat_ref is index or name) |
mode |
string | apply (default) or dry_run |
extra_properties |
JSON object | Additional model properties |
Empty canvas
threat_model_create produces an empty canvas diagram. For a visual canvas with rendered nodes, edges, trust boundaries, and colored dataflows, use threat_model_import_otm instead.
threat_model_update
Update an existing threat model with a delta of changes. Add, update, or remove components, threats, and mitigations in one call.
| Parameter | Type | Description |
|---|---|---|
threat_model_id |
string | ID of the model to update |
updates |
JSON object | A delta with any combination of: metadata, add_components, update_components, remove_components, add_threats, update_threats, remove_threats, add_mitigations, update_mitigations, remove_mitigations |
mode |
string | apply (default) or dry_run |
threat_model_validate
Validate a threat model for completeness and integrity. Checks that canvases exist, components have threats, threats have mitigations, and there are no orphaned entities.
| Parameter | Type | Description |
|---|---|---|
threat_model_id |
string | Model to validate |
Returns a structured report listing any issues found, plus counts and stats.
threat_model_export
Export a threat model.
| Parameter | Type | Description |
|---|---|---|
threat_model_id |
string | Model to export |
export_format |
string | otm (default) — Open Threat Model JSON, identical to the UI's OTM export and round-trip-safe with threat_model_import_otm; or summary — counts + component/threat names |
threat_model_import_otm
Preferred tool for creating threat models with visual canvas diagrams. Imports an Open Threat Model (OTM) JSON and creates the full hierarchy: model, canvas with rendered nodes / edges, components, threats, and mitigations, all in a single call.
| Parameter | Type | Description |
|---|---|---|
collection_id |
string | Target collection ID |
otm_content |
string | Devici OTM JSON string. Must be passed inline — the MCP server is remote, so local file paths aren't reachable. |
threat_model_content_snapshot
Snapshot the attributes / threats / mitigations attached to a model. Useful before assigning new codex content so you don't duplicate what's already there.
| Parameter | Type | Description |
|---|---|---|
threat_model_id |
string | Target model UUID |
flat |
boolean | When true, return a flat (deduped by title) shape; otherwise nest by component / threat |
Threats & mitigations
threat_model_generate_threats
Generate or save threats for a threat model using STRIDE or LINDDUN. Two-phase workflow.
| Parameter | Type | Description |
|---|---|---|
threat_model_id |
string | Target model ID |
methodology |
string | STRIDE (default) or LINDDUN |
target_component_ids |
JSON array | Component IDs to focus on (empty = all) |
threats_to_save |
JSON array | Threats to persist. Leave empty for the analysis phase. |
Phase 1 (analyze): Call with empty threats_to_save. Returns model structure plus a methodology guide.
Phase 2 (apply): Call with threats_to_save populated. Persists the threats.
MAESTRO and other frameworks
threat_model_generate_threats itself is STRIDE / LINDDUN only. For MAESTRO and any other framework that lives in your codex, use the codex_* tools instead. They cover any built-in or custom methodology.
threat_model_add_mitigations
Batch-create mitigations for existing threats.
| Parameter | Type | Description |
|---|---|---|
mitigations |
JSON array | Mitigations: [{threat_id, name, description, ...}] |
Codex content
The codex is Devici's library of attributes, threats, and mitigations: built-in plus your workspace's custom content. The codex tools let an agent assign curated content rather than invent it off-hand.
How the codex chain works
When you assign attributes to a component, Devici uses the codex to attach the threats those attributes are linked to, plus each threat's default mitigations — all in one step. So in many flows you only need codex_assign_to_component with attributes; the rest follows from the codex.
codex_browse
Browse the Devici codex (built-in + custom) by methodology and content type. Returns the methodology and mitigation catalogs (so you can discover framework UUIDs) plus matching attributes / threats / mitigations.
| Parameter | Type | Description |
|---|---|---|
source |
string | built_in, custom_codex, or both (default) |
content_type |
string | attributes, threats, mitigations, or all |
methodology |
string | Filter built-in threats to a framework, e.g. STRIDE, MAESTRO, LINDDUN. Ignored for custom codex. |
text |
string | Free-text search |
detailed |
boolean | When true (default), fetch detailed shapes (caused_by, neutralized_by, mitigations, explanation, consideration, assignable_to_components) |
limit |
integer | Page size (default 100) |
page |
integer | Page offset. Pagination is offset-based, so use page=0, 100, 200, … not 0, 1, 2, … |
catalog_only |
boolean | Return only catalogs (skip attribute / threat / mitigation lists) |
codex_assign_to_component
Attach codex attributes / threats (and optional mitigations) to a component. Built-in or custom-codex attributes bring their linked threats onto the component through the codex, so usually you only need attributes.
| Parameter | Type | Description |
|---|---|---|
component_id |
string | Target component UUID |
attributes |
JSON object | {built_in: [uuid…], custom_codex: [uuid…], custom: [{title, description}, …]} (each list capped at 20) |
threats |
JSON object | Same shape; custom items need {title, description, priority, status?} |
sync_mitigations |
JSON array | Optional mitigation ops to run after the threats step: [{threat_id, built_in, custom_codex, custom}] |
mode |
string | apply (default) or dry_run |
codex_assign_to_threat
Attach codex mitigations to an existing threat.
| Parameter | Type | Description |
|---|---|---|
threat_id |
string | Target threat UUID |
mitigations |
JSON object | {built_in: [uuid…], custom_codex: [uuid…], custom: [{title, definition?, consideration?, explanation?, example?, question?}, …]} |
mode |
string | apply (default) or dry_run |
codex_assign_bulk
Bulk-apply codex content across many components and threats in one call. The fastest path for content passes over an entire model.
| Parameter | Type | Description |
|---|---|---|
attribute_ops |
JSON array | [{component_id, built_in?, custom_codex?, custom?}] (max 20) |
threat_ops |
JSON array | [{component_id, built_in?, custom_codex?, custom?}] (max 20) |
mitigation_ops |
JSON array | [{threat_id, built_in?, custom_codex?, custom?}] (max 20) |
mode |
string | apply (default) or dry_run |
built_in and custom_codex accept either UUID strings or {id: <uuid>} objects. Both are normalized.
Browse & search
collection_search
Search and browse Devici collections.
| Parameter | Type | Description |
|---|---|---|
query |
string | Search by name or description |
collection_id |
string | Get a specific collection by ID |
include_threat_models |
boolean | Include nested threat models in the response (default true) |
limit |
integer | Page size (default 20) |
page |
integer | Page number |
library_search
Search the Devici codex and threat / mitigation libraries.
| Parameter | Type | Description |
|---|---|---|
query |
string | Search text |
search_type |
string | codex (default), threats, or mitigations |
limit |
integer | Page size (default 20) |
page |
integer | Page number |
dashboard_report
Get Devici dashboard analytics and reports.
| Parameter | Type | Description |
|---|---|---|
report_type |
string | dashboard_types, dashboard_data, or threat_models_report |
chart_type |
string | Required when report_type is dashboard_data |
start |
string | Start date (ISO format) |
end |
string | End date (ISO format) |
project_id |
string | Filter by project |
limit, page |
integer | Pagination |
Gateway
The gateway is an escape hatch for advanced cases that the workflow tools don't cover. Most users will never call it directly.
Sensitive surface
The gateway sits closer to the raw Devici API than any other tool. The endpoint is gated by the MCP server's allowlist — calls to non-allowlisted endpoints return 403. Issue the token with only the scopes the gateway actually needs, and store the credentials in your secret manager (never in source).
devici_api_request
Make an allowlisted Devici API request. Use as an escape hatch for any endpoint not covered by a workflow tool.
| Parameter | Type | Description |
|---|---|---|
method |
string | HTTP method: GET, POST, PUT, DELETE |
endpoint |
string | API path, e.g. /users/ or /threat-models/abc123 |
params |
JSON string | Query parameters |
body |
JSON string | Request body |
The endpoint must be on the server's allowlist. Calls outside the allowlist return 403. Within the allowlist, the call is governed by the token's scopes (the same scopes that gate every other tool — see the Permissions model note above).
Skills
The MCP server hosts workflow runbooks as skills — markdown files the agent loads on demand to drive multi-step tasks. The agent calls this on your behalf; you don't normally invoke it directly.
load_skill
Fetch a workflow runbook by slug.
| Parameter | Type | Description |
|---|---|---|
name |
string | Skill slug, e.g. generate-threat-model, import-otm, codex-content-agent, drawio-to-otm, manage-collections, export-report, threat-prioritization, api-gateway, troubleshooting |
Returns {name, content} on success, or {error, available} listing valid slugs if the name doesn't match.
See also
- Playbooks — common end-to-end task patterns
- Authentication — how the API token is issued, used, and revoked
- Troubleshooting — error codes and OTM shape gotchas