MCP Server

The local Polycrate MCP server (polycrate mcp): six tool families for hub, documentation, specs, workspace and block releases and actions. Configuration for Cursor, Claude Desktop and Copilot.

Polycrate offers AI assistants two separate MCP servers. This page describes the local CLI MCP (polycrate mcp): hub, documentation, schemas and the complete SDD/release flow for workspaces and blocks.

For live platform data (workspaces, alerts, clusters, logs) you need the API MCP — different endpoint, API key.

This page (CLI) API MCP
Start polycrate mcp on your machine https://<your-api-host>/mcp
Content hub blocks, docs, schemas, specs, releases, actions objects and observability of your organization
Login not required Bearer API key
Mutations yes — local files, registry push, action runs yes — platform objects

Both entries can coexist in Cursor. The assistant chat in the Polycrate UI is a third product and not an MCP.

What the CLI MCP does

The Model Context Protocol (MCP) is an open standard through which AI models call external tools. The local Polycrate MCP performs the same operations as the CLI — every tool call is a polycrate command with identical gates:

  • Blocks in the hub: search, inspect, list versions
  • Documentation: local schemas (workspace.poly, block.poly, …), embedded guides, public docs from ayedo.de
  • Specs: create, read, write sections, set status, lint
  • Workspace releases: create, write changelog/release note, finalize
  • Block releases: record, finalize, push, pull downstream
  • Actions: run

The process these ops implement is described in Dev and Deploy and Spec-Driven Development.

Start the server

polycrate mcp

Configuration

Cursor IDE

~/.cursor/mcp.json (global) or .cursor/mcp.json in the project:

{
  "mcpServers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

After saving: restart Cursor. Additionally run polycrate spec rules generate --force -w /abs/path so that .cursor/rules/sdd.mdc binds the agent to the canonical flow.

Claude Desktop

OS File
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json 
{
  "mcpServers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

GitHub Copilot (VS Code)

.vscode/mcp.json in the workspace:

{
  "servers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

The six tools

One server, six tools. Every tool takes op (required) and dispatches on it. No aliases, no session_id. Mutating ops need workspace as an absolute path — relative is a hard fail.

hub

op Parameters Description
info — hub URL, registry, docs URL
list_blocks project, filter, limit search blocks in the hub
inspect_block block_name, content_type (block|readme|changelog) block details
list_versions block_name available versions
cli_latest_version — latest stable CLI version
cli_list_versions limit all CLI versions
cli_artifacts version download URLs and Docker tags

docs

op Parameters Description
schema name: workspace|block|changelog|secrets local schema specification for the respective .poly file
guide name: create_k8sapp_block|create_workspace|ansible_patterns|block_inheritance|registry_workflow|debugging|best_practices|dev_and_deploy embedded step-by-step guides
get path (e.g. /docs/polycrate/dev-and-deploy/), locale (de|en) one public docs page from ayedo.de (public API, no scraping, no token)
search q full-text search in the public docs

sdd

op Parameters CLI equivalent
list workspace spec list
inspect workspace, id spec inspect <id>
create workspace, name, type spec create
update_meta workspace, id, status|type|set=key=value spec update --set — status=done fails on drift or non-empty Open Questions
update_section workspace, id, section, body spec update --section — section bodies only, no H1/H2, no frontmatter
lint workspace, id spec lint
format workspace, id spec format

workspace

op Parameters CLI equivalent
release_create workspace, version, spec (comma-separated, optional) release create X.Y.Z [--spec …] — specs must be done/cancelled
release_update workspace, version, message, type, changelog_item, highlights release update
release_finalize workspace, version release finalize — gates: message, highlights, drift/Open Questions of assigned specs
release_status workspace, version release status --no-pager

block

op Parameters CLI equivalent
release_update workspace, block, version, message, type, changelog_item, app_version release --block <name> update
release_finalize workspace, block, version release block-finalize — sets block.poly version, pushes
release_status workspace, block, version release --block <name> status
push workspace, block block push
pull workspace, block (FQBN), version (required) block pull <fqbn>:<version> — rewrites from: on all instances
verify workspace, block, version (optional) block verify --format json

There is no release_create for blocks — the call returns an error pointing to release_update → release_finalize. Blocks have no specs.

action

op Parameters CLI equivalent
run workspace, block, action polycrate run <block> <action>

Examples

Block discovery

Tool: hub   {"op": "list_blocks", "filter": "postgres", "limit": 10}
Tool: hub   {"op": "inspect_block", "block_name": "ayedo/k8s/postgres", "content_type": "readme"}
Tool: hub   {"op": "list_versions", "block_name": "ayedo/k8s/postgres"}

Generate a workspace

Tool: docs  {"op": "schema", "name": "workspace"}
Tool: hub   {"op": "inspect_block", "block_name": "ayedo/k8s/cluster"}
→ the assistant produces a complete workspace.poly

Spec to release

Tool: sdd        {"op": "create", "workspace": "/abs/ws", "name": "Rotate hub token", "type": "feat"}
Tool: sdd        {"op": "update_section", "workspace": "/abs/ws", "id": 7, "section": "solution", "body": "### Plan\n…"}
Tool: sdd        {"op": "lint", "workspace": "/abs/ws", "id": 7}
Tool: sdd        {"op": "update_meta", "workspace": "/abs/ws", "id": 7, "status": "done"}
Tool: workspace  {"op": "release_create", "workspace": "/abs/ws", "version": "1.4.0", "spec": "7"}
Tool: workspace  {"op": "release_update", "workspace": "/abs/ws", "version": "1.4.0", "type": "feat", "message": "Hub token rotation", "highlights": "- rotation without downtime"}
Tool: workspace  {"op": "release_finalize", "workspace": "/abs/ws", "version": "1.4.0"}

Release and deploy a block

Tool: block   {"op": "release_update", "workspace": "/abs/core", "block": "hardening", "version": "0.5.6", "type": "fix", "message": "Configurable PerSourcePenalties"}
Tool: block   {"op": "release_finalize", "workspace": "/abs/core", "block": "hardening", "version": "0.5.6"}
Tool: block   {"op": "pull", "workspace": "/abs/prod", "block": "cargo.ayedo.cloud/ayedo/linux/hardening", "version": "0.5.6"}
Tool: action  {"op": "run", "workspace": "/abs/prod", "block": "hardening", "action": "install"}

Look up documentation

Tool: docs  {"op": "guide", "name": "dev_and_deploy"}
Tool: docs  {"op": "get", "path": "/docs/polycrate/spec-driven-development/", "locale": "en"}
Tool: docs  {"op": "search", "q": "workspace encryption"}

Troubleshooting

“MCP Server not found”

which polycrate && polycrate version
cat ~/.cursor/mcp.json

If polycrate is not in PATH, use the full path as command (e.g. /usr/local/bin/polycrate).

“unknown op” or “workspace must be absolute”

The error message lists the allowed ops or demands an absolute path. Both are CLI gates, not MCP gates — the CLI documentation of the respective command applies.

“Connection to Hub failed”

polycrate hub inspect ayedo/k8s/cluster
curl -I https://hub.polycrate.io

“No tools available”

Restart the client completely after changing the MCP configuration.

Security

  • The server runs locally; hub and public API are accessed via HTTPS
  • No credentials are passed to the assistant; docs uses no token
  • Mutating ops (sdd, workspace, block, action) act on local files, the registry and target systems — with the same gates as the CLI
  • Registry auth for action containers comes from DOCKER_REGISTRY_HOST / _USER / _PASSWORD in the process environment; ~/.docker/config.json is not mounted

See also