octopilot-mcp
OfficialGenerate CI workflows and browse the Octopilot GitHub Actions registry, enabling automated CI/CD pipeline creation.
Suggest and generate .pre-commit-config.yaml as part of repository onboarding to enforce code quality checks.
Generate skaffold.yaml configuration files for artifacts, facilitating container image building and deployment.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@octopilot-mcpOnboard the Rust API project in ./rust-api for Octopilot CI"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
octopilot-mcp
Model Context Protocol (MCP) server for Octopilot — enables AI agents to detect, generate, build, and wire up new repositories end-to-end using the Octopilot CI/CD toolchain.
What it does
Tool | Description |
| Parse |
| Generate a |
| Full |
| One-call onboarding: detect → generate files → return next steps |
| Run |
| All Octopilot GitHub Actions from the bundled registry |
| Full spec, inputs, examples, gotchas for one action |
op promote-imageis intentionally not exposed. Image promotion between environments is operationally sensitive and must only run through a GitHub Actions workflow (with audit trail, OIDC credentials, and environment protection rules). Usegenerate_ci_workflowto produce the workflow that handles promotion safely.
Related MCP server: @lex-tools/codebase-context-dumper
Option A — Hosted (zero install)
Connect directly to the public server at https://mcp.octopilot.app — no cloning, no Python, no pip required.
# Cursor
fastmcp install cursor https://mcp.octopilot.app --name octopilot
# Claude Desktop
fastmcp install claude https://mcp.octopilot.app --name octopilotAvailable hosted tools (stateless, no local dependencies):
Tool | Description |
| Browse the Octopilot GitHub Actions registry |
| Full spec, inputs, examples, gotchas for one action |
| Generate a |
| Full |
Need
detect_project_contexts,onboard_repository, orrun_op_build? Those tools need Docker and local filesystem access — use Option B below.
Option B — Local install (full suite)
# Clone and install
git clone https://github.com/octopilot/octopilot-mcp
cd octopilot-mcp
uv syncUsage
Register with your IDE (one command, FastMCP 3 CLI)
Docker or Colima is the only external dependency. Most tools are pure Python;
run_op_build pulls ghcr.io/octopilot/op:latest automatically with
--pull always, so you always run the latest release.
# Cursor
uv run fastmcp install cursor src/octopilot_mcp/server.py --name octopilot
# Claude Desktop
uv run fastmcp install claude src/octopilot_mcp/server.py --name octopilotDevelopment (hot-reload)
uv run fastmcp dev src/octopilot_mcp/server.py --reloadInspect tools from the terminal
# List all available tools
uv run fastmcp list src/octopilot_mcp/server.py
# Call a tool directly
uv run fastmcp call src/octopilot_mcp/server.py tool_list_actionsRun as a server directly
uv run octopilot-mcpManual JSON config (alternative to fastmcp install)
{
"mcpServers": {
"octopilot": {
"command": "uv",
"args": ["run", "--directory", "/path/to/octopilot-mcp", "octopilot-mcp"]
}
}
}Pin to a specific op release (optional):
{
"mcpServers": {
"octopilot": {
"command": "uv",
"args": ["run", "--directory", "/path/to/octopilot-mcp", "octopilot-mcp"],
"env": { "OP_IMAGE": "ghcr.io/octopilot/op:v1.0.0" }
}
}
}Environment variables
Variable | Default | Description |
|
| Pin to a specific op release for reproducibility |
Example agent interaction
User: Onboard this Rust API project to use Octopilot CI.
Agent: [calls onboard_repository("/path/to/my-api", "ghcr.io/my-org")]
→ Detected: rust (stable) in api/
→ Generated: skaffold.yaml, .github/workflows/ci.yml
→ Next steps: add .pre-commit-config.yaml, push changesDevelopment
uv sync --all-extras
# Run tests
uv run pytest tests/ -v
# Run with coverage
uv run pytest tests/ --cov=src/octopilot_mcp --cov-report=term-missingTool module coverage target: ≥95% (actions, detect, generate, op_runner).
See CONTRIBUTING.md for details.
Resources
The server also exposes MCP resources for agent context:
octopilot://actions— Full actions registry JSONoctopilot://pipeline-context-schema— JSON Schema for pipeline-contextoctopilot://docs/getting-started— Plain-text onboarding guideoctopilot://docs/skaffold-patterns— Commonskaffold.yamlpatterns
Available Tools
7 toolstool_detect_project_contextsA
Parse skaffold.yaml in the workspace and return a pipeline-context JSON object.
The pipeline-context is consumed by lint, test, janitor, and ci workflow generation. It contains the detected languages, versions, and build matrix.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | Absolute path to the repository root (must contain skaffold.yaml). |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only states the tool parses a file and returns JSON, but omits critical details such as side effects (none implied), error handling for missing or malformed skaffold.yaml, and any permissions required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundancy. The first sentence states the core action, and the second adds valuable context about consumption. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to detail return values. However, it could be improved by noting prerequisites (e.g., file existence) or edge cases. Overall, it is sufficient for a simple parsing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single parameter 'workspace' is already well documented in the input schema. The description adds no extra semantic information beyond the schema, earning the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Parse') and resource ('skaffold.yaml'), clearly stating the tool's action and output. It distinguishes itself from sibling tools like tool_generate_ci_workflow and tool_generate_skaffold_yaml by focusing on parsing an existing file rather than generating or modifying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the downstream use of the output ('consumed by lint, test, janitor, and ci workflow generation'), indicating when the tool is typically invoked. However, it does not explicitly state when to avoid using it or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tool_generate_ci_workflowB
Generate a complete .github/workflows/ci.yml for the repository.
| Name | Required | Description | Default |
|---|---|---|---|
| registry | Yes | Target container registry and org, e.g. "ghcr.io/my-org". | |
| platforms | No | Comma-separated platform list (default: linux/amd64,linux/arm64). | linux/amd64,linux/arm64 |
| pipeline_context | Yes | Output from detect_project_contexts(). | |
| golangci_lint_timeout | No | Timeout for golangci-lint; increase for large vendor trees. | 10m |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description does not disclose behavioral traits such as whether the tool overwrites existing files, requires authentication, or has side effects, leaving the agent unaware of important constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded, but it could benefit from a structured list or additional context that earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and a nested object parameter, the description does not explain what the generated workflow contains, nor does it mention that the file will be created or overwritten, which is critical for a generation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate' and the specific resource '.github/workflows/ci.yml', and it distinguishes from sibling tools like tool_generate_skaffold_yaml which targets a different output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are any prerequisites, exclusions, or when-not-to-use conditions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tool_generate_skaffold_yamlB
Generate a skaffold.yaml for the given build artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
| builder | No | Cloud Native Buildpack builder image to use. | ghcr.io/octopilot/builder-jammy-base:latest |
| artifacts | Yes | List of {"name": str, "context": str} dicts. 'name' is the image name; 'context' is the relative path to the source. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'generate' without specifying if it overwrites, requires existing files, or any side effects. Behavioral traits are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no waste, and front-loaded. Could include more detail without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and two parameters, the description is minimal. It doesn't explain the output or any behavior. Not complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description repeats 'given build artifacts' but adds no extra meaning beyond the schema's descriptions for 'builder' and 'artifacts'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a skaffold.yaml for build artifacts. It is specific and distinct from sibling tools like tool_generate_ci_workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, or any prerequisites or exclusions. The description is silent on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tool_get_action_detailsA
Return the full spec for a single Octopilot GitHub Action.
Includes: description, all inputs/outputs, example workflow YAML, and known gotchas with symptoms and fixes.
| Name | Required | Description | Default |
|---|---|---|---|
| action_id | Yes | Action identifier, e.g. "octopilot", "lint", "test", "janitor", "detect-contexts", "release", "sops-decrypt", "setup-tools", "rotate-secret", "kubernetes-auth", "gke-allow-runner", "eks-allow-runner", "aks-allow-runner". |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It lists what the return includes but does not disclose behavioral traits like read-only nature, authentication needs, or side effects. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and every sentence adds value. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 param, has output schema), the description is adequate and covers the essential return content. Could mention return format or when the action_id is invalid, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter (action_id) well-described. The description adds no further semantic value beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the full spec for a single Octopilot GitHub Action, with specific content. It distinguishes from siblings like tool_list_actions by focusing on a single action's details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing detailed info on a specific action but does not provide explicit when-to-use, when-not-to-use, or alternatives. Siblings exist (e.g., tool_list_actions) but no guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tool_list_actionsA
Return all Octopilot GitHub Actions from the bundled registry.
Each entry includes: id, title, path, description, features, inputs, outputs. Use get_action_details for examples and gotchas.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return structure but does not mention potential side effects, authentication, or rate limits. However, as a read-only list operation, this is sufficient for behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the main purpose, and includes necessary details without any fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no parameters and an existing output schema, the description completely covers the tool's behavior, including what each returned entry contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema description coverage is 100% (trivially). The description adds value by detailing the return fields, which goes beyond the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns all Octopilot GitHub Actions from the bundled registry, listing the fields included. It distinguishes itself from sibling tool get_action_details by directing users there for examples and gotchas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance to use get_action_details for examples and gotchas, indicating when to choose an alternative. It does not specify when not to use this tool, but the context is clear for a listing operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tool_onboard_repositoryA
Onboard a repository end-to-end in a single call.
Detects the project languages, generates skaffold.yaml (if missing) and .github/workflows/ci.yml, and returns a ready-to-commit file set plus a checklist of remaining manual steps.
| Name | Required | Description | Default |
|---|---|---|---|
| builder | No | Buildpack builder image. | ghcr.io/octopilot/builder-jammy-base:latest |
| registry | Yes | Container registry and org, e.g. "ghcr.io/my-org". | |
| platforms | No | Target build platforms. | linux/amd64,linux/arm64 |
| workspace | Yes | Absolute path to the repository root. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions returning a file set and checklist but lacks details on side effects (e.g., does it write to disk?), required permissions, or error conditions. More transparency is needed for a mutation-like operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences. The first sentence states the high-level purpose, and the second adds specific actions and outputs. No redundancy or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of end-to-end onboarding and the presence of an output schema, the description covers key actions and outputs but omits prerequisites, error scenarios, and details about what is included in the returned file set. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, with each parameter having a description. The tool description adds no additional information beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Onboard a repository end-to-end in a single call.' It lists specific actions (detects languages, generates skaffold.yaml and CI workflow) and outputs, distinguishing it from sibling tools like tool_generate_ci_workflow and tool_generate_skaffold_yaml by being a composite operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies 'end-to-end' usage but does not explicitly state when to use this tool versus the more granular sibling tools. No guidance is given on prerequisites or when not to use it, leaving the agent to infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tool_run_op_buildA
Run op build in the workspace using the official op container.
Docker or Colima must be running. The container image is always pulled before each run so the latest op release is used automatically. Set OP_IMAGE in the MCP server env to pin to a specific version.
| Name | Required | Description | Default |
|---|---|---|---|
| push | No | If True, push images to the registry after building. | |
| registry | Yes | Target registry/org, e.g. "ghcr.io/my-org". | |
| platforms | No | Comma-separated platform list. | linux/amd64 |
| workspace | Yes | Absolute path to the repository root (must contain skaffold.yaml). |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that Docker/Colima must be running, the image is pulled each run, and OP_IMAGE can pin a version. However, it does not mention that the workspace must contain skaffold.yaml (implied by schema but not in description), nor what the tool modifies or creates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first states the core action, second adds prerequisite, third adds configuration. No superfluous words, front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic usage and prerequisites. However, it fails to mention that the workspace must contain skaffold.yaml (a required file per the schema description for workspace). Given that an output schema exists, return values are not needed, but the missing prerequisite is a notable gap for a build tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the input schema (100% coverage), so the description adds no additional semantic value beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs 'op build' in the workspace using the official op container. The verb 'run' and resource 'op build' are specific, and it distinguishes from sibling tools which are about detection, CI generation, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: Docker or Colima must be running, and the container image is always pulled. However, it does not explicitly state when not to use this tool or mention alternatives, though siblings are for different tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v0.1.0- First observed
tool_detect_project_contexts - First observed
tool_generate_ci_workflow - First observed
tool_generate_skaffold_yaml - First observed
tool_get_action_details - First observed
tool_list_actions - First observed
tool_onboard_repository - First observed
tool_run_op_build
TDQS
Scored across 7 tools
Each tool targets a distinct operation: project detection, CI workflow generation, skaffold generation, action details, action listing, full onboarding, and running builds. There is no functional overlap.
All tools follow a consistent verb_noun pattern in snake_case (e.g., detect_project_contexts, generate_ci_workflow, list_actions). The naming is predictable and clear.
With 7 tools, the set is well-scoped for the domain of CI/CD pipeline management and onboarding. Each tool has a clear purpose and contributes to the overall workflow.
The tool surface covers core workflows: detection, generation, action interaction, onboarding, and building. Minor gaps exist (e.g., no tool for updating existing configurations or tear-down), but the main use cases are addressed.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Related MCP Servers
- AlicenseAqualityAmaintenanceA Model Context Protocol (MCP) server that helps large language models index, search, and analyze code repositories with minimal setup14548 PyPI1,004MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).13 npm3Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that bridges BMAD agents with GitHub Copilot, enabling AI-assisted development workflows through specialized agent tools and prompts.79 npm1ISC
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that provides VSCode context and filesystem operations for AI assistants.9-