6. MCP Tools and Capabilities
The Hopex MCP Server exposes Hopex capabilities as tools. The AI client does not access the repository directly; it calls the tools declared by the server within the GraphQL schema, Hopex rights, and MCP configuration.
The end user does not directly select or invoke MCP tools. The MCP Server exposes each tool with a description and related metadata intended for the AI client or its LLM. Based on this information, the user request, and the conversation context, the AI client or LLM automatically selects the tool that best matches the user's request.
6.1. Tool design principles
Each tool corresponds to a Hopex capability exposed by the MCP Server: schema introspection, query guidance, GraphQL execution, authorized mutations, relationship exploration, object counting, or diagram access.
Read and write operations are separated. Execute_Query runs read-only GraphQL queries. Execute_Mutation runs GraphQL mutations when mutations are authorized.
Mutation authorization is configured in section 5.1.2 Mutation authorization. Tool usage is summarized in section 6.6 Available MCP capabilities.
6.2. Tool naming and structure
Tool names describe the exposed action: read, write, resource access, analysis, or diagram access. They are explicit for both the AI client and technical teams.
Tool structure follows the GraphQL schema, Hopex rights, and connection profile used for the call.
When customized metamodel elements are exposed, their names and descriptions should follow section 5.2 Customized metamodel exposure to support schema discovery and query guidance.
6.3. Tool inputs and outputs
Input parameters define the call scope: object type, Hopex identifier, filter, relationship depth, result limit, or output format.
Responses contain the information returned to the AI client: architecture data, relationships, metadata, execution status, and errors.
6.4. Tool error handling
The MCP Server returns structured errors to the AI client. The AI client uses them, with the LLM when applicable, to prepare the user-facing message.
Errors cover authentication, authorization, invalid parameters, GraphQL schema issues, data access, and Hopex-side execution. Messages do not expose secrets, tokens, API keys, or unnecessary internal details.
Typical MCP Server errors are listed in section 14.2 Error response examples.
6.5. Data exposure control
The visible scope is defined by the selected schema, the Hopex rights and profile, and the MCP configuration.
Large extractions are limited through filtering, pagination, or result limits when needed.
6.6. Available MCP capabilities
Main MCP capabilities are summarized below. Tool names may change between versions; functional capabilities remain the reference.
These capabilities cover schema discovery, query guidance, read execution, authorized mutations, relationship exploration, object counting, and diagram access.
|
Capability
|
Main tools
|
Purpose
|
|---|---|---|
|
Schema discovery
|
Introspect_Main_Types, Introspect_Type, GraphQL_Schema_Types
|
Expose available GraphQL types, fields, relationships, and schema metadata.
|
|
Query guidance
|
Get_Query_Guide, GraphQL_Schema_Query_Guide
|
Help the AI client build valid GraphQL queries with filters, pagination, and sorting.
|
|
Read execution
|
Execute_Query, Count_Objects, Path_Finder
|
Read objects, count objects, and explore relationships within the authorized scope.
|
|
Write execution
|
Get_Mutation_Guide, Execute_Mutation, GraphQL_Schema_Mutation_Guide
|
Execute authorized create, update, or delete operations when mutations are enabled.
|
|
Diagram access
|
Get_Diagram_Natures, Get_Object_Diagrams, Get_Diagram_SVG, Diagrams_Natures
|
Find diagram types, diagrams linked to objects, and diagram content.
|
Write execution is available only when mutations are authorized.