AI Agent Access (MCP)

ArchRepo supports the Model Context Protocol (MCP) , allowing you to connect AI agents such as Claude Desktop or Cursor directly to your project’s architecture model.

Once connected, your AI agent can browse model items, read architectural narratives, explore the metamodel, and navigate relationships — all using your own ArchRepo identity.

Prerequisites

Before connecting, make sure you have:

• An ArchRepo account at archrepo.com 
• MCP enabled for your project — ask a project admin to turn on MCP Enabled in Project Settings

On first connection, your AI agent will open a browser window asking you to sign in with your ArchRepo account.

Connecting with Claude Desktop, Cursor, Windsurf, or other MCP clients

Use the Streamable HTTP transport URL:

https://archrepo.com/api/mcp

If your client only supports the legacy SSE transport, use:

https://archrepo.com/api/sse

Your MCP client will prompt you to sign in with your ArchRepo credentials when it first connects.

Ask — the built-in AI assistant

You don’t need an external MCP client to get AI help with your architecture — Ask is ArchRepo’s own built-in AI assistant, available directly inside the app. It draws on the same read-only tools described below (model items, tasks, metamodel, dependency graphs, and more), so you can ask it questions in plain language without connecting anything.

Ask also has one capability the external MCP tools don’t: it can answer questions about a delivery team’s tasks directly — for example, “find me all tasks assigned to the BA Team”. See Finding a delivery team’s tasks below for how it decides which tasks belong to a team, and how to word the team’s name so it finds the right one.

Completion, blocking & impact questions

Ask can also answer three question shapes about where a project’s specifications stand, without you needing to know which lens applies:

• “What’s the plan? What’s the bottleneck? What can start now?” — Ask returns a build sequence: the ordered layers of work, the critical path driving the overall timeline, the biggest bottlenecks, and any blockers or coverage gaps standing in the way. Ask about a specific milestone to scope the answer to just that milestone’s items.
• “Why is X blocked? What is X still waiting on?” — Ask explains exactly what’s holding one item back: an upstream item it reads from that hasn’t been approved yet, an open Issue or undecided Design Decision it references, another unsettled dependency, or being caught in a dependency cycle.
• “What slips if X is blocked or deferred?” — Ask reports the downstream impact of one item staying blocked (or being deliberately deferred): which items are directly held up by it, which are only delayed with some runway before it bites, and — if X sits on a dependency cycle — which items only look affected because they share that cycle, not because they’re genuinely downstream of it.

Every answer states which lens it’s under — design completeness, build/develop sequencing, or data availability — since the same question can have a different answer depending which one you mean (see Specification Completeness & Dependency Lenses below). These answers are read from the exact same underlying dependency derivation as the Build tab and the tools below, so Ask, the Build tab, and an external AI agent connected via MCP never disagree with each other. Any item Ask names as a blocker is a clickable link straight to that item.

Available Tools

Once connected, your AI agent has access to the following tools:

Discovery

Your agent calls list_my_projects first to discover available projects. You can then refer to a project by name — for example, “look at the Platform project” — and the agent will use the correct IDs automatically.

Metamodel

Concern Overviews

Model Items

Data Sets

Tasks

Finding a delivery team’s tasks

Both fetch_project_tasks (team parameter, above) and Ask — via its own fetch_team_tasks tool — can scope a task list to a single delivery team. Both follow the same rule, so the answer always matches what you’d see on that team’s Tasks tab in ArchRepo:

• A task is included if the team owns it directly, or if it’s assigned to a member of that team and no other team.
• A task assigned to someone who belongs to more than one delivery team, with no explicit team assignment, is left out — attributing it to one team over another would just be a guess. Instead, the response includes a summary (or, for Ask, a plain-language note) stating how many such tasks were excluded and why, so the count is never silently missing.

Naming a team: you can identify a team by its name (not case-sensitive — “ba team” matches “BA Team”), its reference (e.g. "DT004"), or its Model Item ID. If your wording doesn’t match any team, the tool tells you the closest team names it found instead of guessing. If it matches more than one team (for example, two teams that happen to share a name), it lists every match rather than picking one — rephrase using the ref or Model Item ID to be specific.

Milestone Reporting

