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 read-only tools:
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. |
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. |
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 the complete model item document: all base fields plus type-specific fields (risk scores, assumption status, design decisions, FMEA analysis, API protocols, etc.), relationships, external references, approval state, data mappings, and PlantUML diagrams. 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_related_model_items | Returns items connected to a given item, including their description, status, readiness score, and estimation. |
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 the current user’s active tasks (To Do + In Progress) assigned to them across all projects, sorted by progress then due date. No parameters required — identity is resolved from the OAuth token. |
Relationships
| Tool | Description |
|---|---|
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. |
Recommended workflow
At session start: call fetch_my_tasks to understand the user’s current workload before diving into analysis.
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 the complete document: external references, relationships, approval state, and all type-specific fieldsget_model_item_narrative— read the full architectural description, design decisions, and diagramsget_related_model_items— explore connected assumptions, risks, requirements, data sets, and operational itemsget_data_set_schema— for any related Data Set items, fetch the full entity model and field definitions
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. |
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 CDN (
https://blobs.archrepo.com/…). AI agents that support image rendering (such as Claude) can view 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 and data entities, shown as inline notes with their IDs.
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.