Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OGE HSE MCP Find HSE procedures about working at height"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This repository provisions an Entra-protected, read-only remote MCP server containing fictitious HSE procedures and incidents. It is a demonstration only; none of the records are operational safety guidance.
Copy .env.example to .env and set the variables.
Install with py -m pip install -e ".[dev]".
Run oge-hse-seed.
Run tests with py -m pytest -q.
Related MCP server: SSO MCP Server
The script reads deployment-specific values only from .env:
.\scripts\provision.ps1It creates the resource API registration when needed, provisions Azure Container Apps and Azure Container Registry, builds the image in ACR, and prints the MCP URL and resource API scope. It does not grant tenant-wide consent or create Microsoft 365 integrations; those are explicit administrator review steps described in docs/microsoft-365-integration.md.
Remove all demonstration Azure resources and the Entra app registration with .\scripts\remove.ps1.
search_hse_knowledge: Search procedures and incident lessons with grounding metadata.
search_procedures: Search global and site-authorized HSE procedures.
get_procedure: Retrieve one authorized procedure.
search_incidents: Search fictitious incidents for authorized sites.
Authorization is fail-closed. The HTTP bearer token is validated for signature, issuer, audience, expiry, and required delegated scope. Site access comes from the configured claim named by HSE_ENTRA_SITE_CLAIM; a tool argument can't expand that scope.
Copilot Studio custom connector with OBO OAuth: bind the MCP server to a specific HSE agent while preserving delegated user identity.
Microsoft 365 federated connector: expose live, read-only HSE retrieval through a tenant-local connector in supported Microsoft 365 Copilot experiences.
Architecture and rollout comparison: compare the agent-specific and tenant-local federated paths.
Get one HSE procedure when it is global or in the caller's authorized site scope.
| Name | Required | Description | Default |
|---|---|---|---|
| site_ids | No | ||
| procedure_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose the scope restriction, which is a behavioral constraint. However, it doesn't explain what happens if the procedure is not found, whether it's read-only (implied by 'get'), or any error handling. For a simple get operation, this is somewhat sufficient but still leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundancy. It front-loads the action and resource, and adds the scope condition in a compact clause. Every word earns its place, making it optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no annotations, the description is insufficient. It doesn't explain the site_ids parameter, doesn't provide usage guidance relative to siblings, and doesn't mention output or error conditions. The output schema may cover return values, but the description still leaves critical gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions scope authorization but doesn't explain the site_ids parameter at all. The procedure_id is self-explanatory from its name, but site_ids remains ambiguous. The description adds minimal value over the schema and fails to clarify the optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and the resource (one HSE procedure), and adds a scoping condition (global or authorized site scope). It distinguishes from siblings implicitly by specifying a single procedure fetch, but doesn't explicitly name alternatives. This is clear and specific enough to understand the tool's core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over the sibling search tools. It only states a precondition (global or authorized site scope) which clarifies when the tool can be used, not when it should be used. There is no mention of alternatives or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search current HSE procedures and incident lessons for grounded answers.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| site_ids | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It usefully discloses that the tool searches current knowledge and returns grounded answers, which signals a synthesis/retrieval behavior. It does not mention limitations, citation behavior, or permissions, so it is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that states verb, resource, and purpose with no filler. Every word contributes to the agent's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core call is simple (one required query), and an output schema exists to document return values. The main gaps are undocumented parameter semantics for limit and site_ids and the lack of explicit routing guidance relative to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only reinforces the query field through 'Search'. Limit and site_ids are not explained, leaving the agent to guess what values are acceptable and how they affect results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Search'), a clear resource ('current HSE procedures and incident lessons'), and the intended result ('grounded answers'). This differentiates it from the sibling tools search_procedures and search_incidents, which target narrower sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for grounded answers' implies the tool is meant for question-answering over HSE knowledge, giving some usage context. However, it does not explicitly say when to prefer this over search_procedures or search_incidents, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search fictitious HSE incidents in the caller's authorized site scope.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| severity | No | ||
| site_ids | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits on its own. It indicates a read-only search operation via 'Search' and notes the 'fictitious' nature of the data, but it doesn't elaborate on side effects, pagination, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that gets to the point immediately. No wasted words, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is too sparse for a tool with four parameters. It doesn't explain what 'query' refers to, what severity values are accepted, or how site_ids should be provided. It also doesn't differentiate from sibling search tools beyond the resource type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the description provides no explanation of any of the four parameters (limit, query, severity, site_ids). The agent must infer parameter semantics entirely from the schema, which only gives types and defaults, leaving meaning ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'fictitious HSE incidents', making it distinct from sibling tools that search knowledge and procedures. The mention of 'authorized site scope' adds a specific context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context that the search is limited to the caller's authorized sites, which informs when this tool is appropriate. However, it does not explicitly mention alternatives or when not to use it, so it's clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search current HSE procedures in the caller's authorized site scope.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| category | No | ||
| site_ids | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It mentions 'current' (implying active/valid status) and 'authorized site scope' (implying access control), but it does not state that the operation is read-only, describe pagination, sorting, or what happens when no results are found. This is minimal for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the action and scope. It contains no filler or redundancy. However, it is so brief that it sacrifices necessary detail, but that is a completeness issue, not a conciseness one.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (which helps with return format), the description lacks essential context: it doesn't explain the optional parameters, filtering semantics, or usage scenarios. For a search tool with 4 optional params and no annotations, this is insufficient for an agent to call it correctly and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about any of the four parameters (limit, query, category, site_ids). Since the schema only gives types and defaults, the description must compensate but fails to do so, leaving the agent without guidance on how to construct effective queries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search', the resource 'HSE procedures', and the scope constraint 'in the caller's authorized site scope'. It distinguishes itself from siblings like search_hse_knowledge (knowledge base) and search_incidents (incidents) by resource type, and from get_procedure (likely single retrieval) by the search action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus its alternatives. While the search vs. get distinction is implied by the name, the description does not mention get_procedure for specific retrievals or search_hse_knowledge for knowledge queries. The 'authorized site scope' hints at a constraint but doesn't route the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_proceduresearch_hse_knowledgesearch_incidentssearch_proceduresScored across 4 tools
search_procedures and search_incidents are clearly scoped, but search_hse_knowledge overlaps with both by searching procedures and incident lessons. An agent may be uncertain whether to use the broad knowledge search or the specific procedure/incident search for a given query.
Tool names consistently follow a verb_noun pattern using snake_case: search_hse_knowledge, search_procedures, search_incidents, and get_procedure. The one get_* tool is a natural singular retrieval counterpart to the search_* tools.
Four tools is a well-scoped set for an HSE knowledge and incident search server. Each tool serves a distinct retrieval need without unnecessary bulk.
The read-only search and retrieval workflow is well covered: procedures can be searched and retrieved, incidents can be searched, and a combined knowledge search exists. A dedicated get_incident or incident-lesson detail tool is missing, but agents can likely work around it via search_hse_knowledge.
Read-only finance and operations controls for AI agents with evidence and safe next actions.
Read-only senior-care exit routes, duplicate-referral deadlines, and templates; no PII or sending.
Read-only MCP access to devplane.dev's public pages, FAQ corpus and comparisons.
Read-only access to Epivo's live course catalogue for AI agents.
