MCP Support

InfraKitchen supports the Model Context Protocol (MCP), exposing a stateless, streamable HTTP endpoint at /api/mcp so AI agents can inspect and manage your infrastructure. MCP tools call the REST and GraphQL APIs with the client’s own bearer token, so an agent can do exactly what its service account is allowed to do — the protocol grants no additional privileges.

Enabling MCP

MCP is disabled by default, and the MCP_ENABLED flag is only checked once when the server starts — a restart is required for changes to take effect. To enable it, set the flag in your environment or .env file:

MCP_ENABLED=true

When MCP is enabled, the endpoint is mounted at /api/mcp; when it is disabled, the route is never registered and requests to /api/mcp return 404 Not Found.

Authentication

The MCP endpoint requires authentication on every request. The data and actions available through MCP mirror the permissions of the authenticating service account.

Authorization: Bearer <service-account-token>

Connecting an MCP client

Any MCP client that supports streamable HTTP can connect to the endpoint.

Claude Code

claude mcp add --transport http infrakitchen https://<your-infrakitchen-host>/api/mcp \
  --header "Authorization: Bearer <service-account-token>"

VS Code / GitHub Copilot

Add the server to .vscode/mcp.json (workspace) or your user-level mcp.json. Copilot agent mode picks up the server automatically; with the inputs block below, VS Code prompts for the token on first use instead of storing it in the file:

{
  "servers": {
    "infrakitchen": {
      "type": "http",
      "url": "https://<your-infrakitchen-host>/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:infrakitchen-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "infrakitchen-token",
      "description": "InfraKitchen service account token",
      "password": true
    }
  ]
}

Generic client configuration

Most clients (Cursor, Windsurf, and others) accept a JSON configuration:

{
  "mcpServers": {
    "infrakitchen": {
      "url": "https://<your-infrakitchen-host>/api/mcp",
      "headers": {
        "Authorization": "Bearer <service-account-token>"
      }
    }
  }
}

MCP Inspector

To explore the server interactively, run the MCP Inspector and connect to the URL with the Authorization header:

npx @modelcontextprotocol/inspector

Tool catalog

Schema discovery and reads

Writes

Every writable entity exposes up to three tools:

Notes on the write tools:

• Request bodies prefer snake_case keys; they are translated to GraphQL camelCase automatically. Provider-specific configuration is passed through as raw JSON.
• patch_* requires at least one field in the body.
• patch_action_* runs a lifecycle action on an existing entity. Query the entity’s *Actions query first (for example resourceActions(id: ...)) to see which actions are allowed for its current state, then pass one of those values.

Documentation

Safety model

• Resources are gated. New resources land in the approval-pending state and wait for a human to approve before any cloud provisioning happens. Patches to live resources are staged and also require approval. MCP cannot bypass this gate.
• Other entities are not gated. Creating or modifying templates, code repositories, template versions, storages, integrations, and executors takes effect immediately.
• Lifecycle actions change state immediately. patch_action_* tools can trigger actions such as approve, reject, destroy, recreate, or disable when those actions are allowed for the entity’s current state.
• Use a least-privilege service account. Give the agent’s service account only the permissions it needs; MCP is subject to the same authorization checks as the REST and GraphQL APIs.
• Everything is auditable. Changes made through MCP appear in the Audit Logs like any other API activity.

Troubleshooting