SemaphoreUI MCP Server

Overview Schema Source Related Servers Discussions Admin

run_task

Run a SemaphoreUI task from a template ID, with options for dry-run, diff, host limits, and 30-second startup monitoring.

Instructions

Run a task from a template with optional 30-second monitoring.

Args: template_id: ID of the template to run project_id: Optional project ID (if not provided, will attempt to determine from template) environment: Optional environment variables for the task as dictionary limit: Restrict execution to specific hosts/groups (Ansible --limit) dry_run: Run without making changes (Ansible --check) diff: Show differences when changing files (Ansible --diff) debug: Enable verbose debug output playbook: Override playbook file path git_branch: Override git branch to use message: Task description/message arguments: Additional CLI arguments as a JSON string or string list inventory_id: Override inventory to use follow: Enable 30-second monitoring for startup verification (default: False)

Returns: Task execution result with immediate web URLs and optional monitoring summary

Template Override Requirements: Some parameters require the template to have overrides enabled in task_params. Use create_template() or update_template() with task_params to enable:

- limit: requires task_params={"allow_override_limit": true}
- inventory_id: requires task_params={"allow_override_inventory": true}

Without these settings, the parameter will be ignored silently.

Examples: # Just start the task and get URLs result = await run_task(template_id=5)

# Start task with 30-second monitoring and get URLs
result = await run_task(template_id=5, follow=True)

# Run with limit to specific hosts (template must allow override)
result = await run_task(template_id=5, limit="webservers")

# Dry run with diff to preview changes
result = await run_task(template_id=5, dry_run=True, diff=True)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`diff`	No
`debug`	No
`limit`	No
`follow`	No
`dry_run`	No
`message`	No
`playbook`	No
`arguments`	No
`git_branch`	No
`project_id`	No
`environment`	No
`template_id`	Yes
`inventory_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.5Aug 22, 2026

changedInput schema / properties / arguments / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

First observedv1.0.4Jun 3, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations to provide default safety hints, the description takes on the burden and succeeds: it clearly warns that 'without these settings, the parameter will be ignored silently,' discloses that monitoring is optional and can run for 30 seconds, and explains the return value includes 'immediate web URLs.' This is honest and practically useful, though it could have been even more explicit about side effects (e.g., that this likely triggers a long-running job).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Despite its length, the description is well-structured with clear sections (Args, Returns, Override Requirements, Examples), making it scannable. Every sentence serves a purpose; there is no fluff. The format mirrors common API documentation patterns, so an agent can quickly locate parameter details or jump straight to examples.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (13 parameters, Ansible integration, override prerequisites), the description covers all bases: parameter meanings, required conditions, return value shape, and realistic examples. It even highlights a common pitfall (silent parameter ignoring) that could otherwise trip up an agent. With no annotations or output schema to rely on, this description is comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must fully compensate, and it does: every parameter has a one-line meaning (e.g., 'limit: Restrict execution to specific hosts/groups (Ansible --limit)'). It even explains conditional behavior (e.g., project_id: 'if not provided, will attempt to determine from template'). The override requirements section adds crucial semantic detail about when parameters take effect. This is exactly what makes an agent confident in calling the tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Run a task from a template with optional 30-second monitoring,' making the primary function obvious. While it doesn't explicitly contrast with sibling tools like get_task or stop_task, the meaning is unambiguous for any agent familiar with the domain. The resource (task from a template) and verb (run) are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage context is implied through examples like 'Just start the task' and 'Dry run with diff,' which show when to use the tool, but there is no explicit statement about when not to use it or which sibling to use instead. The 'Template Override Requirements' section provides conditional usage guidance, but it doesn't compare with alternatives. This is adequate but not exemplary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server