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., "@controlplane-mcp Adopt my existing project for orchestration."
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.
ControlPlane MCP v0.1 is a small local Python server for adopting an already-scoped project into a durable, repo-backed coordination pattern. Markdown and TOML in the target repository remain the database of record; MCP is only the interface.
Python 3.11 or newer is required. From this repository:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"The v0.1 package currently targets MCP Python SDK 2.0.x. Its dependency metadata excludes 2.1 and later until their changed tool-exception rendering can be adopted without weakening ControlPlane's stable actionable-error contract.
The server is scoped to one allowed workspace root at process startup. Set CONTROLPLANE_ALLOWED_ROOT to that existing directory, then launch the local stdio transport:
$env:CONTROLPLANE_ALLOWED_ROOT = 'C:\path\to\allowed-workspace'
.\.venv\Scripts\python.exe -m controlplane_mcpIf the variable is omitted, the process working directory is the single allowed root. The target project directory must already exist beneath it. Relative project paths are resolved from that root; absolute paths are accepted only when their resolved location remains inside it.
For a generic MCP host, register these inputs in the host's own configuration:
command: the environment's Python executable;
arguments: -m, controlplane_mcp;
working directory: this installed project or another suitable launch directory;
environment: CONTROLPLANE_ALLOWED_ROOT=<absolute allowed root>;
transport: stdio.
The generic stdio launch and all five tools are covered by automated tests, including a real subprocess integration test. For Codex, use a trusted project-local configuration where practical and confirm the server with codex mcp list or /mcp.
For exact Codex configuration, verification labels, and copyable fresh-thread adoption prompts, see Documentation/CODEX_ADOPTION_RUNBOOK.md.
Related MCP server: Coding Tools MCP
Install the test extra and run the full suite:
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest -qThe suite covers repository bootstrap and validation, role-scoped outputs, resolved-path containment (including symlink/junction escape cases), MCP tool metadata, and real STDIO startup/shutdown.
The fixture and preparation helper build a fresh local Git repository, configure the server project-locally, bootstrap the supplied demo brief, and verify that no work order is fabricated:
.\.venv\Scripts\python.exe scripts\prepare_codex_live_rehearsal.py `
--workspace C:\path\to\new-disposable-workspaceThe destination must not already exist. The script deliberately refuses to
overwrite it. See examples/codex-live-rehearsal/PROJECT_BRIEF.md for the neutral
demo purpose.
bootstrap_project is the only mutation. It accepts project_path, project_id, project_name, and non-empty caller-supplied project_brief. It creates only initial scaffolding and state, is idempotent for identical inputs, reports conflicts without overwriting, and never creates a work order.
get_project_status returns compact canonical state and explicit validation errors.
get_orchestrator_bootstrap returns project purpose, current state, authority, issuance guidance, and evidence-review gates.
get_worker_bootstrap returns bounded worker context, first-order identity requirements, execution gates, evidence permissions, and stop/review behavior.
get_bootstrap_context accepts only orchestrator or worker and returns structurally different, narrowly role-scoped context.
The four read tools are annotated read-only and closed-world. bootstrap_project is annotated non-destructive and idempotent. MCP annotations are client hints, not security controls.
.controlplane/config.toml
Documentation/PROJECT_BRIEF.md
Documentation/CURRENT_STATE.md
WorkOrders/
Decisions/
Evidence/The initial configuration stores only schema version and caller-supplied project identity. The Project Brief is written exactly as supplied. Initial CURRENT_STATE says no work is authorized. Empty work, decision, and evidence directories are created; no WO-001 or other substantive order is invented.
With an allowed root C:\work and an existing empty directory C:\work\sample, call:
{
"name": "bootstrap_project",
"arguments": {
"project_path": "sample",
"project_id": "sample",
"project_name": "Sample Project",
"project_brief": "# Sample Project\n\nBuild the caller-defined sample safely.\n"
}
}Calling again with exactly the same values returns an idempotent existing-state result. Different identity or brief content is a conflict and is never written over the canonical files.
Only an orchestrator transitions canonical work-order state. READY is not permission to execute, and worker completion is not acceptance. The canonical orchestrator and primary worker must be separate first-order, user-visible threads or tasks. A primary worker is a persistent project-level identity; work orders are temporary assignments. The worker bootstrap returns a manual lifecycle prompt only when no primary worker exists or replacement is explicitly recorded, and it reports worker reachability, start confirmation, assignment, and canonical activation separately.
Ordinary dispatch is one ACTIVE-plus-START message: the worker verifies the canonical ACTIVE commit, explicit START, identity, and scope, executes in that same turn, and next reports completion for orchestrator review. There is no acknowledgement-only turn.
v0.1 does not authenticate caller roles. Safety comes from a read-oriented API surface, one narrow initialization mutation, resolved-path containment, strict state validation, conflict refusal, and explicit authority protocol. Filesystem containment is checked before each operation, but v0.1 does not claim protection against an adversary racing filesystem links between validation and use.
Apache License 2.0. See LICENSE.
Initialize canonical scaffolding from an explicit caller-supplied brief.
The target directory must already exist under the configured workspace root. This never infers purpose, overwrites canonical state, or creates a work order.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| project_name | Yes | ||
| project_path | Yes | ||
| project_brief | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds valuable context: it never infers purpose, never overwrites canonical state, and never creates a work order. This goes beyond annotations and clarifies the side-effect profile, though it does not mention permission requirements or output format (which is covered by output schema).
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 primary purpose, followed by clear constraints and exclusions. There is no fluff or redundancy; every clause earns its place. It is an example of exemplary 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?
The tool has four required parameters with zero schema descriptions and the description adds no parameter details. Usage guidance is only implicit. Though the output schema exists, the lack of any help on parameter semantics and selection criteria makes the description incomplete for an agent to invoke correctly without guessing.
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 0% and the tool description provides absolutely no explanation of any of the four required parameters. The parameters (project_id, project_name, project_path, project_brief) have only their names; no semantics are conveyed. The description fails entirely to compensate for the lack of schema documentation.
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 states a specific verb ('Initialize') and resource ('canonical scaffolding') and clarifies the deliberate, non-inferential nature, which distinguishes it from the getter siblings. It also gives explicit exclusions ('never infers purpose, overwrites canonical state, or creates a work order'), making the tool's purpose unmistakable.
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 a clear precondition ('target directory must already exist') and implies this is an initialization tool versus the getter siblings, but it does not explicitly state when to use this tool over alternatives or when not to use it. No explicit routing guidance is given, leaving the agent to infer from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return narrowly role-scoped canonical context for the requested role.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | ||
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds that the context is 'canonical' and 'role-scoped', which provides some behavioral context, but it does not disclose specifics like error conditions, the exact structure of the response, or any side effects (though read-only implies none). It does not contradict the annotations.
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 sentence and is not verbose, but it sacrifices essential details for brevity. Phrases like 'narrowly role-scoped' add little concrete value. It could be more effective while remaining concise if it included the project_path parameter and a note on the sibling roles.
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 is incomplete for a tool that has direct role-specific siblings. It does not clarify the difference between get_bootstrap_context and get_orchestrator_bootstrap/get_worker_bootstrap, nor does it hint at the role of project_path. While an output schema exists (per context signals), the description still needs to convey what 'canonical context' means operationally. An agent would likely need to inspect sibling definitions to use this correctly.
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 0%, so the description carries the full burden for parameter explanation. It mentions the 'role' concept but does not explain the allowed enum values or what 'project_path' refers to or its format. The role is only implied, and project_path is entirely absent from the description. This is a significant gap for a tool with only two required parameters.
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 'return' and the resource 'canonical context' scoped by role. It implies a generic role-parameterized tool, but it does not explicitly distinguish itself from get_orchestrator_bootstrap and get_worker_bootstrap, which are direct role-specific alternatives. The word 'narrowly role-scoped' hints at the distinction but doesn't name the siblings.
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 given on when to use this tool instead of the sibling tools, particularly get_orchestrator_bootstrap and get_worker_bootstrap. The agent must infer the relationship from the role enum, which is not spelled out. There is no mention of exclusions, prerequisites, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return purpose, state, authority, issuance guidance, and review gates.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so read-only behavior is covered. The description lists returned fields, which is a small addition, but it does not explain any operational behavior such as error conditions, required permissions, or the meaning of the returned fields beyond their names. Minimal added context beyond annotations.
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 very short and to the point, but it is little more than a list of return fields. It lacks any structural elements like a clear tool purpose or usage guidance. While concise, it is under-specified rather than efficiently structured.
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?
Although an output schema exists and likely details the return fields, the description offers no additional context about when to call this tool, how to interpret the output, or any side effects. For a tool with one parameter and a read-only annotation, the description is too sparse to be considered complete.
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?
The sole parameter project_path has zero description coverage (0%) in the input schema, and the description does not mention it at all. The description fails to compensate for the lack of schema-level documentation, leaving the agent to guess what project_path should be (path, ID, etc.).
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 states that the tool returns a list of items (purpose, state, authority, etc.) but lacks a specific action verb and does not clarify what 'orchestrator bootstrap' means or how it differs from siblings like get_worker_bootstrap. It is vague about the tool's core purpose beyond returning a set of fields.
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 indication of when to use this tool versus the sibling tools (bootstrap_project, get_project_status, get_worker_bootstrap, get_bootstrap_context). The description provides no context, prerequisites, or explicit conditions for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return compact canonical status and explicit validation errors.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only behavior is covered. The description adds that the tool returns 'compact canonical status and explicit validation errors', which is a useful behavioral detail beyond the annotation. However, it does not describe any other side effects, prerequisites, or response nuances, so it adds limited context.
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 sentence, front-loaded with the core action, and contains no extraneous wording. Every word contributes to meaning, making it appropriately concise and well-structured.
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 tool has an output schema, so return values are already defined. The main gaps are the lack of parameter explanation and missing usage guidance. For a simple one-parameter read-only tool, the description is minimally sufficient but not complete; an agent would still need to infer what 'project_path' means.
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 0%, and the description completely fails to explain the required parameter 'project_path'. There is no indication of what the path refers to, its format, or constraints. The description provides zero value in clarifying the parameter beyond the schema's type/title.
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 states a specific verb ('Return') and resource (canonical status and validation errors). It is concise and clear about what the tool produces. However, it does not explicitly differentiate from sibling tools, though the siblings are bootstrap-related and thus functionally distinct in name.
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 offers no explicit guidance on when to use this tool versus alternatives. It does not mention any exclusions or contexts. The purpose implicitly suggests use when needing status or validation info, but this is not stated, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return bounded worker entry context, execution gates, and stop behavior.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only safety profile is handled. The description gestures at behavior through 'execution gates' and 'stop behavior' but does not explain what those involve, any limits of 'bounded', or consequences beyond the fact that this is a read 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 a single front-loaded sentence with no filler. Each phrase ('bounded worker entry context', 'execution gates', 'stop behavior') contributes a distinct aspect of the returned data, making it appropriately sized for a read-only tool with an output schema.
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 output schema and readOnly annotation cover the return shape and safety profile. However, the description does not differentiate this tool from its sibling tools and leaves key terms ('bounded', 'execution gates') undefined, so the agent lacks enough context to confidently select and invoke the 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 0% and the tool description never mentions 'project_path'. The agent must infer from the bare property name that it is a path, with no guidance on format, required meaning, or how it relates to the worker bootstrap context.
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 names a specific action ('Return') and a specific resource ('worker entry context'), and lists the returned facets: bounded context, execution gates, and stop behavior. It is distinguishable from 'get_orchestrator_bootstrap' by the word 'worker', though the terminology is somewhat unexpanded.
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 statement tells the agent when to use this tool over the closely related siblings such as get_bootstrap_context or get_orchestrator_bootstrap. Usage is only implied by the word 'worker'; there are no exclusions, prerequisites, or alternative routing clues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0bootstrap_projectget_bootstrap_contextget_orchestrator_bootstrapget_project_statusget_worker_bootstrapScored across 5 tools
The getter tools for bootstrap context overlap: get_orchestrator_bootstrap, get_worker_bootstrap, and get_bootstrap_context all return role-scoped context, with the generic one likely covering the same ground. Only bootstrap_project is clearly distinct, while the getter separation by role is somewhat clear but not fully disambiguated.
All tool names are snake_case and follow a verb_noun pattern consistently. bootstrap_project stands out as an action, while the others use get_ prefix, but this is a typical and understandable distinction. The consistent prefix and structure make the naming predictable.
With only 5 tools, the surface is compact and well‑scoped for a control plane bootstrap service. Each tool appears to serve a distinct functional need without bloat, making the count appropriate for the apparent domain.
The tool set covers project bootstrap, status retrieval, and role‑specific context, but lacks lifecycle operations like listing or updating projects. The generic get_bootstrap_context seems redundant, and there are no endpoints for project deletion or modification, leaving notable gaps for a control plane.
Project memory, semantic code search, and grounded agent context.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Durable, shareable and governed project memory with smart triage and explicit project composition.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.