Limitations and Troubleshooting
- Last Updated: November 20, 2026
- 5 minute read
- Semaphore
- Version 5.13
- Documentation
This topic describes known limitations of the Semaphore MCP Server and provides guidance for resolving connection, authentication, and tool execution issues.
If you are setting up an MCP client for the first time, see Prerequisites and Server Configuration.
Cannot connect to the MCP Server
If your MCP client cannot connect to Semaphore, check the following:
Server URL: Verify that you are using the MCP Server endpoint configured for your deployment environment.
For on-premises deployments, the endpoint follows this format:
http://<semaphore_studio_url>/ai/mcpReplace
<semaphore_studio_url>with the hostname and port of your Semaphore Studio instance.For Progress Data Cloud deployments, use the MCP Server endpoint configured for your cloud environment.
Network connectivity: Confirm that the MCP Server endpoint is accessible from the machine running your MCP client.
Transport: Verify that the client supports Streamable HTTP and is configured to use HTTP transport.
Authentication: Confirm that the client sends the authentication header required for your deployment:
- On-premises:
X-Api-Keywith a Semaphore access token. - Progress Data Cloud:
Authorizationwith a Bearer JWT token.
- On-premises:
Token expiration: Check whether the token has expired. If necessary, obtain a new token using the authentication procedure for your deployment environment.
Client configuration: Save your configuration and restart or reconnect the MCP client if required.
After reconnecting, verify that the MCP Server is available and its tools can be discovered.
For authentication instructions, see Authentication and Permissions.
The MCP client requests OAuth authentication
The Semaphore MCP Server uses token-based authentication rather than OAuth. The required authentication header depends on the deployment environment.
Some MCP clients may attempt an OAuth authentication flow when a server is added without the required authentication header.
Visual Studio Code
When adding the Semaphore MCP Server by URL alone, VS Code may attempt OAuth registration and display an error such as:
Dynamic Client Registration not supported
To resolve this issue:
- Open the
.vscode/mcp.jsonconfiguration file. - Configure the Semaphore MCP Server with the correct endpoint.
- Add the authentication header required for your deployment environment.
- Save the file.
- Start or reconnect the MCP server.
- Verify that the server status is Running and its tools are available.
For a complete VS Code configuration example, see Authentication and Permissions.
GitHub Copilot CLI
When adding the Semaphore MCP Server using /mcp add, GitHub Copilot CLI may indicate that OAuth authentication is required.
To work around this issue:
Open the GitHub Copilot CLI configuration file:
~/.copilot/mcp-config.jsonAdd the Semaphore MCP Server configuration manually, including the authentication header required for your deployment environment.
Save the configuration file.
Restart GitHub Copilot CLI.
Run
/mcpto verify that the server is connected.
If the configuration already contains other MCP servers, preserve their entries when adding Semaphore.
For the complete configuration, see Connecting GitHub Copilot CLI.
Authentication succeeds, but an operation fails
A successful MCP connection does not guarantee permission to perform every operation.
The MCP Server performs operations according to the permissions associated with the authenticated user.
If an operation fails:
- Confirm that the selected model or task is accessible to the authenticated user.
- Verify that the user has the permissions required for the requested operation.
- Check whether the operation is supported by the available MCP tools.
- Verify that the tool parameters contain the correct model URI, concept URI, or task graph URI.
- Review any error returned by the MCP tool.
For example, a user who can retrieve model information may not have permission to modify or delete model content.
If the error message does not explain the cause, contact your Semaphore administrator for assistance.
The client cannot find a model or concept
If a prompt does not return the expected model or concept:
- Confirm that the correct knowledge model is selected.
- Try searching for the concept using its preferred label.
- Check whether the search is case-sensitive.
- Verify that the authenticated user has access to the requested model.
- When available, use the exact model or concept URI to avoid ambiguity.
Some concept search tools support different matching options, including case-sensitive and case-insensitive searches.
For a reference to the available search tools, see Available MCP Tools.
Concept metadata values are missing from tool results
Some concept retrieval tools return only a subset of the concept's properties.
For example, getConceptAsJsonByUri may return a concept's class, GUID, and preferred label without returning metadata values such as skos:definition.
The getAllMetadataTypes tool retrieves metadata type definitions, including their URIs and schema information. It does not retrieve the values assigned to concepts.
The addMetadataValue, updateMetadataValue, and deleteMetadataValue tools modify metadata values. They do not retrieve a concept's current metadata values.
To inspect the current metadata values:
- Open the model in Knowledge Model Management.
- Select the concept.
- Open the concept's Metadata section.
- Review the values associated with the concept.
The getListOfChangesInModelSince tool can return metadata changes recorded in model history. However, a change log is not a substitute for retrieving the current state of a concept.
MCP tool limitations
OWL operations are not supported
The MCP Server does not provide OWL-specific operations.
Do not assume that functionality available through other Semaphore interfaces is also exposed through MCP tools.
AI Workflows agents are not exposed as MCP tools
The MCP Server does not expose the built-in Model from Spec or Enrichment agents as directly callable MCP tools.
To use these agents, access AI Workflows through the Knowledge Model Management user interface.
Concept deletion is restricted
The deleteConcept tool supports deleting leaf concepts only.
If a concept has child concepts, review its hierarchy before attempting deletion.
Concept scheme deletion is restricted
The deleteConceptSchemeByUri tool supports deleting concept schemes only when they do not contain child concepts.
Model and task deletion can remove data
The manageModelsOrTasks tool supports model and task management operations.
- Deleting a model permanently deletes the model and its associated tasks.
- Deleting a task discards its uncommitted changes.
Review the target model or task before performing deletion operations.
Working with tasks
Some MCP tools accept a task graph URI through the modelUri parameter.
When working with tasks, ensure that operations target the intended task rather than the master model.
Review task changes before committing them to the master model.
Important: If the master model URI is used instead of the task graph URI, supported modification operations may change the master model directly.
For information about available task operations, see Available MCP Tools.
Turtle/RDF import considerations
The importTriples tool imports Turtle/RDF data into a task or master model.
The import is atomic, meaning it is applied as a single transaction.
For large imports, divide the data into smaller batches to reduce the risk of upstream read timeouts.
Use getTurtleModelExample to retrieve an illustrative example of the expected Turtle structure.
Do not import the example unchanged.
Before invoking importTriples:
- Confirm the target model or task.
- Review the RDF content.
- Verify that the import has been explicitly requested.
- Consider using a task if the imported content requires review before being committed.
MCP client compatibility
The Semaphore MCP Server uses Streamable HTTP and requires support for custom HTTP authentication headers.
MCP clients that support the required transport and authentication headers include:
- GitHub Copilot CLI: Configure the MCP Server manually using
~/.copilot/mcp-config.json. - Visual Studio Code with GitHub Copilot Chat: Configure the MCP Server using
.vscode/mcp.jsonand access its tools in Agent mode.
Other MCP-compatible clients may also work if they support the required transport and authentication mechanisms.
Configuration procedures differ between clients. Follow the instructions for your specific client.