Polycrate MCP: Connecting AI Assistants with Live Infrastructure Context | Blog

TL;DR

The Model Context Protocol (MCP) is an open standard: AI clients talk to helper programs over stdin/stdout (stdio) using JSON-RPC.
polycrate mcp starts such an MCP endpoint: the client launches it on demand as a subprocess—not a separate service you cd into a workspace to “bring up,” and not a polycrate mcp server command (that does not exist).
Built-in tools include the Polycrate Hub (search, inspect, list versions), official documentation (docs_get), schema helpers for workspace.poly / block.poly / CHANGELOG.poly / secrets.poly, guides (Ansible, registry, debugging, best practices), and CLI metadata (versions, artifacts).
Local workspace files (playbooks, inventory.yml, logs) are not mirrored by Polycrate MCP. Your IDE (e.g. Cursor) already loads the project—together with MCP tools you get full context.
Full reference: MCP Server Integration.

Why plain AI hits limits without Polycrate context

AI assistants excel at generic Ansible or YAML questions—but struggle with your platform standards, approved blocks on the Hub, and correct *.poly shapes. Without up-to-date docs and Hub data, models guess.

Polycrate MCP fills that gap with curated sources (Hub, docs, embedded guides and schemas) instead of generic web knowledge.

How MCP works technically (and what `polycrate mcp` does)

Stdio subprocess, not a long-running server in your project folder

The Polycrate MCP process speaks stdio (JSON-RPC). Typical flow:

You configure Cursor, Claude Desktop, or VS Code / Copilot to run polycrate with argument mcp.
When the model needs an MCP tool, the client starts that process, talks to it, and tears it down—you do not need to keep an MCP process running in a terminal, and you do not need to cd into the workspace for MCP to work (Polycrate must be on PATH or configured with a full path).

The official docs state you usually do not start the server manually—clients do it from configuration. See MCP Server Integration.

What Polycrate MCP is not

Not a substitute for your inventory or playbooks: there are no tools that export “the whole workspace” like a filesystem API.
Not a channel to run polycrate run … from the model—execution stays in your terminal (or CI).

Tools Polycrate exposes

The authoritative list is in the documentation; categories at a glance:

Category	Examples	Purpose
Hub	`hub_info`, `hub_list_blocks`, `hub_inspect_block`, `hub_list_versions`	Discover blocks, README/metadata, versions
CLI	`cli_get_latest_version`, `cli_list_versions`, `cli_get_artifacts`	Releases, download URLs, Docker tags
Spec	`spec_workspace`, `spec_block`, `spec_changelog`, `spec_secrets`	Valid structure for `*.poly` files
Guides	e.g. `guide_create_workspace`, `guide_ansible_patterns`, `guide_registry_workflow`, `guide_debugging`, `guide_best_practices`	Embedded best practices for assistants
Docs	`docs_get` with `topic`	Selected Polycrate documentation pages (configurable base URL)

docs_get supports a fixed set of topics (including workspaces, blocke, best-practices, ansible, registry, mcp)—see the table in the MCP docs.

Custom docs URL: In ~/.polycrate/polycrate.yml you can set hub.docs_url (e.g. local mkdocs serve or an internal mirror). The default is the public documentation site.

Setup: Cursor, Claude Desktop, GitHub Copilot

Configuration is usually JSON with command: polycrate and args: ["mcp"].

Cursor: ~/.cursor/mcp.json—see MCP documentation.
Claude Desktop: platform-specific paths to claude_desktop_config.json (macOS, Linux, Windows)—same doc.
GitHub Copilot (VS Code): .vscode/mcp.json in the workspace or global github.copilot.chat.mcpServers—docs.

After changes: restart the client. If polycrate is not on PATH, use the full path to the binary in the config (troubleshooting in the docs).

Workspace, inventory, and Ansible: combining context correctly

The following example shows a typical Polycrate workspace for Linux patching—independent of MCP: workspace.poly, a block, and root inventory.yml.

# workspace.poly
name: acme-corp-automation
organization: acme

blocks:
  - name: linux-patch
    from: registry.acme-corp.com/acme/linux/linux-patch:1.0.0
    config:
      target_hosts_group: linux_servers

# blocks/linux-patch/block.poly (simplified, local block during development)
name: linux-patch
version: 0.1.0
kind: generic

config:
  target_hosts_group: linux_servers

actions:
  - name: patch
    description: "Patch Linux systems"
    playbook: patch.yml

# inventory.yml (workspace root)
all:
  children:
    linux_servers:
      hosts:
        server01.acme-corp.com:
          ansible_user: ubuntu
        server02.acme-corp.com:
          ansible_user: ubuntu

MCP can supply docs_get for Ansible and best practices; hub_inspect_block can inspect a public Hub block you reference via from:. Your inventory.yml and playbooks are read by the AI in Cursor through the project—not via a separate “workspace export” from Polycrate MCP.

Practice: debugging and design with IDE + MCP

After a failed polycrate run linux-patch patch: Terminal output and files (inventory.yml, patch.yml, block.poly) are in the editor—the model analyzes them there. In parallel it can use MCP docs_get with topic ansible or troubleshooting, or guide_debugging.
Planning a new workspace: spec_workspace, hub_list_blocks to find blocks, hub_inspect_block for README and config schema.
CHANGELOG entry: spec_changelog returns the expected CHANGELOG.poly format.

“Infrastructure context” is therefore two-track: project files (IDE) plus Polycrate-specific knowledge (MCP).

Security and data flow (per documentation)

The MCP process runs locally.
Communication to the Hub uses HTTPS; no credentials are passed to the model as part of tool responses—public Hub data is fetched.
What the model sees from your repo is governed by the IDE and your permissions—that is not the same as MCP tool payloads.

Details: MCP – Security and Workspace encryption.

Frequently asked questions

Is there `polycrate mcp server`?

No. The subcommand is polycrate mcp.

Do I have to start MCP from the workspace directory?

No. You only configure the invocation of polycrate with argument mcp. Your shell’s current working directory for that process does not matter; the binary must be discoverable.

Does Polycrate MCP automatically export my local inventory?

No. Use the editor’s file view / context, or paste relevant snippets into the chat.

Does MCP run `polycrate run`?

No. Execution stays with you.

From theory to practice

Polycrate MCP is not a “magic workspace mirror,” but a precise bridge between AI assistants and the Hub, documentation, schemas, and guides. Together with the IDE, that yields a strong workflow for platform and automation teams.

ayedo develops Polycrate and helps teams integrate it into modern Platform Engineering practices.

Overview and dates: Workshops.