MCP Server

This page explains how Semaphore's MCP Server works, how to configure your clients/agents, and what capabilities are available.

Request access to this feature

If you want to try the MCP Server, contact support@semaphore.io so we can enable this feature in your organization at no cost.

Overview

MCP servers (Model Context Protocol servers) connect AI models to external data and tools through a standardized interface. They provide structured, real-time context-like data from APIs so models can retrieve accurate information and perform actions securely and consistently.

You can connect your favorite AI agent with Semaphore using the official MCP Server. This allows the AI agent or IDE to access the activity in your organization using a conversational interface.

With MCP, you can now ask your AI agent why your build failed and to provide a fix.

MCP Server Capabilities

Semaphore's MCP Server provides read-only access to your Semaphore organization via the following tools:

• echo: Returns the provided message verbatim (handy for smoke tests)
• organizations_list: Lists organizations that the user can access
• projects_list: List projects that belong to a specific organization
• projects_search: Search projects inside an organization by project name, repository URL, or description
• workflows_search: Search recent workflows for a project (most recent first)
• pipelines_list: List pipelines associated with a workflow (most recent first)
• pipeline_jobs: List jobs belonging to a specific pipeline
• jobs_describe: Describes a job, surfacing agent details, and lifecycle timestamps
• jobs_logs: Fetches job logs. For cloud jobs, it streams loghub events. For self-hosted jobs, returns a URL where logs can be fetched

See example prompts to see a bit of what's possible.

Configure your AI Agent or IDE

Access to the MCP Server is controlled via an API Token. You can obtain your API token in two ways:

• Personal API Token: if you don't know your personal API token, you can reset it and obtain a new one
• Service Account: create a service account with Member role and use its API token

Both types of tokens are used to communicate with the Semaphore MCP Server endpoint: https://mcp.semaphoreci.com/mcp

If you have problems connecting to the MCP Server, see troubleshooting.

Claude Code

1. Export an environment variable with your API token

   export SEMAPHORE_API_TOKEN=my-token

2. Add the MCP Server to Claude Code

   claude mcp add semaphore https://mcp.semaphoreci.com/mcp \
     --scope user --transport http \
     --header "Authorization: Bearer $SEMAPHORE_API_TOKEN"

3. If you have a session open, restart Claude Code

OpenAI's Codex

1. Open $HOME/.codex/config.toml and add the following lines to the config file

   Semaphore MCP Configuration for Codex

   [mcp_servers.semaphore]
   url = "https://mcp.semaphoreci.com/mcp"
   bearer_token_env_var = "SEMAPHORE_API_TOKEN"
   startup_timeout_sec = 30
   tool_timeout_sec = 300

   Environment variable name

   The bearer_token_env_var value references the name of the environment variable that contains the actual API token value. It is not set to the actual API token value.

2. Export an environment variable with your API token. The name of the environment variable must be equal to the bearer_token_env_var in the previous step. Consider adding this line to your .bashrc (or similar)

   export SEMAPHORE_API_TOKEN=my-token

3. Start Codex normally

VSCode Codex Extension

1. Install the VSCode Codex Extension

2. Set up Codex as shown above in OpenAI's Codex. Alternatively, in VS Code press the Gear icon → MCP settings → Open config.toml and add the lines shown in the Codex Setup

   Semaphore MCP Configuration for Codex

   [mcp_servers.semaphore]
   url = "https://mcp.semaphoreci.com/mcp"
   bearer_token_env_var = "SEMAPHORE_API_TOKEN"
   startup_timeout_sec = 30
   tool_timeout_sec = 300

3. Close VS Code

4. Export an environment variable with your API token. The name of the environment variable must be equal to the bearer_token_env_var in the config.toml. Consider adding this line to your .bashrc (or similar)

   export SEMAPHORE_API_TOKEN=my-token

5. Start VS Code from the command line, in the same shell session where you set the environment variable. This ensures VS Code can have access to the API token

   code path/to/project

   note

   Due to current limitations of the Codex extension for VS Code, if you start VS Code in any other way except from the terminal session where the SEMAPHORE_API_TOKEN variable has the correct value, the Semaphore MCP server will not work.

Example Prompts

The MCP Server provides access to your Semaphore organization (assuming the MCP Server is enabled for your organization).

Here are a few example prompts you can use to interact with your projects, pipelines, and jobs. Use them as starting points to interact with Semaphore. Some prompts might require an API Token with Admin Role.

Task	Prompt
List organizations the Agent has access to	"List organizations you have access to"
Save the organization and project IDs in AGENTS.md (speeds up tasks and saves tokens)	"Find the current project in Semaphore and obtain the organization id and project id. Save the values in AGENTS.md for future reference"
Understand what the pipeline does	"Describe what my pipeline does for this project on Semaphore"
Troubleshoot failed tests	"Help me figure out why have my test failed on Semaphore"
Troubleshoot failed builds	"Why did my build fail?"
Retrieve the logs for a job	"Show me the logs for the build job in the latest workflow in Semaphore"

Troubleshooting

Codex fails to connect

Symptom: When you start Codex, you see the following message:

■ MCP client for `semaphore` failed to start: handshaking with MCP server failed: Send message error Transport
[rmcp::transport::worker::WorkerTransport<rmcp::transport::streamable_http_client::StreamableHttpClientWorker<reqwest::async_impl::client::Client>>] error:
Client error: HTTP status client error (401 Unauthorized) for url (https://mcp.semaphoreci.com/mcp), when send initialize request

Solution: This usually means the environment variable with the Semaphore API Token is not correctly loaded. Check your config.toml to learn what the environment variable name and ensure you are setting it correctly in your shell before starting Codex.

VS Code fails to connect

Symptom: Your Codex extension in VS Code fails to connect with the MCP server.

Solution: This usually means that VS Code does not have access to the environment variable with the Semaphore API Token. Ensure you have set the environment variable as per config.toml in your shell, and that you are actually starting VS Code from that very same shell session. Starting VS Code by any other means causes Codex to fail the connection.

See also

• User management
• Service accounts