Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

McpServer

Stability: beta -- This resource kind ships with orloj.dev/v1 and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.

Represents a connection to an external MCP (Model Context Protocol) server. The McpServer controller discovers tools via tools/list and auto-generates Tool resources (type=mcp) for each.

spec

  • transport (string): required. stdio or http.
  • command (string): stdio transport: command to spawn the MCP server process. Required unless image is set.
  • args ([]string): stdio transport: command arguments.
  • env ([]object): stdio transport: environment variables for the child process. Each entry has:
    • name (string): environment variable name.
    • value (string): literal value.
    • secretRef (string): resolve value from a Secret resource. Mutually exclusive with value.
    • mountPath (string): absolute path inside the container where the resolved value is written as a file. Only valid when image is set. The env var is set to the mount path so the MCP server can locate the file.
  • image (string): stdio transport: container image. When set, the MCP server runs inside a Docker container (docker run --rm -i) with sandboxing.
  • image_pull_secret (string): name of a Secret containing registry credentials for pulling spec.image. The Secret must contain either a .dockerconfigjson key with a complete Docker config JSON, or registry, username, and password keys. Requires image to be set.
  • idle_timeout (duration string): duration after which an idle session is shut down (e.g. 5m). Default 0 means never evict.
  • endpoint (string): http transport: the MCP server URL.
  • auth (object): http transport: authentication configuration.
    • secretRef (string): secret reference for auth.
    • profile (string): bearer or api_key_header. Defaults to bearer.
  • tool_filter (object): optional tool import filtering.
    • include ([]string): allowlist of MCP tool names. When set, only listed tools are generated. When empty, all discovered tools are generated.
  • reconnect (object): reconnection policy.
    • max_attempts (int): max reconnection attempts. Defaults to 3.
    • backoff (duration string): backoff between attempts. Defaults to 2s.
  • default_tool_runtime (object): default runtime policy inherited by all generated Tool resources. When set, each tool synced from this server receives this policy as its spec.runtime.
    • timeout (duration string): max tool call execution time (e.g. 30s, 2m).
    • isolation_mode (string): isolation mode for tool execution.
    • retry (object): retry policy (see Tool resource).

Defaults and Validation

  • transport is required. Must be stdio or http.
  • command or image is required when transport=stdio.
  • endpoint is required when transport=http.
  • image is only valid with transport=stdio.
  • image_pull_secret requires image to be set.
  • env[].secretRef and env[].value are mutually exclusive.
  • env[].mountPath requires image to be set and must be an absolute path.
  • idle_timeout defaults to 0 (never evict).
  • reconnect.max_attempts defaults to 3.
  • reconnect.backoff defaults to 2s.

status

  • phase: Pending, Connecting, Ready, Error.
  • discoveredTools ([]string): all tool names from the MCP server's tools/list response.
  • generatedTools ([]string): names of the Tool resources actually created.
  • lastSyncedAt (timestamp): last successful tool sync.
  • lastError (string): last error message.

Guide: Connect an MCP Server

Examples: examples/resources/mcp-servers/

See also: MCP server concepts.