Authentication and Permissions
- Last Updated: November 20, 2026
- 4 minute read
- Semaphore
- Version 5.13
- Documentation
The Semaphore MCP Server uses token-based authentication. The authentication method depends on the deployment environment:
- On-premises: A Semaphore access token is passed in the
X-Api-KeyHTTP header. - Progress Data Cloud: A JWT token is passed in the
AuthorizationHTTP header using the Bearer scheme.
MCP operations are subject to the permissions of the authenticated user.
Generate an on-premises access token
Before connecting an MCP client to an on-premises deployment, generate an access token for the Semaphore user whose permissions you want to use.
- Sign in to Semaphore Studio.
- Navigate to Services > Generate Access Token.
- In Expires after, specify the number of hours the token should remain valid.
- Click Generate.
- Copy the generated token and store it securely.
The token expires after the specified number of hours. After it expires, generate a new token and update your MCP client configuration.
Important: Treat access tokens as credentials. Do not share them or include them in source code, documentation, or configuration files committed to version control.
Generate a Progress Data Cloud token
For Progress Data Cloud deployments, generate a JWT token using the cloud authentication process.
For instructions, see REST API Integration.
Use the generated JWT token to authenticate MCP requests through the Authorization HTTP header:
Authorization: Bearer <cloud_token>
Configure token authentication
Configure your MCP client to connect to the Semaphore MCP Server using HTTP transport and the authentication header required for your deployment environment.
For on-premises deployments, the MCP Server endpoint follows this format:
http://<semaphore_studio_url>/ai/mcp
Replace <semaphore_studio_url> with the hostname and port of your Semaphore Studio instance. Use HTTPS if configured for your environment.
For Progress Data Cloud deployments, use the MCP Server endpoint configured for your cloud environment.
The required authentication headers are:
On-premises:
X-Api-Key: <API_KEY>
Progress Data Cloud:
Authorization: Bearer <cloud_token>
Your MCP client must support custom HTTP headers.
Configure authentication in GitHub Copilot CLI
For on-premises deployments, include the following authentication configuration in the GitHub Copilot CLI MCP server definition:
"headers": {
"X-Api-Key": "<API_KEY>"
}
For Progress Data Cloud deployments, use the following authentication header instead:
"headers": {
"Authorization": "Bearer <cloud_token>"
}
For the complete configuration and connection procedure, see Connecting GitHub Copilot CLI.
Configure authentication in Visual Studio Code
Visual Studio Code supports HTTP MCP servers with custom headers.
To configure the Semaphore MCP Server for an on-premises deployment in a VS Code workspace:
Open the workspace in VS Code.
Create or open
.vscode/mcp.json.Add the following configuration:
{ "servers": { "semaphore-mcp": { "type": "http", "url": "http://<semaphore_studio_url>/ai/mcp", "headers": { "X-Api-Key": "${input:semaphore-api-key}" } } }, "inputs": [ { "id": "semaphore-api-key", "type": "promptString", "description": "Semaphore access token", "password": true } ] }Replace
<semaphore_studio_url>with the address of your Semaphore Studio instance.Save the configuration.
Start the
semaphore-mcpserver using the MCP controls in VS Code.When prompted, enter your Semaphore access token.
Verify that the server status is Running and that MCP tools are discovered.
The ${input:semaphore-api-key} reference prompts for the token instead of storing it directly in the configuration file.
Important: Keep local MCP configuration files containing environment-specific information out of version control. Never commit access tokens.
Progress Data Cloud authentication in VS Code
For Progress Data Cloud deployments, use the Authorization header with a JWT token.
In .vscode/mcp.json, replace the headers object with:
"headers": {
"Authorization": "Bearer ${input:semaphore-cloud-token}"
}
Replace the existing token input in the inputs array with:
{
"id": "semaphore-cloud-token",
"type": "promptString",
"description": "Progress Data Cloud JWT token",
"password": true
}
Use the MCP Server URL configured for your Progress Data Cloud environment.
When prompted, enter the JWT token generated through the Progress Data Cloud authentication process.
Understand permissions
MCP operations are performed according to the permissions associated with the authenticated user.
The MCP Server does not grant additional permissions beyond those assigned to that user.
For example:
- A user with permission to view a model can retrieve model information through the available MCP tools.
- Creating, updating, or deleting KMM content requires the corresponding permissions.
- Operations involving models and tasks are subject to the permissions assigned to the authenticated user.
Use credentials associated with a user who has the permissions required for the intended operations. Avoid using an account with broader permissions than necessary.
Renew an expired token
On-premises deployments
If a Semaphore access token expires:
- In Semaphore Studio, navigate to Services > Generate Access Token.
- Specify a new token lifetime in Expires after.
- Click Generate and copy the new token.
- Update the token used by your MCP client.
- Restart or reconnect the MCP client if required.
- Verify that the MCP Server connection is available.
Progress Data Cloud deployments
If your JWT token expires, obtain a new token using the Progress Data Cloud authentication process.
For instructions, see REST API Integration.
Update your MCP client configuration with the new token and reconnect if required.
For GitHub Copilot CLI, use /mcp to inspect the connection.
For VS Code, check the MCP server status and confirm that its tools are available.
OAuth authentication
OAuth is not required by the Semaphore MCP Server.
Some MCP clients may attempt OAuth authentication when a server is added without an authentication header.
For example, adding the Semaphore MCP Server by URL alone in VS Code can trigger an OAuth registration flow and produce a Dynamic Client Registration not supported error.
To connect, configure the authentication header required for your deployment environment instead of relying on automatic OAuth registration.
In the tested version of GitHub Copilot CLI, attempting to add the Semaphore MCP Server interactively using /mcp add also reports that OAuth is required.
To work around this issue, manually configure the server in ~/.copilot/mcp-config.json with the appropriate authentication header, and restart GitHub Copilot CLI.
For detailed instructions, see Connecting GitHub Copilot CLI.