14. Annexes
 
Glossary
Error response examples
Hopex rights and profiles matrix
Security and network exposure checklist
AI client configuration examples
OAuth/DCR examples
Header-based examples
SaaS and on-premises deployment checklist
14.1. Glossary
Term
Definition
MCP
Protocol used by an AI client to discover and call capabilities exposed by an MCP-compatible server.
Hopex context
Technical context of an MCP call, including authentication, GraphQL schema, and rights.
Hopex user context
User, repository, and connection profile associated with an MCP call.
Hopex MCP Server
HAS module that exposes Hopex capabilities to an AI client through the server MCP implementation.
AI client
Application or platform that connects to the MCP Server, discovers tools, manages authentication and headers, and presents responses to the user. It may use an LLM to select tools and formulate answers.
HAS
Hopex Application Server. It exposes the MCP endpoint, provides the runtime framework, and applies common security and supervision mechanisms.
GraphQL schema
 
GraphQL schema used by the MCP Server to expose the scope available to AI clients.
 
Customized metamodel
Customer-specific extension of the Hopex metamodel exposed through a GraphQL schema when required by AI usage scenarios.
Metaclass
Type of object in the Hopex metamodel. When exposed to AI clients, custom metaclasses should have clear labels and descriptions.
Meta-association
Relationship definition between metaclasses in the Hopex metamodel. Custom meta-associations should explain the business relationship they represent.
Meta-attribute
Property definition attached to a metaclass in the Hopex metamodel. Custom meta-attributes should be named and described so the LLM can select them correctly in GraphQL queries.
MCP tool
Technical capability exposed by the MCP Server and usable by the AI client.
MCP resource
Reference content exposed by the MCP Server, such as a schema guide or a list of diagram natures.
 
14.2. Error response examples
Case
Code / message
AI client handling
Mutation disabled
OPERATION_NOT_ALLOWED
Mutations are disabled on this server.
Inform the user that the server is in read-only mode.
Read operation sent to Execute_Mutation
INVALID_QUERY
Only 'mutation' operations are accepted.
Use Execute_Query for read operations.
Rephrase and use the read tool when the context allows it.
Write operation sent to Execute_Query
INVALID_QUERY
Only 'query' operations are accepted.
Use Execute_Mutation for write operations.
Rephrase and use the mutation tool when the context allows it.
Irreversible deletion
confirmationRequired with the list of detected operations.
Ask for explicit confirmation before running the mutation again.
14.3. Hopex rights and profiles matrix
The rights matrix depends on the customer environment, Hopex profiles, and exposed GraphQL schema. It identifies the objects, relationships, and operations available through the MCP Server for a given profile.
• Target Hopex repository
• Connection profile used
• Exposed GraphQL schema
• Accessible objects and relationships
• Available read tools
• Authorized or non-authorized mutations
• Restrictions and customized metamodel exposure specific to the customer environment, as described in section 5.2 Customized metamodel exposure.
14.4. Security and network exposure checklist
*MCP endpoint exposed over HTTPS.
*TLS certificate valid and trusted by the AI client.
*Reverse proxy, gateway, or firewall configured when required.
*Authentication mode defined: OAuth/DCR or API key.
*Secrets stored in the secure mechanism of the AI client.
*Default GraphQL schema configured in the HAS console, including customized metamodel exposure when applicable; see section 5.2 Customized metamodel exposure.
*Required headers documented on the AI client side.
*HAS supervision enabled for MCP sessions.
14.5. AI client configuration examples
These examples are indicative. Exact syntax, callback URLs, header declaration, and secret storage vary by AI client and should be checked in the client documentation.
14.5.1. OAuth/DCR examples
The AI client declares the remote MCP Server URL and uses OAuth 2.0 with Dynamic Client Registration when supported. Exact fields depend on the AI client.
Claude example — OAuth/DCR declaration
{
"connector": "Hopex MCP",
"server_url": "https://<hopex-host>/mcp",
"authentication": {
"type": "oauth_dcr"
}
}
This example uses a compact JSON-style declaration for an AI client that supports OAuth/DCR as part of its MCP connector configuration.
Copilot Studio example — MCP wizard
Server name: Hopex MCP
Server description: Hopex MCP Server for architecture repository access
Server URL: https://<hopex-host>/mcp
Authentication type: OAuth 2.0
OAuth mode: Dynamic Client Registration
This example represents a form-based configuration where the AI client collects the MCP Server URL and OAuth/DCR settings through a connector wizard.
The next example uses a custom MCP connector declaration with OAuth Dynamic Client Registration enabled by the AI client.
Mistral Work example — custom MCP connector
{
"name": "Hopex MCP",
"server_url": "https://<hopex-host>/mcp",
"authentication": {
"type": "oauth_dynamic_client_registration"
}
}
14.5.2. Header-based examples
Claude example: the configuration declares the server HTTPS URL, HTTP transport, and headers. Secrets, such as the API key, are referenced through a secure mechanism provided by the AI client.
Claude JSON example — MCP headers
{
"mcpServers": {
"hopex-mcp": {
"type": "http",
"url": "https://<hopex-host>/mcp",
"headers": {
"x-api-key": "${Hopex_MCP_API_KEY}",
"x-schema": "EA_Core",
"x-allow-mutation": "true"
}
}
}
}
The next examples use header-based configuration, typically for API key mode, schema selection, and mutation authorization in API key scenarios.
Copilot Studio example: headers are declared in the OpenAPI definition of the custom connector. x-api-key can be defined as an API key authentication scheme, while x-schema and x-allow-mutation can be declared as header parameters.
Copilot Studio OpenAPI example — MCP headers
components:
securitySchemes:
HopexMcpApiKey:
type: apiKey
in: header
name: x-api-key
parameters:
- name: x-schema
in: header
required: false
schema:
type: string
- name: x-allow-mutation
in: header
required: false
schema:
type: boolean
security:
- HopexMcpApiKey: []
This example shows the same header-based approach for a custom MCP connector when the AI client supports custom HTTP headers.
Mistral Work example: the Hopex MCP Server is added as a custom MCP connector with its HTTPS URL. When the connector supports custom headers, MCP headers can be declared in the connector configuration. Otherwise, the server uses the default values configured in HAS.
Mistral Work JSON example — MCP headers
{
"name": "Hopex MCP",
"server_url": "https://<hopex-host>/mcp",
"headers": {
"x-api-key": "${Hopex_MCP_API_KEY}",
"x-schema": "EA_Core",
"x-allow-mutation": "true"
}
}
14.6. SaaS and on-premises deployment checklist
*MCP endpoint URL confirmed from the AI client environment.
*Authentication mode validated for the target SaaS tenant or on-premises environment.
*Required headers checked in the AI client configuration.
*Customized metamodel exposure validated when a custom GraphQL schema is used.
*Network path validated, including HTTPS, certificates, proxy, gateway, firewall, and DMZ constraints when applicable.
*Baseline read tests completed from the AI client.
*Mutations tested only when enabled and authorized.
*HAS supervision events checked.
*Support procedure and diagnostic information identified.
Use this checklist as the final deployment control.
Detailed principles are described in section 3.5 SaaS and on-premises considerations and deployment implications are described in section 5.5 SaaS and on-premises deployment.