MCP Tools

The ArchiSpark MCP server exposes 38 tools, 2 prompts and 2 resources allowing an LLM (Claude, GPT-4…) to explore and fully modify an ArchiMate model — elements, relationships, views, workspaces, import/export.

Connection

Endpoint: http://localhost:3001/mcp/
Transport: Streamable HTTP (MCP protocol 2025-03-26), stateless — no mcp-session-id, every request gets a fresh server instance (safe for serverless, no sticky sessions needed)
Auth: Bearer token — a personal API token (api_tokens table, same tokens used by the REST API). Generate one from Mon profil → Tokens API → Nouveau token in the web UI.

The token resolves the calling user’s organization membership and all tools operate on that organization’s active workspace. Write tools (create_*, update_*, delete_*, activate_workspace, import_model) require org role owner/admin or platform role platform_admin — org members get a read-only error. See Authentication & Authorization for the full role model.

Configuration in Claude Code:

claude mcp add archimate \
  http://localhost:3001/mcp/ \
  --transport http \
  --header "Authorization: Bearer <token>"

Configuration for Vercel deployment:

claude mcp add archimate-vercel \
  https://archispark-mcp-server.vercel.app/mcp/ \
  --transport http \
  --header "Authorization: Bearer <token>"

All mutations are persisted to PostgreSQL immediately. save_model is a no-op kept for compatibility.

---

Prompts

Prompts inject semantic context into the LLM session. Call them at the start of a modeling session.

archimate-modeling-guide

Injects the complete ArchiMate 3.1 rules: layers, element types, relationship semantics, essential modeling rules and the recommended workflow. Call this first before any modeling session.

// No arguments
// Returns: a user message with the full ArchiMate 3.1 guide

create-viewpoint-view

Step-by-step guide for creating a view for a specific viewpoint, including the right elements to place and the recommended workflow.

Argument	Type	Description
viewpoint	string	Target ArchiMate viewpoint (e.g. "Application Structure", "Layered")

---

Resources

Resources are static documents the LLM can read on demand without polluting every tool response.

archimate://layers

JSON document containing all 8 ArchiMate layers with their element types grouped by category (active, behavioural, passive) and descriptions. Read before create_element to choose the correct type.

archimate://relationships

JSON document with the semantics, direction and a concrete example for each of the 11 ArchiMate relationship types. Read before create_relationship to choose the most precise type.

---

Recommended workflow

1. archimate-modeling-guide  ← load ArchiMate rules
2. get_model_info            ← verify active workspace
3. create_element × N        ← create all elements
4. create_relationship × N   ← link elements
5. create_view               ← create view with a viewpoint
6. create_node × N           ← place elements in the view
7. create_connection × N     ← represent relationships visually
8. render_view               ← visualize the SVG result

---

Model & Metadata

get_model_info

Returns global metadata of the active workspace model. Call first to verify which model is loaded.

// Input: none
// Output: { identifier, name, version, element_count, relationship_count, view_count, property_definition_count }

---

Elements

list_element_types

Returns ArchiMate 3.1 element types present in the model, grouped by layer and category. Each layer entry includes the types actually present in the model alongside the full ArchiMate 3.1 type list.

// Input: none
// Output:
{
  "layers": {
    "Business": {
      "description": "Couche métier: acteurs, processus, services...",
      "active": ["BusinessActor"],          // present in model
      "behavioral": ["BusinessProcess"],
      "passive": ["BusinessObject"],
      "all_active": ["BusinessActor", "BusinessRole", ...],
      "all_behavioral": ["BusinessProcess", "BusinessFunction", ...],
      "all_passive": ["BusinessObject", "Contract", ...]
    },
    "Application": { "..." },
    "...": {}
  },
  "note": "Lists without 'all_' prefix contain only types present in this model."
}

---

list_elements

Lists elements with optional filters.

Parameter	Type	Description
element_type	string?	Filter by ArchiMate 3.1 type (e.g. ApplicationComponent)
name	string?	Filter by name (substring, case-insensitive)

---

get_element

Returns the full detail of an element: type, name, documentation and custom properties. The identifier is the identifier field returned by list_elements or create_element.

Parameter	Type	Description
element_id	string	Element identifier

---

create_element

Creates a new ArchiMate element. The response includes a hints field with the element’s layer and suggested next steps.

Parameter	Type	Description
name	string	Element name
type	string	ArchiMate 3.1 type (see full list)
documentation	string?	Description
properties	array?	[{ property_definition_ref, value }]

// Response includes hints:
{
  "identifier": "e-abc",
  "type": "ApplicationComponent",
  "hints": {
    "layer": "Application",
    "next_steps": [
      "Link to the BusinessProcess it serves via Serving",
      "Link to TechnologyService supporting it via Realization",
      "Create a view with viewpoint 'Application Structure' or 'Application Usage'"
    ]
  }
}

If the type is invalid, the error message lists all valid types grouped by ArchiMate layer.

---

update_element

