# Semaphore MCP > Semaphore connects your CI/CD platform directly to your AI agent. It lets you manage every part of your delivery lifecycle—from running workflows and viewing live job logs to triggering deployments and cleaning up artifacts—all through natural conversation. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** ci-cd, automation, pipelines, deployment, workflow-management ## Description **Semaphore MCP Server - CI/CD Automation via AI** This server hooks your Semaphore CI/CD account right up to your favorite agent. You ditch switching between web dashboards and terminals; you manage every single part of your delivery lifecycle using natural conversation with your AI client. ### Monitoring Builds and Debugging Failures You've got a broken build, right? No sweat. To check the status of everything, you can run `list_pipelines` to see all project runs, or use `list_workflows` for defined workflows. For deep dives, you get summary details on one specific job with `get_job`, and if that's not enough, you pull every log line using `get_job_logs`. You can also check the overall status of a whole pipeline run via `get_pipeline`, or focus just on a workflow’s context using `get_workflow`. If something fails, don't start over. You can use `rebuild_pipeline` to re-run only the broken sections of an existing job, and you can always stop a runaway process cleanly; that includes stopping a whole pipeline run with `stop_pipeline`, halting a specific workflow execution using `stop_workflow`, or just stopping a single running job instantly via `stop_job`. ### Managing Deployments and Targets You need to release code, period. This server gives you total control over deployment targets. You can list every target associated with the project using `list_deployment_targets`, and if you know its name, you find it with `get_deployment_target_by_name`; otherwise, you pull all the specs using `get_deployment_target` by ID. The lifecycle management is simple: use `create_deployment_target` to set up a new destination, then activate it immediately with `activate_deployment_target`, or take it offline entirely with `deactivate_deployment_target`. If something changes—say, the URL or credentials—you modify it using `update_deployment_target`; if you're done with it, `delete_deployment_target` wipes it out permanently. You can check what happened before by pulling a full history of events with `get_deployment_history`, and to force an immediate release into a specific environment, you trigger a promotion using `trigger_promotion`. If the target is bad news, you delete it; if you just need to know how it looks, you use `get_deployment_target`. ### Artifacts and Code Integrity Storage management is key. You can see all the built files available for a project scope by running `list_artifacts`. When you're done with storage, you set the rules defining artifact cleanup using `configure_artifact_retention`, and you check what those current policies are with `get_artifact_retention`. Before committing anything, don't just trust it. You run `validate_yaml` to make sure your pipeline definition is syntactically correct, preventing messy commits down the line. For quick, isolated operations that don't require a full CI/CD cycle, you execute them right now using `trigger_task`. ### Agent and System Management The infrastructure runs on agents, so keeping track of 'em is critical. You can see every agent type configured across your organization by checking `list_agent_types`, or get the full details for one specific definition with `get_agent_type`. To spin up new resources, you use `create_agent_type` to define a new self-hosted agent type, and if you need to adjust its settings, you modify it using `update_agent_type`; if it's obsolete, `delete_agent_type` removes it. You can list all active agents via `list_agents`, or pull detailed information on one specific instance with `get_agent`. If an agent type needs to be temporarily disabled for maintenance, you use `disable_all_agent_types`. ### Other Tools At Your Fingertips You also get tools for viewing promotion records with `list_promotions`, and if the whole project's YAML changes, you can run a general pipeline restart using `rebuild_pipeline` or trigger an entire fresh execution of a defined workflow with `run_workflow`; this is different from just running a single task. You'll find everything you need to manage your entire delivery process through one chat interface. ## Tools ### activate_deployment_target Marks a specific deployment target as active for immediate use. ### configure_artifact_retention Sets the rules defining how long build artifacts are kept in storage. ### create_agent_type Adds a new type of self-hosted agent to your system configuration. ### create_deployment_target Sets up a brand new destination for deploying code (a target). ### deactivate_deployment_target Takes a deployment target offline, preventing accidental use. ### delete_agent_type Removes an agent type definition from your organization's list. ### delete_deployment_target Permanently removes a deployment target. ### disable_all_agent_types Turns off all agents belonging to a specific type at once. ### get_agent Retrieves detailed information about one specific self-hosted agent instance. ### get_agent_type Gets the full description and details for a defined agent type. ### get_artifact_retention Shows current artifact retention policies for a project scope. ### get_deployment_history Retrieves a chronological list of all deployment events for a specific target. ### get_deployment_target_by_name Finds and describes a deployment target based on its human-readable name. ### get_deployment_target Describes the details of a deployment target using its unique ID. ### get_job_logs Fetches and displays all logged output for a specified job ID. ### get_job Retrieves the summary details of one specific build job run. ### get_pipeline Gets the current status and details of an entire pipeline run. ### get_workflow Retrieves the specific status and context for a defined workflow execution. ### list_agent_types Lists every agent type currently configured in your organization. ### list_agents Displays all self-hosted agents, grouped by their agent type. ### list_artifacts Lists build artifacts available for a particular project scope. ### list_deployment_targets Shows all deployment targets associated with the current project. ### list_pipelines Retrieves a list of pipelines that have run for this project. ### list_promotions Displays a history list of all promotion events within a pipeline. ### list_workflows Lists all defined workflows for the project. ### rebuild_pipeline Re-runs only the failed sections of an existing pipeline run. ### rerun_workflow Resets and runs a previously defined workflow with its original settings. ### run_workflow Initiates a new, fresh execution of a specific workflow. ### stop_job Immediately halts a job that is currently running and consuming resources. ### stop_pipeline Stops an entire pipeline run, preventing further steps from executing. ### stop_workflow Halts a running workflow execution cleanly. ### trigger_promotion Manually forces the deployment of code to a specified environment/target. ### trigger_task Runs an isolated, single-purpose task right now without needing a full pipeline run. ### update_agent_type Modifies the configuration or settings of an existing agent type. ### update_deployment_target Changes details (like credentials or URL) for a deployment target. ### validate_yaml Checks if your pipeline YAML definition is syntactically correct before committing it. ## Prompt Examples **Prompt:** ``` List the last 5 workflows for project 'api-service'. ``` **Response:** ``` I've retrieved the latest workflows for project 'api-service'. The most recent one (ID: wf-123) was triggered on 'master' and finished successfully. Would you like to see the pipeline details for any of these? ``` **Prompt:** ``` Show me the logs for job ID 889900 to see why the build failed. ``` **Response:** ``` Fetching logs for job 889900... The logs indicate a timeout during the 'npm install' step. It seems like a network issue with the registry. Would you like me to rerun the workflow? ``` **Prompt:** ``` Rerun the workflow with ID wf-554433. ``` **Response:** ``` I have triggered a rerun for workflow wf-554433. A new workflow has been created with ID wf-554434. I'll monitor it for you. ``` ## Capabilities ### Monitor Build Jobs Fetch specific job details using `get_job` and retrieve live logs for debugging failures via `get_job_logs`. ### Control Pipelines and Workflows List pipelines (`list_pipelines`), check workflow statuses (`get_workflow`), and manually trigger or stop them using `run_workflow`, `stop_pipeline`, or `stop_workflow`. ### Manage Deployments Create, list, activate, deactivate, update, and delete deployment targets. You can also check the full history using `get_deployment_history` and trigger promotions with `trigger_promotion`. ### Handle Build Artifacts List stored artifacts (`list_artifacts`) for a given scope and set how long they need to be kept via `configure_artifact_retention`. ### Manage System Agents View details about specific agents (`get_agent`), list all agent types (`list_agent_types`), or update/delete the underlying infrastructure with tools like `update_agent_type`. ## Use Cases ### Debugging a failed build log. A developer sees that their latest commit fails. Instead of clicking the job ID and scrolling through hundreds of lines, they ask their agent to run `get_job` for the last failure, then immediately follow up with `get_job_logs`. The agent returns the specific error stack trace in seconds, letting them fix it without leaving their code editor. ### Moving code from Staging to Production. The release manager confirms staging testing is complete. They tell their agent: 'Trigger promotion to production for project X.' The agent executes `trigger_promotion`, and the system updates the status, allowing the manager to track the change using `get_deployment_history`. ### Rerunning a specific workflow. A small bug is found right after deployment. Instead of restarting everything, the team member asks their agent to run `rerun_workflow` for the last successful build ID. The agent initiates the new run and keeps monitoring it until completion. ### Cleaning up old resources. The DevOps team realizes they're accumulating too many failed builds. They use `list_artifacts` to see what exists, then call `configure_artifact_retention` to set a 30-day policy, keeping the system clean and organized. ## Benefits - Debugging build failures used to mean jumping between the editor and a log dashboard. Now, calling `get_job_logs` lets you pull all the output directly into your agent's response, keeping your focus on the code. That saves massive context switching time. - You can stop runaway processes instantly. If a job is stuck or consuming excessive resources, running `stop_job` halts it immediately via chat—no need to find the kill button in three different tabs. - Deployment rollouts are now controlled commands. Instead of guessing which environment needs an update, use `trigger_promotion` to move code from 'Staging' to 'Pre-Prod', and check history with `list_promotions` for proof. - Managing infrastructure is simple. Need to clean up old build files? Use `configure_artifact_retention` to set clear rules, preventing your storage from getting choked by unnecessary artifacts. - You can test code definitions before committing. Run `validate_yaml` against a new pipeline structure; it catches syntax errors instantly, so you don't waste time running invalid configs. ## How It Works The bottom line is you get full control over complex CI/CD tasks using simple natural language commands. 1. Subscribe to this server and provide your Semaphore API Token and Organization Slug. 2. Use a command like `list_pipelines` to see the current project status, or run `get_job` with an ID to check a specific build. 3. Your AI agent interprets your request, calls the necessary tool (e.g., `run_workflow`), and returns the real-time result directly in the chat window. ## Frequently Asked Questions **How do I check if my pipeline YAML is correct before committing it using `validate_yaml`?** Run `validate_yaml` and pass your file content to the tool. It immediately returns a boolean success status or highlights specific syntax errors, ensuring your code compiles properly before you even push. **Can I stop a job that's running right now using `stop_job`?** Yes, if you provide the correct Job ID to the agent, it executes the `stop_job` tool. This immediately halts resource consumption and prevents unexpected issues from continuing. **What is the difference between `run_workflow` and `trigger_task`?** `run_workflow` starts an entire defined sequence of steps (a workflow). `trigger_task` runs a single, isolated operation without needing the full context or structure of a multi-step workflow. **How do I see which agents are available for my project using `list_agents`?** Calling `list_agents` shows you all self-hosted agent instances. The output groups them by type, letting you verify if the required infrastructure is online and ready to run your build. **If a promotion fails, how do I use `get_deployment_history` to check the root cause?** The tool pulls every record of deployments for that target. You see who ran it and when, allowing you to trace the failure. It's perfect for pinpointing exactly where the process broke down. **How do I use `configure_artifact_retention` to manage old build files?** It lets you set rules defining how long artifacts stay stored. You define policies—like deleting anything older than 90 days. This keeps your storage clean and helps manage costs. **What if my production environment changes? How do I use `update_deployment_target`?** You modify the target's connection details or credentials directly. Calling this tool with new parameters ensures your CI/CD tools still talk to the right place, even if the infrastructure shifts. **What does `list_pipelines` show me? Does it list everything in the project?** It provides a summary of every pipeline defined for that specific project scope. You get the name, ID, and last run status immediately. This helps you quickly see what's available without opening individual workflow details. **Can I check the logs of a specific job to debug a failure?** Yes! Use the `get_job_logs` tool with the Job ID. Your agent will retrieve the execution logs, allowing you to identify errors directly in the conversation. **How do I list all active pipelines for a specific project?** Simply ask the agent to run the `list_pipelines` action providing the Project ID. You can also filter by branch name or workflow ID. **Is it possible to trigger a promotion to production via chat?** Yes. If your pipeline has promotions configured, you can use the `trigger_promotion` tool by providing the Promotion ID to move your code to the next stage.