get_milestone_readiness output includes:

• Milestone header — name, ref, and date
• Summary — total item count, number baselined, pending review, draft, and total open tasks
• Per-item data — status, readiness score, scopeDescription (the free-text description of what is in scope at this milestone), milestoneBaseline (the baseline specifically tagged to this milestone), latestBaseline (the most recent baseline regardless of tagging), and open task count
• Warning — if no items have been added to scope yet, a message is returned explaining how to add them via the Milestone Scope tab in ArchRepo

By default (includeInactive: false), in-scope items whose status is Deleted, Archived, or Rejected are excluded from both the item list and the summary counts. An item is not removed from a milestone’s scope when it is archived or rejected, so counting it would overstate the milestone’s remaining work. Pass includeInactive: true to include them. If every in-scope item is superseded, the warning says so — distinct from the “nothing has been scoped yet” warning, because the remedy differs.

Milestone scope entries can be added and managed via the Milestone Scope tab on a model item in ArchRepo, or programmatically via the update_milestone_scope tool.

Dependency Graph

get_build_dependency_graph output includes:

• nodes — one entry per in-scope item: id, ref, name, type, status. Pass includeReadiness: true to also include readinessScore and buildReadiness.state on each node (omitted by default to keep the response lean).
• edges — directed connections in the form { from, to, relationshipType }. from depends on to — in other words, to must be developed and tested first. Only relationship types that represent a genuine construction/build-order dependency are included (the same isBuildOrderDependency classification returned by get_metamodel_type_details — e.g. uses, supports, contains, depends on); purely informational or data-flow relationships (e.g. generates, triggers) never appear as edges. Both ends of every edge are guaranteed to be in the returned node set — a dependency pointing at an item excluded by itemTypes or milestoneId is simply left out rather than reported separately.

By default (includeInactive: false), items whose status is Deleted, Archived, or Rejected are excluded from both nodes and edges, consistent with get_all_model_item_relationships; pass includeInactive: true to include them.

This tool returns the raw graph only. It does not compute a critical path, build sequence, or “what unblocks this” analysis — ask your agent to reason over the returned graph, or use a more specialised tool if one is available.

This is the build/develop lens only — what must be developed and tested before what. For the other two lenses ArchRepo’s dependency tooling offers over the same architecture — specification completeness and integration-test / data availability — see Specification Completeness & Dependency Lenses below.

Specification Completeness & Dependency Lenses

Passing phase: "develop" explicitly asks for the same build/develop lens, with one refinement: a dependency is only shown between two items that are both real buildable components (applications, services, APIs, data sets, data stores, UI components, reports, streams, and similar) — so a requirement, non-functional concern, task, or open issue never shows up as something else “depends on,” and an Environment hosting the things deployed to it is not shown depending on them. The plain default call (no phase argument) does not apply this refinement and can occasionally include such items.

Specification Completeness

get_specification_completeness and get_build_dependency_graph with phase: "design" are equivalent — same underlying data, same response shape — so use whichever your agent finds first. get_specification_completeness exists as its own named tool specifically so this lens shows up on its own when an AI agent lists what’s available, rather than being hidden behind a parameter on the build-order tool.

This lens looks at data dependencies at the level of individual pieces of data, not whole datasets. Normally, if an item reads from a large shared data set, the build-order view says it depends on the whole data set — even if only one small part of it, written by one specific item, is actually relevant. The specification-completeness view instead says the item depends on whichever item specifically writes the data it reads — often a much shorter, more accurate chain.

On top of data dependencies, this lens also carries the full set of interface and containment dependencies between specs:

• An item that uses another building block (an application, service, API, data set, data store, stream, data flow, report, or environment) is shown depending on it.
• An item that implements an Application Pattern, Business Rule, or Use Case is shown depending on it (implementing a Concept does not create a dependency — Concepts are reference material, not something to be “ready”).
• An item that contains other specs (e.g. an Application containing its UI Components) is shown depending on all of them, and that roll-up carries through nested containment automatically. Containment used purely to describe where something is deployed (an Environment or Infrastructure Environment hosting something) is not treated as a spec dependency, since deployment placement isn’t part of what needs to be designed and approved first.
• If one item already contains another, a separate “uses” dependency between the same pair is not shown twice — the containment relationship already captures the ordering. A “uses” dependency to anything else is unaffected.