Updates an existing element (only provided fields are modified). Changing the type may invalidate existing relationships — verify with get_element_relationships after modification.

Parameter	Type	Description
element_id	string	Identifier
name	string?	New name
type	string?	New ArchiMate 3.1 type
documentation	string?	New documentation (null to clear)
properties	array?	Replaces all properties

---

delete_element

Deletes an element and all its relationships (incoming and outgoing). The element is also removed from all views. Irreversible.

Parameter	Type	Description
element_id	string	Identifier

---

get_element_relationships

Returns all relationships (incoming and outgoing) for an element. Useful to check semantic consistency before modifying or deleting an element.

Parameter	Type	Description
element_id	string	Element identifier

---

list_elements_in_views

Returns identifiers of elements placed in at least one view. Useful to distinguish modeled elements (with visual representation) from orphans (in the model but without a view).

// Input: none
// Output: ["id-abc", "id-def", …]

---

Relationships

list_relationship_types

Lists the ArchiMate relationship types present in the model, enriched with semantics and direction for each type.

// Output:
[
  {
    "type": "Assignment",
    "description": "Lies an active element to the behavioural element it performs.",
    "direction": "active → behavioural (same layer or Physical layer)"
  },
  {
    "type": "Realization",
    "description": "A more concrete element implements a more abstract one.",
    "direction": "lower layer → upper layer"
  }
]

---

list_relationships

Lists relationships with optional filters.

Parameter	Type	Description
rel_type	string?	ArchiMate relationship type (e.g. Assignment, Realization)
source_id_filter	string?	Filter by source element identifier
target_id	string?	Filter by target element identifier

---

get_relationship

Returns the full detail of a relationship by its identifier: type, source, target, name and properties.

Parameter	Type	Description
relationship_id	string	Relationship identifier

---

create_relationship

Creates a relationship between two existing elements. The response includes a hints field with the semantics of the chosen type and suggested next steps.

Parameter	Type	Description
type	string	Relationship type: Assignment, Realization, Serving, Access, Composition, Aggregation, Influence, Triggering, Flow, Specialization, Association
source	string	Source element identifier
target	string	Target element identifier
name	string?	Optional label
access_type	string?	For Access: Access, Read, Write, ReadWrite
is_directed	boolean?	For Association
influence_strength	string?	For Influence: +, ++, -, -- or any string

// Response includes hints:
{
  "identifier": "r-abc",
  "type": "Serving",
  "hints": {
    "semantics": "An element provides its capability for use by another.",
    "direction": "provider → consumer",
    "next_steps": [
      "Visualize in a view via create_connection (with the returned relationship_id)",
      "Check consistency with get_element_relationships on the source element"
    ]
  }
}

Choosing the most precise type matters: Assignment / Realization / Serving carry richer semantics than Association. Consult the resource archimate://relationships for guidance.

---

update_relationship

Updates an existing relationship (only provided fields are modified).

Parameter	Type	Description
relationship_id	string	Identifier
name	string?	New name
type	string?	New ArchiMate 3.1 type
source	string?	New source element identifier
target	string?	New target element identifier
access_type	string?	New access type
is_directed	boolean?	New directed flag
influence_strength	string?	New influence strength

---

delete_relationship

Deletes a relationship. Visual connections associated with it in views are also removed.

Parameter	Type	Description
relationship_id	string	Identifier

---

Views

list_views

Lists all views with their viewpoint, node count and connection count.

---

get_view

Returns the detail of a view: viewpoint, placed nodes and represented connections. Use render_view to get the visual SVG.

Parameter	Type	Description
view_id	string	View identifier

---

create_view

Creates a new view (diagram). A viewpoint defines the audience and expected element types. The response includes next_steps hints.

Parameter	Type	Description
name	string	View name
viewpoint	string?	ArchiMate viewpoint (use list_viewpoints to get valid values)
documentation	string?	Description

// Response includes next_steps:
{
  "identifier": "v-xyz",
  "name": "Payment Architecture",
  "next_steps": [
    "Call list_elements to find elements to display",
    "Call create_node for each element to place in this view",
    "Call create_connection to represent relationships visually",
    "Call render_view to visualize the result"
  ]
}

Use the prompt create-viewpoint-view for a full step-by-step guide.

---

update_view

Updates the name, viewpoint or documentation of a view (only provided fields are modified).

Parameter	Type	Description
view_id	string	View identifier
name	string?	New name
viewpoint	string?	New viewpoint (null to clear)
documentation	string?	New documentation (null to clear)

---

delete_view

Deletes a view. The underlying elements and relationships are not deleted — only the visual representation is removed.

Parameter	Type	Description
view_id	string	View identifier

---

render_view

Generates an SVG image of a view. Returns base64-encoded SVG as an image content block. Call after placing elements and connections.

Parameter	Type	Description
view_id	string	View identifier

---

list_viewpoints

Returns the sorted list of all 28 ArchiMate 3.1 viewpoints. Key viewpoints: Layered (cross-cutting), Application Structure, Business Process Cooperation, Technology, Implementation and Deployment, Motivation, Strategy, Capability Map.

