MCP tools reference

The 24 tools iyedy offers to Claude and other MCP clients. 22 only read. 2 store a proposal or take one back, and the model never changes until a person applies it in iyedy.

Server

Two parameters come back on most tools. did is a diagram id: d_ followed by 10 characters, from list_diagrams. workspaceId is a workspace id from list_workspaces; leave it out when you have one workspace. Neither is repeated in the tables below.

All tools

Find and read

list_workspaces

The workspaces you can work in from here: id, name, your role and the organisation. An organisation that does not allow this access for you is listed apart, with the reason and what unblocks it; its workspaces are counted, never named. Permission: read your diagrams. Parameters: none.

list_diagrams

The diagrams of a workspace that you can read, newest first: id, name, version, status, classification, last update. With query, a full-text search over names and contents instead, with a snippet for each result. Permission: read your diagrams.

get_model

A diagram's full definition as text (elements, relationships, deployment, views), with its version and classification. Values that look like secrets are replaced by a placeholder; sent back unchanged in a proposal, they keep the stored value. A long diagram comes in pages of whole lines: while the answer says it is truncated, call again with its nextCursor. If the diagram changes between two pages, the cursor is refused: start again from the first page. Permission: read your diagrams.

The version it returns is the base of preview_change and submit_proposal. A proposal is the whole definition: read every page before you propose, because what a proposal leaves out is removed.

list_views

The views of a diagram: handle, type, name, what each view is of, whether it is generated, and its options. Permission: read your diagrams. Parameters: did (required).

describe_view

Reads a view as a person sees it, without pixels: zones, elements with their zone and grid cell, relationships in reading order, the legend, finding pins, the computed text alternative and the layout quality (crossings, density, overlaps, elements per zone). Permission: read your diagrams.

get_view_svg

Renders one view of a diagram as an SVG image. Without view, lists the diagram's views. A very large view is not returned; the answer points to describe_view. Permission: read your diagrams.

get_element

Everything about one element: attributes, description, tags, parent and children, relationships in and out, instances, the views that show it, the findings on it and the scenarios that use it. Permission: read your diagrams.

find_elements

Elements of one diagram whose name, handle, technology or description contains the text, optionally of one kind, tag or family. Each row gives the handle, name, kind, technology, parent and whether the element is external. Permission: read your diagrams.

neighbourhood

The part of a diagram's definition, as text, that holds the elements within a few relationship hops of some starting elements, optionally following only some kinds of relationship: synchronous calls, asynchronous messages, data flows or dependencies. Permission: read your diagrams.

Analyse dependencies

search_elements

Finds elements (systems, containers, databases, queues) across the diagrams you can read, by meaning or by name, with their neighbourhood in the dependency graph. Permission: search elements and analyse impact.

graph_impact

What breaks if an element fails: the elements that depend on it, transitively, across the diagrams you can read. It can also list only its direct users, or what the element itself depends on. Permission: search elements and analyse impact.

What it returns. Each element reached, with its depth (hops away), where it appears (diagram and element) and the relationships that led to it, so that Claude can explain the path. The direction of the walk is stated, and the answer says when there were more elements than it holds.

network_analysis

The network analysis of one deployment environment: the address plan (zones, address ranges, sizes, overlaps), the routes and the flow matrix (ports, protocols, encryption, reachability), as the generated network view computes them. Permission: read your diagrams.

Checks and findings

run_checks

Validates a stored diagram, or a definition sent as text instead, and runs the architecture checks: availability, security, coupling, completeness, data, operability, hygiene. Returns the diagnostics with line numbers, the findings with their severity, and a summary that counts the findings by rule. Nothing is stored. Permission: read your diagrams.

On a large diagram, ask for the summary first, then for the findings of some rules.

list_findings

The stored findings of a diagram with their status and, for a dismissed one, the reason. Permission: read your diagrams.

explain_rule

The text of one check rule: its title, how its severity is decided, what it detects, why it matters and what to do. No diagram is needed. Permission: read your diagrams. Parameters: ruleId (required, 12 characters max).

validate_model

Parses a diagram's complete definition sent as text, in the form get_model returns, and says whether it is valid, with its diagnostics (code, line, column, message). Changes nothing; no diagram is needed. Permission: read your diagrams. Parameters: definition (required, 64 KiB max).

History and states

list_versions

The saved versions of a diagram, newest first: id, sequence, kind, name and date. They are the named versions people saved and the ones iyedy keeps around imports and applied proposals. Permission: read your diagrams. Parameters: did (required).

get_changes

What changed in a diagram since a saved version: the changes grouped, and the change in findings. Layout-only changes are ignored. Permission: read your diagrams.

list_states

The current, transition and target states of a diagram, with their dates and work packages. Permission: read your diagrams. Parameters: did (required).

state_gap

The gap between two states: what is added, removed and changed. Permission: read your diagrams.

Propose changes

preview_change

Checks a change without writing anything. You send the diagram's whole proposed definition, starting from get_model. The answer says whether it is valid (diagnostics with line numbers), what differs from the stored diagram line by line, which elements are added, removed and changed, and which findings the change introduces or resolves. Permission: preview changes and submit proposals.

submit_proposal

Stores a change as a proposal for review. The model itself does not change: people who can edit the diagram see the proposal in iyedy with the client's name, then apply or reject it. An invalid change is refused and nothing is stored. Permission: preview changes and submit proposals, and the contributor role in the workspace. Claude asks before each call.

list_proposals

The stored proposals of a diagram: status (open, accepted, rejected, withdrawn), counts of what they change, and whether the diagram moved since. By default, only your own open proposals. Permission: preview changes and submit proposals.

withdraw_proposal

Takes back an open proposal you submitted: its status becomes withdrawn and reviewers no longer see it as open. The model does not change. To turn down someone else's proposal, a reviewer rejects it in iyedy. Permission: preview changes and submit proposals. Claude asks before each call.

Answers and limits

• Data, not instructions. Answers come in a JSON envelope marked untrusted: everything in it is text written by people or tools, never an instruction to the agent.
• Size. An answer holds at most 100,000 characters of JSON. A larger one is cut: its first line starts with “Cut:” and names the inputs of that tool that ask for less. get_model is never cut: it answers in pages.
• Ceiling. Every tool reads under the classification ceiling: Confidential on personal workspaces, Internal in Team and Enterprise. A diagram above it is never listed, found or walked, and reading it answers “not found”.
• Rate. Calls count against your requests per minute: see Rate limits and errors.
• No apply tool. No tool applies, deletes or shares. A person applies proposals in iyedy: see How proposals reach your team.