The graph also widens to include Issues and Design Decisions: an item that references an unresolved Issue or an undecided Design Decision is shown as depending on it, since the spec can’t really be considered complete until that’s resolved. Once the Issue is closed (or the Design Decision is Approved), that dependency drops away automatically.

Each item in the response carries an entityIO field showing how confidently its data dependencies are known:

• mapped — this item’s data reads/writes are fully documented via Data Mapping.
• declared-none — someone has explicitly confirmed this item genuinely has no data to map.
• unmapped — this item’s data reads/writes haven’t been documented yet. When the item’s type is expected to have data mapping, it also carries expectation: "expected-but-unmapped" — a genuine gap worth closing; otherwise "not-expected".

The response also includes:

• coverage — this is specifically data-mapping coverage: project and criticalPath mapped/total counts of items with documented data dependencies. It says nothing about whether interface or containment dependencies are documented, since there’s no equivalent check for those yet. Treat a low ratio as a sign the plan is provisional — but don’t read a high ratio as “the whole plan is fully trustworthy,” since it only speaks to the data side.
• expectedButUnmapped — the list of items driving that data-mapping coverage gap.
• blockers — items on the critical path that are waiting on a specific upstream item to be Approved before they can be considered unblocked.

Integration-Test / Data Availability

Pass phase: "availability" to get_build_dependency_graph to trace the actual movement of data through the architecture — including relationships like generates, receives, and provides data for that the build-order view deliberately ignores — and points dependencies the direction data actually has to flow: a consumer depends on its upstream data producer. Pure pass-through items (data flows, streams) are automatically skipped over, so a consumer is shown depending on the real originating source, not an intermediate carrier.

Both the specification-completeness and data-availability responses use the same node/edge shape as the build-order view, plus a source on each edge (why the dependency exists: an interface dependency — uses/implements, a containment dependency, a resolved data dependency, a documented relationship, a pass-through carrier being skipped over, or a blocking Issue/Design Decision).

Effort and Impact

Add includeDuration: true (to either get_specification_completeness or get_build_dependency_graph with any phase) to also see each item’s estimated completion duration and remaining effort — rolled up along its longest dependency chain from the tasks logged against it and everything it depends on. Add blockedItemId (an item’s reference or ID) to also see that item’s blast radius: every downstream item affected if it stays blocked, each marked as either directly held up by it (gated) or only affected after some runway runs out (delayed, with the number of days of runway shown).

Cycles

A dependency cycle — A needs B, B needs C, C needs A — has no valid build order. ArchRepo never throws on one or loops forever; it reports it and carries on.

Two independent cycle signals come back, and they can legitimately disagree:

• criticalPath.hasCycles / criticalPath.cycleIds — computed over the architecture dependency edges only. When hasCycles is true, do not read criticalPath.path as a linear prerequisite sequence.
• inCycle on each node (with includeDuration: true) — computed over the task-augmented graph, which also includes cross-specification task dependencies the architecture edges never show.

So a project can report hasCycles: false while several nodes are inCycle: true. That is not a contradiction — it means the cycle is task-induced, created by how the work was scheduled rather than by the architecture itself.

An inCycle node also carries cyclePosition:

• "on" — the node is itself mutually reachable within the cycle. It also carries cycleId, cycleMemberIds (everything on that cycle), and cycleEdges: a shortest closed walk through it, one entry per edge. Each edge is attributed source: "derived" (an architecture dependency) or source: "task" (a cross-specification task dependency, named by taskRef). The "task" edge is usually the one to point at first when explaining a cycle, precisely because the architecture view never shows it. Check whether a cycle’s cycleEdges are all "derived" (an architecture cycle too) or include a "task" edge (task-induced only) before reporting the cause.
• "downstream" — the node merely depends on a cycle without being on it, and carries downstreamOfCycleId naming that cycle. Describe it as blocked by an upstream cycle, never as in a cycle.

Relationship Graph

get_relationship_graph output includes:

• nodes — one entry per in-scope active item: id, ref, name, type, status. Pass includeReadiness: true to also include readinessScore and buildReadiness.state on each node (omitted by default to keep the response lean).
• edges — compact [fromIndex, toIndex, relationshipType] tuples. fromIndex and toIndex are positions in the nodes array of this same response (this keeps the payload small on large graphs). from owns the relationship, and to is its target — this describes how the connection is recorded, not a dependency or build order. Unlike get_build_dependency_graph, do not read to as “must be built first”. Both ends of every edge are guaranteed to be in the returned node set — an edge pointing at an item that’s excluded or out of scope is simply left out rather than reported separately.

Scoping the graph:

• itemTypes — an allow-list of item types to include (e.g. ["system", "api", "stream"]). This is the recommended way to keep the response small, and is often all you need. Supplying itemTypes turns off the default exclusion list below (an explicit allow-list is the scope), unless you also pass excludeTypes yourself.
• When itemTypes is omitted, nodes are restricted to the active structural architecture. Items whose status is Deleted, Archived, or Rejected are excluded by default (pass includeInactive: true to include them), and a fixed set of item types that sit outside the structural architecture are excluded by default, since they represent delivery tracking, governance, or reference material:
  • Delivery — tasks, delivery increments, delivery groupings, milestones, releases, delivery organisations
  • Governance / rationale — risks, issues, assumptions, design decisions
  • Reference / support — media, FAQs, glossary terms, requests, artefacts, business references
• excludeTypes — override or extend that default exclusion set. Any item type not listed is included automatically, so new item types show up without this tool needing an update.

Very large projects: if the in-scope graph has more nodes than maxNodes (default 1000), the tool returns a short summary — { tooLarge: true, nodeCount, edgeCount, maxNodes, nodeCountsByType } — instead of the graph, rather than returning a partial one. Use the per-type counts in nodeCountsByType to re-run scoped to the types you actually need via itemTypes (and/or a milestoneId), or raise maxNodes to fetch the whole thing.

Seed-scoped neighbourhood — “show me what’s around this item”: pass seedItemIds (one or more item references or IDs) to get back only those items plus everything within hops connections of them, instead of the whole in-scope graph. hops defaults to 1 and can be raised up to 5. By default the neighbourhood is traced in both directions (seedDirection: 'both'); pass 'out' or 'in' to follow only relationships the seed owns, or only relationships pointing at the seed. A seed item is always included in the response even if its type would normally be excluded. The response also includes a seeds list confirming which items were resolved. Because the item-count limit above is checked after narrowing to the neighbourhood, seeding is a good way to fetch a useful slice of a project that would otherwise be too large.

This tool returns the raw graph only. It does not compute a critical path, build sequence, or impact analysis — use get_build_dependency_graph or get_item_impact for those questions.

Impact Analysis

get_item_impact output includes:

• item — the queried item’s id, ref, name, type, and status.
• precedes — everything the item transitively depends on: its prerequisites, what must be developed and tested first.
• unblocks — everything that transitively depends on the item: its downstream impact, what gets blocked if this item slips.

Each node in precedes and unblocks carries a depth (1 = direct, 2+ = transitive hops) plus the same core fields as get_build_dependency_graph nodes. Pass includeReadiness: true to also include readinessScore and buildReadiness.state (omitted by default). Traversal is cycle-safe — a cyclic graph returns each reachable node once — and follows only the same construction/build-order dependency edges as get_build_dependency_graph (see the data-flow-exclusion limitation noted above). Traversal is unbounded by default; pass maxDepth to cap the number of hops walked in each direction on very large graphs.

By default (includeInactive: false), items whose status is Deleted, Archived, or Rejected are excluded from the traversal, consistent with get_build_dependency_graph. An inactive item leaves the node set entirely, so a chain that reaches a node only through one terminates there rather than routing around it. Pass includeInactive: true to traverse them.

Graph Hubs

get_graph_hubs output includes:

• metricScopes — names the edge set behind each metric, since the two are computed differently and are not interchangeable.
• totalNodesConsidered — the full in-scope item count, before topN truncation.
• hubs — the ranked list. Each entry carries the item’s id/ref/name/type/status, its inDegree/outDegree/totalDegree, its blastRadius, and its 1-based rank under the requested ordering.

Two distinct metrics are reported, never combined into one score:

• degree (inDegree/outDegree/totalDegree) — relationship-graph connectivity: how many stored relationships, of any type and in either direction, touch the item. Duplicated relationship rows are deduplicated before counting.
• blastRadius — build-order downstream reach: the same transitive count get_item_impact’s unblocks would report for that item, computed over the construction/build-order dependency edges only.

Pass rankBy ('degree', 'blastRadius', or 'both', default 'both') to choose the ordering. 'both' orders by total degree first, blast radius second, and item reference third — two sort keys, not a summed score, so the two metrics stay legible rather than blended into a meaningless composite. topN bounds the returned list (default 20, maximum 100).

itemTypes, excludeTypes, milestoneId, and includeInactive scope the computation the same way they do for get_relationship_graph — both metrics are computed within that scope, so a relationship to an item outside it never counts toward either.

Connection Path

get_connection_path output includes:

• from / to — the resolved id, ref, name, type, and status of the two queried items.
• found — whether a connecting path exists within maxHops.
• paths — an ordered array of hops for each returned path. Each hop carries the source node (id/ref/name/type/status), the relationshipType it travels through, and traversedAgainstStorageDirection — false when the hop follows the relationship’s own recorded direction, true when it was walked backwards — so a caller can render the connection correctly (e.g. “API024 supports UC-11” rather than implying the reverse). The final hop’s destination is the top-level to item.
• truncated — true if more equal-length shortest paths existed than maxPaths allowed returning.

If found is false, reason explains why: disconnected (no path exists between the two items at all) or maxHopsExceeded (a path may exist, but only beyond maxHops, and re-running with a higher maxHops might find it). This is a normal answer, not an error.

Only the shortest path length is ever returned — a longer alternate is never substituted for a shorter one. When several paths tie for shortest, up to maxPaths (default 3, maximum 10) of them are returned. maxHops bounds how far the search looks before giving up (default 6, maximum 10). direction ('out', 'in', or 'both', default 'both') controls whether the path must follow relationships in their recorded direction, against it, or either — 'both' is usually what you want, since relationship direction reflects who recorded the connection, not which way it “matters”.

itemTypes, excludeTypes, and includeInactive scope the traversal the same way they do for get_relationship_graph; the two queried items are always considered regardless of these filters.

This tool returns the raw connecting chain only — it does not narrate or explain the path in prose, and it does not compute a “best” path by readiness or effort, only the shortest one by number of hops.

Data Lineage

get_data_lineage output includes:

• threads — the rationalised chains, one per entity and direction, ordered with the focal item first. Each hop carries the item (itemId/ref/name/type/status), its role (focal, source, transform, or consumer), the entity it connects through, the action (reads/writes/modifies), and provenance.
• rawThreads — the same chains with pass-through carriers spliced back in. Expand these only if asked for the literal transport path.
• rationalisation — what was simplified to produce threads (see below).
• cycleItemIds — items caught in a lineage cycle, surfaced rather than thrown.

Pass entity to trace a single entity thread — the best way to answer a specific “where does field X come from” question. Omit it to trace every entity the focal item touches. Pass direction to restrict to upstream (sources) or downstream (consumers).

Resolution is entity-level, not dataset-level: writers or readers of a different entity in the same dataset never appear in a thread. And the trace is derived on read from existing data mapping and relationships — not a stored inverse index — so it can never go stale relative to the model.

When reporting a chain, use the entity and item display names, never raw metamodel type names.

Relationships

Baselines

Media

Recommended workflow

At session start: call fetch_my_tasks to understand the user’s current workload before diving into analysis. Use optional filters — for example progress: ["Backlog"] for weekly planning, or piId to focus on tasks in a specific sprint.

Before updating a task: call fetch_task_details to read the current state of the task, including its PI, team, dependencies, and linked items. Your agent uses this to show you a clear Before / After summary before making any changes.

To update your Focus Now list or task order: call add_focus_now to pin a task to your personal shortlist, or set_task_order to reorder a section. Both tools are scoped to your identity — changes are personal and not visible to other project members.

To update task progress or status independently: use update_task_progress to record a completion percentage (with an optional note) or update_task_status to change the task’s status — including marking it as Blocked. These are focused alternatives to update_task when you only need to update a single field.