// Input: none
// Output: ["Application Cooperation", "Application Platform", …]

See the full viewpoints table for audience and typical elements.

---

Nodes (view layout)

create_node

Places an element in a view as a visual node. The same element can appear in multiple views independently. Coordinates and dimensions are in pixels; if omitted, the element is placed automatically.

Parameter	Type	Description
view_id	string	View identifier
element_id	string	Element to represent
x, y	number?	Position in pixels
w, h	number?	Dimensions in pixels (default ~120×55)

---

update_node

Updates the position, size or display name of a node. The display name overrides the element name in this view only.

Parameter	Type	Description
view_id	string	View identifier
node_id	string	Node identifier
x, y	number?	New position
w, h	number?	New dimensions
name	string?	Override display name (null to reset to element name)

---

delete_node

Removes a node from a view. The underlying element is not deleted — it remains visible in other views.

Parameter	Type	Description
view_id	string	View identifier
node_id	string	Node identifier

---

Connections (view layout)

create_connection

Creates a visual connection between two nodes in a view. Link it to an ArchiMate relationship via relationship_id to carry semantic meaning. Without relationship_id, the connection is purely visual.

Parameter	Type	Description
view_id	string	View identifier
source	string	Source node identifier
target	string	Target node identifier
relationship_id	string?	Underlying ArchiMate relationship (recommended)
name	string?	Label
source_side	string?	Edge attachment: top, right, bottom, left
target_side	string?	Edge attachment: top, right, bottom, left

---

update_connection

Updates a connection in a view (only provided fields are modified).

Parameter	Type	Description
view_id	string	View identifier
connection_id	string	Connection identifier
name	string?	New label (null to clear)
source	string?	New source node
target	string?	New target node
source_side	string?	New edge side
target_side	string?	New edge side

---

delete_connection

Removes a connection from a view. The underlying ArchiMate relationship is not deleted.

Parameter	Type	Description
view_id	string	View identifier
connection_id	string	Connection identifier

---

Property Definitions

list_property_definitions

Lists all custom property definitions in the model. Properties add custom metadata to elements and relationships.

---

get_property_definition

Returns the detail of a property definition.

Parameter	Type	Description
id	string	Definition identifier

---

create_property_definition

Creates a custom property definition.

Parameter	Type	Description
name	string	Name
type	string?	string (default), boolean, date, number, enumeration

---

update_property_definition

Updates a property definition (only provided fields are modified).

Parameter	Type	Description
id	string	Identifier
name	string?	New name
type	string?	New type

---

delete_property_definition

Deletes a definition and removes the property from all elements and relationships.

Parameter	Type	Description
id	string	Identifier

---

Workspaces

list_workspaces

Lists all workspaces and indicates which one is active. Each workspace is an independent ArchiMate model.

// Input: none
// Output: [{ id, name, active }, …]

---

activate_workspace

Activates a workspace. All subsequent operations (elements, relationships, views) target this workspace.

Parameter	Type	Description
workspace_id	string	Workspace identifier (from list_workspaces)

---

Import / Export

export_model

Exports the active model as Open Exchange XML (ArchiMate 3.1, The Open Group standard). The XML can be imported into other ArchiMate tools (Archi, etc.).

// Input: none
// Output: XML string (text content block)

---

import_model

Imports a model from Open Exchange XML. Replaces the content of the active workspace.

Parameter	Type	Description
xml	string	XML content (Open Exchange Format, archimate3_Model.xsd)

Returns the model metadata after import.

---

Persistence

save_model

No-op — all changes are persisted to PostgreSQL immediately. Kept for compatibility with clients that call it explicitly.

---

Example Claude session

Human: Create an Application Architecture view for the Payment domain.

→ archimate-modeling-guide()
← [ArchiMate 3.1 rules loaded]

→ get_model_info()
← { identifier: "m-1", name: "Payment Platform", element_count: 0, … }

→ create_element(name="Payment Service", type="ApplicationComponent")
← { identifier: "e-abc", hints: { layer: "Application", next_steps: ["Link to BusinessProcess via Serving", …] } }

→ create_element(name="Payment DB", type="DataObject")
← { identifier: "e-def", … }

→ create_relationship(type="Access", source="e-abc", target="e-def", access_type="ReadWrite")
← { identifier: "r-ghi", hints: { semantics: "A behavioural element reads or writes a passive element.", … } }

→ create_view(name="Payment Architecture", viewpoint="Application Structure")
← { identifier: "v-xyz", next_steps: ["Call create_node for each element", …] }

→ create_node(view_id="v-xyz", element_id="e-abc", x=100, y=100, w=120, h=55)
→ create_node(view_id="v-xyz", element_id="e-def", x=280, y=100, w=120, h=55)

→ create_connection(view_id="v-xyz", source="n-1", target="n-2", relationship_id="r-ghi")

→ render_view(view_id="v-xyz")
← [SVG image]