MCP — AI Access to the Platform

The Polycrate API MCP gives AI assistants in the IDE read-only access to your organization's workspaces, clusters, alerts, logs, metrics and live Kubernetes objects. Setup, authentication, available tools and security model.

MCP — AI Access to the Platform

The API MCP gives AI assistants in the IDE (Cursor, Claude Code, comparable clients) read-only access to your Polycrate organization: workspaces, clusters, alerts, logs, metrics and live Kubernetes objects.

It is not the same server as the local CLI MCP and not the Assistant chat in the web UI.

Which MCP do you need?

Both servers can be configured in Cursor in parallel — under different names.

The Assistant in the Polycrate UI is a separate chat with its own session and usage. It does not replace the MCP and vice versa.

→ Local Hub/docs MCP: MCP Server (CLI)

What the API MCP can do

The assistant can, on your behalf (with the permissions of the API key):

• List and show objects individually (workspaces, clusters, alerts, …)
• Query logs (VictoriaLogs) and metrics (VictoriaMetrics) — same scope as polycrate logs / polycrate metrics
• Read Kubernetes resources you are allowed to see in the cluster (Deployments, Pods, Services, …)

It cannot:

• create, change or delete anything — not even with a read_write key
• read Kubernetes Secrets or use kubectl exec / port-forward
• show credentials, tokens or key material (they are removed or masked)
• act as a monitoring agent (agent tokens are rejected)

Signing in

The browser login (SSO session) does not apply to MCP. A Bearer token is required.

Agent tokens from endpoint monitoring do not work.

Creating and revoking: API Keys & Authentication

Setting up in Cursor

1. Create an API key and copy it.
2. Add a second server to ~/.cursor/mcp.json (you can keep the CLI MCP):

{
  "mcpServers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    },
    "polycrate-api": {
      "url": "https://api.acme.corp/mcp",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    }
  }
}

3. Restart Cursor. Eight tools from polycrate-api should appear under MCP tools.

Replace api.acme.corp with your API URL (the same base as in ~/.polycrate/polycrate.yml under api.url). The path is always /mcp.

Claude Code

{
  "mcpServers": {
    "polycrate-api": {
      "type": "http",
      "url": "https://api.acme.corp/mcp",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    }
  }
}

Checking the connection

Without a token, GET https://<your-api-host>/mcp responds with a health status (no secret). Tool calls require the header; missing or agent tokens return 401.

What customers see

Every signed-in user without superuser rights — including ayedo staff without superuser — sees the same customer catalog. The eight tools are the same as for superusers; only internal object types are missing.

Blocks and action runs in the workspace are not part of the customer catalog (superusers only).

What superusers see in addition

Only accounts with Superuser / Super Admin. A staff flag without superuser is not sufficient — the customer catalog applies in that case.

Additionally, among others: regions, S3 clusters, load balancer regions, PoPs, providers and provider accounts, blocks and action runs, rollouts, domains and certificates, CVEs and compliance reports, notifications, notes and projects, Grafana dashboards and datasources, IPAM, billing/pricing.

System configuration (SystemConfig) is not reachable via MCP.

Tools (for admins)

The assistant picks the tools itself. For support and approvals:

IDs vs. names

• list and get filter organizations and workspaces by UUID.
• Logs and metrics require the organization name (e.g. acme), optionally workspace and block names — no UUID.

If the assistant reports "unknown type", the type is not in the catalog of this key (customer key vs. superuser).

Example questions

"List the workspaces of the organization acme."

"Which alerts are currently firing? Show details for the first one."

"Logs of the last four hours for organization acme, workspace shop-prod, errors."

"Which deployments are running in the cluster of shop-prod in the namespace default?"

Kubernetes Secrets are rejected. Fields such as tokens or PEM keys in other objects are returned masked.

Security (admin)

• Read only. Writes do not go through MCP, regardless of the key mode.
• No session cookie. MCP is for machines/IDE, not for the browser tab.
• No agent token. Monitoring agents stay restricted to their check APIs.
• No Secret object. Kind Secret / SecretList is blocked; data / stringData are removed.
• Tenant boundary. Organization API keys only see their own org; cross-tenant is rejected.
• Redaction. Sensitive fields (passwords, tokens, PEM, nested org/workspace secrets) are truncated or removed.

Org API keys may list alerts (read). Creating, changing and deleting alerts remains an admin task in the UI/API — not via MCP.

Troubleshooting

See also

• MCP Server (CLI) — Hub, documentation, schemas
• API Keys & Authentication
• Observability (Logs & Metrics)
• Endpoint Monitoring — agent tokens (not for MCP)