Creating or updating tasks: create_task and update_task require Editor role on the project. Your agent will always describe what it is about to do and ask you to confirm before writing any changes.

To understand a concern area at a glance: call get_concern_overview with a concern name (e.g. "Business" or "Apps & Systems"). This returns the concern narrative, each topic’s narrative, and the first batch of items per topic — giving you a structured entry point before drilling into individual items.

When you don’t know the item ID: call search_model_items first to locate the item by keyword, then use the returned id with the tools below.

For a thorough analysis of any architecture item, call the tools in this order:

1. get_model_item — get core metadata and the readiness score, which summarises completeness across all relationship categories
2. get_all_model_item_properties — get all stored properties: external references, approval state, and all type-specific fields
3. get_all_model_item_relationships — get the full picture of connections: both outbound (what this item points to) and inbound (what points to this item)
4. get_model_item_narrative — read the full architectural description, design decisions, and diagrams. If the narrative contains image references (lines starting ![), call get_item_images with the same item to retrieve diagram data for visual interpretation.
5. get_data_set_schema — for any related Data Set items, fetch the full entity model and field definitions

For a comprehensive single-call view: use get_model_item_spec to retrieve the complete specification as Markdown in one call — equivalent to the full 5-step sequence above, with all properties, narrative, relationships, and (for DataSets) the full data model. If the result contains image references (lines starting ![), call get_item_images to retrieve diagram data.

To generate a milestone readiness report:

Call get_milestone_readiness with the milestone’s model item ID. This returns all in-scope items in a single call, with their status, baseline status, readiness score, scope description, and open task counts. Use list_my_projects → list_model_items (with type: "milestone") to find the milestone ID if you don’t have it.

To add or update milestone scope entries:

Call update_milestone_scope with the model item ID and a list of operations. Each operation targets a milestone by ID and specifies whether to add (with a description), update (to replace the description), or remove the entry. Use list_model_items with type: "milestone" to find milestone IDs.

To copy relationships from one item to another:

Call copy_model_item_relationships with the source and target item IDs. Both items must be the same metamodel type. Pass ofMetamodelTypes to restrict the copy to specific relationship categories (e.g. ["businessOutcome", "useCase", "businessRequirement"]).

Linking items by ref (recommended):

When asking your agent to link items, refer to them by their human-readable ref — e.g. “link UI-062 to FR-021, FR-010, NFR-101, and NFR-017”. The agent can pass those refs straight to relate_model_items without having to look up Model Item IDs first. Every response from a write tool echoes the resolved itemA / itemB (or source / target) so you can confirm at a glance that the links landed on the right items.

Prompts

In addition to tools, the ArchRepo MCP server provides prompts — pre-built workflow templates that MCP clients can surface as slash commands or quick-start options. Each prompt encodes domain knowledge and the correct tool-calling sequence for a common architectural analysis task.

In Claude Desktop, prompts appear when you click the + button in the chat input. In other MCP clients they may appear as slash commands.

Narratives & Diagrams

The get_model_item_narrative tool returns the narrative as Markdown, converted from ArchRepo’s rich block editor format. It includes:

• Headings, paragraphs, lists, and tables exactly as authored
• Draw.io diagrams as image URLs pointing to ArchRepo’s versioned media endpoint (https://archrepo.com/dashboard/org/{orgId}/prj/{prjId}/mediaDisplay/{mediaId}/{version}). These URLs require authentication. AI agents connected to an authenticated MCP session — such as Claude Desktop — can render these diagrams directly.
• PlantUML diagrams as plantuml code blocks. Claude and other AI tools can read PlantUML syntax and understand the diagram’s structure.
• References to embedded model items, shown as hyperlinks to the item’s page in ArchRepo.
• Data entity tables, shown inline with attribute definitions and optional Mermaid ERDs.

The get_model_item_spec tool returns diagrams using the same versioned media URLs.

If a model item has no narrative, the tool returns (No narrative content).

Enabling MCP for a Project (Admins)

To allow AI agents to connect to a project:

1. Go to Project Settings for the project
2. Toggle MCP Enabled to on
3. Save the settings

Only project members can connect. Non-members receive an error even if MCP is enabled.