AI-Driven Development: Introducing Semaphore’s MCP Server

We’re excited to introduce the Semaphore MCP Server, a new way for AI agents and IDE copilots to access rich, structured data about your builds. By exposing pipelines, jobs, and logs through the Model Context Protocol, the server gives assistants the context they need to explain failures, summarize project setups, and recommend fixes without digging through the UI.

Important: Semaphore’s MCP Server is free for all users but disabled by default. To enable it for your organization, email support@semaphore.io and we’ll switch it on.

Why Model Context Protocol matters for CI/CD

MCP standardizes how AI models communicate with external systems. An MCP server acts as a bridge between the assistant and your infrastructure, exposing data and scoped actions through declared tools and resources.

With MCP, agents can fetch the exact information they need, like workflow histories or failing job logs.

Some examples of what you can now do with the MCP Server:

• Summarize build or test failures
• Explain why a pipeline failed and highlight the step that needs attention
• Describe what a given pipeline does so new contributors can ramp up quickly
• Propose or even implement fixes in the codebase with full CI context

Semaphore’s MCP Server

Semaphore’s implementation focuses on observability first. This initial release ships as a read-only interface so teams can trial the experience safely while we collect feedback. Under the hood, the server aggregates the same metadata surfaced in the UI and exposes it through a curated toolset:

• organizations_list, projects_list, and projects_search for high-level discovery
• workflows_search, pipelines_list, and pipeline_jobs to inspect activity chronologically
• jobs_describe and jobs_logs to dive into agent details and log output
• echo to smoke-test connectivity from your client

Keeping the scope observational lets you grant access broadly without worrying about write operations. As adoption grows, we’ll layer in more capabilities based on your feedback.

Availability and access

Authentication happens via the same API tokens you already use:

• Use a Personal API Token for individual access
• Or create a Service Account and use the associated API token

Then, you only have to point your MCP client to the official Semaphore endpoint: https://mcp.semaphoreci.com/mcp.

Configure your AI agent

The server is compatible with any MCP-aware client. Below are quick-starts for the three we test most often. If you run into issues, see the full MCP guide or reach out to support.

Claude Code

Claude Code is configured via the command line:

1. Export your API token:

export SEMAPHORE_API_TOKEN=my-token

2. Register the Semaphore MCP endpoint:

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

3. Restart Claude Code, so the new server loads.

OpenAI’s Codex

For Codex, the procedure is similar:

1. Open $HOME/.codex/config.toml and add:

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

Note that bearer_token_env_var points to the name of the shell variable that stores your token, not the token itself.

2. Export the token in your shell (and optionally in your rc file):

export SEMAPHORE_API_TOKEN=my-token

3. Launch Codex normally. It will initialize the MCP server during startup.

VS Code (Codex Extension)

1. Install the Codex VS Code extension.

2. Press the Gear icon → MCP settings → Open config.toml). Add the MCP configuration:

[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. Export SEMAPHORE_API_TOKEN in the shell session you’ll use to start VS Code:

export SEMAPHORE_API_TOKEN=my-token
code path/to/project

Important: Due to extension limitations, VS Code must be launched from the same shell that has the environment variable with the token. Starting VS Code in any other way causes connection errors.

Example prompts

Use these as conversation starters once the server is connected. Some actions assume your agent already has local repo access.

What’s next

Remember, Semaphore’s MCP Server is free for all customers but disabled by default. To enable it for your organization, email support@semaphore.io and we’ll switch it on for you.

We’re iterating quickly on this integration. Please send feedback, feature requests, or issues to the Semaphore repository or chat with us on the Discord server. We’re listening and eager to help your agents work smarter on Semaphore.

Thank you for reading, and happy building!