Skip to main content
Glama
agent-control-plane-mcp
by czyrok

agent_control_plane

Syncs Plane work items with Coder agent workspaces: starts a workspace for each ready item, writes the link back, stops it once the item is closed, and serves the agent's Plane tools over MCP. It is the only service holding a Plane API key.

Sync

Every 30 s it reads the project's work items and:

  • starts a workspace for each item in Todo carrying an Agent label (Claude Code or OpenCode) whose blockers are all Merged, lowest number first, while fewer than MAX_RUNNING_WORKSPACES workspaces run;

  • names it lyre-<n>, on branch lyre-<n>-<title slug>, with the item's Repository labels (else its nearest ancestor's) and a prompt built for the item's scope (Research and Spec items open no pull requests);

  • adds a "Coder workspace" link on the item and moves it to In Progress;

  • moves an item from Waiting back to In Progress on the first comment not posted by this service after a question;

  • stops the workspace of an item moved to Merged or Cancelled, or deleted. Finished keeps it running for review feedback.

States and labels are found by the external_id Plane provisioning stamps on them (todo, waiting, agent/claude_code, scope/spec, …), never by name.

Related MCP server: Plane MCP Server

MCP tools

Workspaces reach http://agent-control-plane-mcp.coder.svc.cluster.local/mcp (port 4331):

  • get_work_item {} returns the item as Markdown: description, parents with their comments, children, blockers and comments.

  • add_comment { body } posts Markdown on the item.

  • finish_work_item { summary } posts the summary and moves the item to Finished.

The caller is identified as in the gatekeeper: the running pod whose IP is the TCP peer in WORKSPACES_NAMESPACE. A workspace not started from a work item gets a plain answer saying so.

Internal API

On http://agent-control-plane.coder.svc.cluster.local (port 4332), reached only by the gatekeeper's pods and the dashboard namespace:

Request

Answer

POST /questions {id, workspace, question}

Comment on the item, state Waiting; {itemKey, itemName, url}, or 404 when the workspace has no item. Repeating an id posts nothing new

GET /questions/<id>

{answered, answer} or 404

GET /waiting

{items: [{name, url}]} of unanswered questions

GET /health

ok

Links and questions live in SQLite at DATABASE_PATH.

Develop

nix develop gives bun and node; Coder agent workspaces load the same shell, as .#agent, on start.

bun install
bun run start
bun run check

bun run start runs node src/main.ts (Node strips the types, there is no build). Without PLANE_URL the sync loop stays off and only the HTTP servers run.

Build and push

A push to main runs .github/workflows/image-to-registry.yaml, which pushes lyre/agent_control_plane:latest-amd64 and latest-arm64 to the S3-backed registry. It needs an environment release holding DOCKER_IMAGE_REGISTRY_BUCKET_REGION, DOCKER_IMAGE_REGISTRY_BUCKET_NAME, DOCKER_IMAGE_REGISTRY_BUCKET_ACCESS_KEY_ID and DOCKER_IMAGE_REGISTRY_BUCKET_ACCESS_KEY_SECRET, the gatekeeper's values.

By hand, from the lyre devShell, with the local registry proxy running:

cargo make registry-image
kubectl -n coder rollout restart deployment agent-control-plane

Environment

Variable

Value

MCP_PORT

Port serving only /mcp, 4331

INTERNAL_PORT

Port of the internal API, 4332

DATABASE_PATH

SQLite file, on the data volume

WORKSPACES_NAMESPACE

Namespace of the workspace pods allowed on /mcp

PLANE_URL

In-cluster Plane URL; empty disables the sync

PLANE_PUBLIC_URL

Plane URL used in links

PLANE_WORKSPACE_SLUG

Plane workspace, lyre

PLANE_PROJECT_IDENTIFIER

Plane project, LYRE

PLANE_ADMIN_EMAIL

Plane admin the API key is minted for

PLANE_ADMIN_PASSWORD

Its password

CODER_URL

In-cluster Coder URL

CODER_PUBLIC_URL

Coder URL used in the workspace link

CODER_TEMPLATE

Template workspaces are created from, agent-task

CODER_ADMIN_EMAIL

Coder admin, from Coder's admin Secret

CODER_ADMIN_PASSWORD

Its password, from the same Secret

AGENT_REPOSITORIES

JSON map of Repository label key to owner/name

MAX_RUNNING_WORKSPACES

Running workspaces above which none starts, 2

NODE_EXTRA_CA_CERTS

The ServiceAccount ca.crt, to trust the API server

The Terraform module in .terraform-module/ sets all of them.

Traps

  • The Plane API key is re-minted on every start: the previous key labelled agent-control-plane is revoked first.

  • Workspaces are owned by Coder's admin. Signed in to Coder as another user, they stay hidden unless that user is an owner.

  • Plane allows 60 API requests a minute per instance, shared by the sync and the agents' tool calls. A 429 skips the tick; raise API_KEY_RATE_LIMIT on Plane's API if it happens often.

License

MIT, see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers