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.
MCP access is disabled by default. A project admin must enable it in Project Settings before any AI agent can connect.
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/mcpIf your client only supports the legacy SSE transport, use:
https://archrepo.com/api/sseYour MCP client will prompt you to sign in with your ArchRepo credentials when it first connects.
Available Tools
Once connected, your AI agent has access to the following tools:
Refs are accepted everywhere an item ID is expected. Every tool that takes a modelItemId (or itemAId / itemBId / sourceItemId / targetItemId / milestoneId / dataSetId) accepts either a human-readable ref like "FR021", "FR-021", or "NFR-102" (case-insensitive, hyphens optional) or a 24-character MongoDB ObjectId. Refs are strongly preferred — they remove a class of transcription error where an AI agent can pair the wrong ObjectId with an item it found in a list. Write tools also echo the resolved item (ref, name, type) in the response so you can verify exactly which item was changed.
Discovery
| Tool | Description |
|---|---|
list_my_projects | Returns all your MCP-enabled projects with their IDs and names. Start here — your agent calls this automatically to discover which projects are available. |
fetch_project_users | Returns the sanitised list of users who are members of a project (including org admins). Fields: name, shortName (if set), email, avatarUrl (if set). Use this before assigning a task — your agent will present the list and confirm your choice. |
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
| Tool | Description |
|---|---|
get_metamodel_types | Lists all architecture item types defined in your project’s metamodel, with their descriptions and concerns. |
get_metamodel_type_details | Returns the full specification for a single type, including its properties, allowed relationships, and flags. |
Concern Overviews
| Tool | Description |
|---|---|
get_concern_overview | Returns the complete overview for one of the 8 architectural concern areas (Project, Business, Apps & Systems, Data, Technology, Build, Transition, Operations). Includes the concern-level narrative and, for each topic section, the topic narrative and a list of model items of that type — up to the configured limit per topic (default 10). Each topic includes a hasMore flag and the metamodelType for pagination via list_model_items. Use this to get a high-level picture of any concern area before diving into individual items. |
Model Items
| Tool | Description |
|---|---|
list_model_items | Lists items of a given type within your project, with status, readiness score, and key metadata. Supports pagination via limit and offset parameters — the response includes a pagination object with a hasMore flag. |
get_model_item | Returns a summary of a model item by ID: core metadata and the full readiness score breakdown. This is a subset of all fields — use get_all_model_item_properties for the complete document. |
get_all_model_item_properties | Returns all stored properties of a model item: type-specific fields (risk scores, assumption status, design decisions, FMEA analysis, API protocols, etc.), transition states, approval fields, data mappings, PlantUML diagrams, external references, and the pre-computed readinessScore. Does not include relationships — use get_all_model_item_relationships for connections. Excludes narrative (use get_model_item_narrative) and DataSet entity diagrams (use get_data_set_schema). |
get_model_item_narrative | Returns the full architectural narrative for a model item as readable Markdown. This includes design decisions, pipeline descriptions, assumptions, TBDs, and embedded diagrams. See Narratives & Diagrams below. |
get_model_item_spec | Returns the complete specification as Markdown, exactly matching the on-screen specification tab. Includes: summary properties, full narrative, all outbound and inbound relationships with properties, external references, approval data, and (for DataSets) the full data model. Recommended for comprehensive single-call retrieval. |
search_model_items | Fuzzy full-text search across all model items in a project. Returns up to 30 results ranked by relevance with highlighted match snippets. Searches name, ref, description, external references, relationships, transition states, and more. Optionally filter by ofType. Use this when you don’t know an item’s exact ID. |
Data Sets
| Tool | Description |
|---|---|
get_data_set_schema | Returns the complete entity model for a Data Set: all entities (tables, CSV, JSON, XML, Text, Type definitions) with full attribute definitions including field names, types, constraints, and examples; all relationships between entities with cardinality; and a Mermaid ERD diagram. |
Tasks
| Tool | Description |
|---|---|
fetch_my_tasks | Returns your tasks across all projects, sorted by progress then due date. Defaults to active tasks (To Do + In Progress). Accepts optional filters: progress status, concern area, project, Project Increment, date range, and linked specification item. Each task includes its notes and any linked specification items. |
fetch_project_tasks | Returns all tasks in a project across all assignees, sorted by progress then due date. Requires orgId and projectId. Defaults to active tasks (Backlog, To Do, In Progress, Blocked) — Done and Cancelled are excluded by default unless explicitly passed via the progress filter. Each task includes the assignee, notes, and linked specification items. Use this for project-wide task audits and reporting. |
get_item_task_summary | Returns open and total task counts for a model item across all project members — not scoped to the current user. Use this for project-wide readiness reporting where fetch_my_tasks is insufficient. Accepts an optional progress filter to control which states count as “open” (default: To Do, In Progress, Blocked). |
fetch_task_details | Returns the complete detail view of a single task — all properties plus fully resolved relationships: Project Increment, delivery team, releases, tasks this task depends on, tasks blocked by this task, and linked specification items (requirements, systems, risks, etc.). Call this before updating a task to see the current state. |
update_task | Updates a task’s properties and relationships in a single call. Supports: progress, completion percentage, notes, assigned user, estimation, dates, name, and description. Also handles relationship changes — setting a PI, team, or release, adding or removing dependencies, and linking or unlinking specification items. Setting progress to Done automatically sets completion to 100%. Requires Editor role. Your AI agent will show you a clear Before / After summary and ask you to confirm before making any changes. |
update_task_progress | Updates a task’s completion percentage (0–100). Setting to 100 marks the task as Done; setting to 1–99 moves a non-Blocked task to In Progress. Optionally appends a timestamped progress note. Requires Editor role. Your AI agent will show a Before / After summary and ask you to confirm before making any changes. |
update_task_status | Updates a task’s status (Backlog, To Do, In Progress, Done, Blocked, Cancelled). Use this to mark a task as Blocked when it cannot proceed. Setting to Done automatically sets completion to 100%. Requires Editor role. Your AI agent will show a Before / After summary and ask you to confirm before making any changes. |
create_task | Creates a new task with an auto-generated reference (e.g. TODO042). Optionally links the new task to a PI, team, release, dependency tasks, and specification items — all in one step. Requires Editor role. Your AI agent will describe the task it is about to create and ask you to confirm before proceeding. |
set_task_order | Sets your preferred order for a reorderable My Tasks section (In Progress, To Do, or Backlog). Pass the full ordered list of task IDs — the stored order is replaced. Changes are personal and not visible to other project members. |
add_focus_now | Adds a task to your personal Focus Now shortlist on the My Tasks dashboard. The list has a soft limit of five — the tool warns if exceeded but still adds the task. Returns without changes if the task is already pinned. Changes are personal and not visible to other project members. |
Milestone Reporting
| Tool | Description |
|---|---|
update_milestone_scope | Adds, updates, or removes milestone scope entries on a model item in a single batch call. Each operation specifies a milestoneId and one of: add (with description), update (with new description), or remove. The entire batch is validated before any changes are saved — if any operation is invalid, nothing is written. Requires Editor role. Your AI agent will describe the changes it is about to make and ask you to confirm before proceeding. |
get_milestone_readiness | Returns all model items in scope for a milestone, each with their status, baseline status, readiness score, scope description, and open task counts. Designed for project-wide readiness reporting — replaces 150+ sequential tool calls with a single efficient query. Set includeTaskSummary: false for a faster status-only view. Optionally filter by itemTypes to focus on specific item types. |
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
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.
Relationships
| Tool | Description |
|---|---|
get_all_model_item_relationships | Returns all relationships for a model item — both outbound (what this item points to) and inbound (other items that point to this item). Each entry is direction-labelled and includes the connected item’s id, ref, name, type, relationship type, and description. Optionally filter by ofMetamodelType or withRelationshipType. Use this whenever you need to understand or copy an item’s connections. |
get_valid_relationships | Returns relationship context from the metamodel. With one type: returns full inbound (what points TO this type) and outbound (what this type points TO) maps. With two types: returns candidates in both directions showing which item will own the relationship. Relationship entries may include an optional helpGuidance field with context from the metamodel author on when and how to use that relationship type. |
relate_model_items | Creates a relationship between two model items. The metamodel determines ownership and type automatically. Accepts an optional description to record why the items are related. Returns options when multiple relationship types are valid between the pair. |
unrelate_model_items | Removes all relationships between two model items, scanning both directions regardless of which item owns the storage. |
update_relationship_description | Sets or updates the description on an existing relationship between two items. Use to add rationale to relationships that were created without one, or to refine existing descriptions. |
copy_model_item_relationships | Copies all relationships (or a filtered subset) from a source model item to a target model item of the same metamodel type. Handles both outbound (creates them on the target) and inbound (adds the target as an additional related item on each inbound item). Optionally pass ofMetamodelTypes to copy only specific categories. Returns a summary of what was copied and what was skipped. |
Baselines
| Tool | Description |
|---|---|
list_model_item_baselines | Returns all specification baselines for a model item, sorted newest first. Each entry includes the baseline ID, name, description, created-by, date, item count, and — for baselines tagged to a milestone — the milestoneId and milestoneName. |
get_model_item_baseline | Returns the full frozen snapshot for a specific baseline: the complete rendered Markdown spec (captured at baseline time) and a drift analysis comparing current versions against baseline versions for all dependencies. |
create_model_item_baseline | Creates a new specification baseline snapshot for a model item, capturing its specification and all dependency versions at that point in time. Requires Editor role. |
compare_model_item_with_latest_baseline | Compares the current state of a model item against its most recent baseline. Returns a drift report showing what has changed since the snapshot was taken. Returns noBaseline: true if no baselines exist yet. |
Media
| Tool | Description |
|---|---|
get_item_images | Returns embedded diagram data for a model item — draw.io SVGs, raster images, and PlantUML source. Call this when the narrative or spec contains image references (lines starting ![) to retrieve diagram content for visual interpretation. |
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:
get_model_item— get core metadata and the readiness score, which summarises completeness across all relationship categoriesget_all_model_item_properties— get all stored properties: external references, approval state, and all type-specific fieldsget_all_model_item_relationships— get the full picture of connections: both outbound (what this item points to) and inbound (what points to this item)get_model_item_narrative— read the full architectural description, design decisions, and diagrams. If the narrative contains image references (lines starting![), callget_item_imageswith the same item to retrieve diagram data for visual interpretation.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 MongoDB 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.
All access is scoped to a single project. Your agent cannot read data from projects you are not a member of.
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.
| Prompt | Arguments | Description |
|---|---|---|
analyse-architecture-item | orgId, projectId, itemIdentifier | Full 5-step analysis of a specific item: metadata, complete properties, narrative, related items, and data models. Produces a structured report with completeness gaps and recommendations. |
project-health-check | orgId, projectId | Survey the entire project for completeness gaps, low-readiness items, open risks, and unresolved assumptions. Produces a RAG-status health report with prioritised recommendations. |
impact-assessment | orgId, projectId, itemIdentifier, proposedChange | Trace the ripple effects of a proposed change through related items, data contracts, and risks. Suggests using relate_model_items to add any missing connections identified. |
specification-readiness-review | orgId, projectId, itemIdentifier | Review whether an item is ready to hand to a development team. Produces a RAG-status checklist of blockers and recommendations. Suggests using relate_model_items to fix missing relationship blockers. |
data-lineage-trace | orgId, projectId, startingPoint | Trace data from source through streams, APIs, and services to consuming systems. Identifies transformations and lineage gaps. |
generate-client-document | orgId, projectId, itemIdentifier, optional documentStyle (technical | executive | review), optional includeRelated | Generate a structured, client-ready Markdown document for a model item. Produces a Word-paste-ready draft with sections covering purpose, design decisions, APIs & streams, data, non-functional requirements, risks & assumptions, and acceptance criteria. documentStyle controls depth and tone; includeRelated fetches connected items to enrich the document. |
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
plantumlcode 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:
- Go to Project Settings for the project
- Toggle MCP Enabled to on
- Save the settings
Only project members can connect. Non-members receive an error even if MCP is enabled.