Core Concepts

June 17, 2026 · View on GitHub

This document defines the key concepts, terminology, and abstractions used throughout ToolHive. Understanding these concepts is essential for working with the platform.

Platform Philosophy

ToolHive is not just a container runner - it's a platform that provides:

  • Proxy infrastructure with middleware
  • Security and isolation
  • Configuration management
  • Registry and distribution
  • Aggregation and composition

Nouns (Things)

Workload

A workload is the fundamental deployment unit in ToolHive. It represents everything needed to run an MCP server:

Components:

  • Primary MCP server (container or remote endpoint)
  • Proxy process (for non-stdio transports or detached mode)
  • Network configuration and port mappings
  • Permission profile and security policies
  • Middleware configuration
  • State and metadata

Types:

  1. Container Workload: MCP server running in a container
  2. Remote Workload: MCP server running on a remote host

Lifecycle States:

  • starting - Workload is being created
  • running - Workload is active and serving requests
  • stopping - Workload is being stopped
  • stopped - Workload is stopped but can be restarted
  • removing - Workload is being deleted
  • error - Workload encountered an error
  • unhealthy - Workload is running but unhealthy
  • unauthenticated - Remote workload cannot authenticate (expired tokens)
  • auth_retrying - Remote workload's token refresh is failing transiently; monitor is still retrying until success (-> running), a permanent error is observed (-> unauthenticated), or the configured ceiling is exceeded (-> unauthenticated)
  • unknown - Workload status cannot be determined
  • policy_stopped - Workload was stopped by policy enforcement

Implementation:

  • Interface: pkg/workloads/manager.go
  • Status: pkg/container/runtime/types.go
  • Core type: pkg/core/workload.go

Related concepts: Transport, Permission Profile, RunConfig

Transport

A transport defines how MCP clients communicate with MCP servers. It encapsulates the protocol and proxy implementation.

Transport types:

  1. stdio: Standard input/output communication

    • Container speaks stdin/stdout
    • Proxy translates HTTP ↔ stdio
    • Two proxy modes: SSE or Streamable HTTP

  2. sse: Server-Sent Events over HTTP

    • Container speaks HTTP with SSE
    • Transparent HTTP proxy
    • Server-initiated messages supported

  3. streamable-http: Bidirectional HTTP streaming

    • Container speaks HTTP with /mcp endpoint
    • Transparent HTTP proxy (same as SSE)
    • Session management via headers

  4. inspector: Debug-only transport

    • Special transport used for the MCP Inspector tooling
    • Not intended for production workloads

Implementation:

  • Interface: pkg/transport/types/transport.go
  • Types: pkg/transport/types/transport.go
  • Factory: pkg/transport/factory.go

Related concepts: Proxy, Middleware, Session

Proxy

A proxy is the component that sits between MCP clients and MCP servers, forwarding traffic while applying middleware.

Two proxy types:

  1. Transparent Proxy: Used by SSE and Streamable HTTP transports

    • Location: pkg/transport/proxy/transparent/transparent_proxy.go
    • Uses httputil.ReverseProxy
    • No protocol-specific logic
    • Forwards HTTP directly

  2. Protocol-Specific Proxy: Used by stdio transport

    • SSE mode: pkg/transport/proxy/httpsse/http_proxy.go
    • Streamable mode: pkg/transport/proxy/streamable/streamable_proxy.go
    • Parses JSON-RPC messages
    • Implements MCP transport protocol

Proxy responsibilities:

  • Apply middleware chain
  • Handle sessions
  • Forward requests/responses
  • Health checking (for containers)
  • Expose telemetry and auth info endpoints

Implementation:

  • Interface: pkg/transport/types/transport.go

Related concepts: Transport, Middleware, Session

Middleware

Middleware is a composable layer in the request processing chain. Each middleware can inspect, modify, or reject requests.

Middleware types:

  • Authentication (auth) - JWT token validation
  • Token Exchange (tokenexchange) - OAuth token exchange
  • Upstream Swap (upstreamswap) - Swap ToolHive JWTs for upstream IdP tokens (embedded auth server)
  • AWS STS (awssts) - Exchange tokens for AWS STS credentials
  • OBO (obo) - On-Behalf-Of token flow
  • MCP Parser (mcp-parser) - JSON-RPC parsing
  • Tool Filter (tool-filter) - Filter and override tools in tools/list responses
  • Tool Call Filter (tool-call-filter) - Validate and map tools/call requests
  • Rate Limit (ratelimit) - Per-client request rate limiting
  • Usage Metrics (usagemetrics) - Anonymous usage metrics for ToolHive development (opt-out: thv config usage-metrics disable)
  • Telemetry (telemetry) - OpenTelemetry instrumentation
  • Authorization (authorization) - Cedar policy evaluation
  • Audit (audit) - Request logging
  • Recovery (recovery) - Panic recovery for the proxy chain
  • Header Forward (header-forward) - Forward selected request headers to upstream
  • Validating Webhook (validating-webhook) - Call external validating webhooks
  • Mutating Webhook (mutating-webhook) - Call external mutating webhooks

Execution order (request flow): Middleware is applied in reverse configuration order, and the chain composed for a given workload depends on which features are enabled. See docs/middleware.md for the complete chain, ordering rules, and per-middleware semantics.

Implementation:

  • Interface: pkg/transport/types/transport.go
  • Factory: pkg/runner/middleware.go
  • Documentation: docs/middleware.md

Related concepts: Proxy, Authentication, Authorization

RunConfig

RunConfig is ToolHive's standard configuration format for running MCP servers. It's a JSON/YAML structure that contains everything needed to deploy a workload.

Configuration categories:

  • Execution: image, cmdArgs, transport, name, containerName
  • Networking: host, port, targetPort, targetHost, isolateNetwork, proxyMode
  • Security: permissionProfile, secrets, oidcConfig, authzConfig, trustProxyHeaders
  • Observability: auditConfig, telemetryConfig, debug
  • Customization: envVars, volumes, toolsFilter, toolsOverride, ignoreConfig
  • Organization: group, containerLabels
  • Middleware: middlewareConfigs - Dynamic middleware chain configuration
  • Remote servers: remoteURL, remoteAuthConfig
  • Kubernetes: k8sPodTemplatePatch

See pkg/runner/config.go for complete field reference.

Schema version: v0.1.0 (current)

Portability:

  • Export: thv export <workload> → JSON file
  • Import: thv run --from-config <file>
  • API contract: Format is versioned and stable

Implementation:

  • Definition: pkg/runner/config.go
  • Schema version: pkg/runner/config.go

Related concepts: Workload, Permission Profile, Middleware

Permission Profile

A permission profile defines security boundaries for MCP servers:

Three permission types:

  1. File System Access:

    • read - Mount paths as read-only
    • write - Mount paths as read-write
    • Mount declaration formats: path, host:container, scheme://resource:container-path

  2. Network Access:

    • outbound.insecure_allow_all - Allow all outbound connections
    • outbound.allow_host - Whitelist specific hosts
    • outbound.allow_port - Whitelist specific ports
    • inbound.allow_host - Whitelist inbound connections

  3. Privileged Mode:

    • privileged - Run with host device access (dangerous!)

Built-in profiles:

  • none - No permissions (default)
  • network - Full network access

Implementation:

  • Definition, network permissions, and mount declarations: github.com/stacklok/toolhive-core/permissions (imported as permissions in pkg/runner/)

Related concepts: RunConfig, Workload, Security

Group

A group is a logical collection of MCP servers that share a common purpose or use case.

Use cases:

  • Organizational structure (e.g., "data-analysis" group)
  • Virtual MCP servers (aggregate multiple MCPs into one)
  • Access control (apply policies at group level)
  • Client configuration (configure clients to use groups)

Operations:

  • Create group: thv group create <name> or add workloads with --group flag
  • List all groups: thv group list
  • List workloads in group: thv list --group <name>
  • Remove group: thv group rm <name>

Implementation:

  • Group management: pkg/groups/
  • Workload group field: pkg/runner/config.go

Related concepts: Virtual MCP Server, Workload, Client

Virtual MCP Server

A Virtual MCP Server aggregates multiple MCP servers from a group into a single unified interface with advanced composition and orchestration capabilities.

Purpose:

  • Combine tools from multiple specialized MCP servers into one endpoint
  • Resolve naming conflicts between backends
  • Create composite tools that orchestrate multiple backend operations
  • Provide unified authentication and authorization
  • Enable token exchange and caching for backend authentication

Key capabilities:

  1. Backend Aggregation:

    • Automatically discovers MCPServers, MCPRemoteProxies, and MCPServerEntries from an MCPGroup
    • Aggregates tools, resources, and prompts from all backends
    • Tracks backend health status
    • Handles backend failures gracefully

  2. Conflict Resolution:

    • prefix - Prefix tool names with backend identifier (e.g., github.create_issue)
    • priority - First backend in priority list wins conflicts
    • manual - Explicitly map conflicting tools to specific backends

  3. Tool Filtering and Rewriting:

    • Allow/deny lists for selective tool exposure
    • Tool renaming and description overrides
    • Per-tool backend selection

  4. Composite Tools:

    • Define new tools that call multiple backend tools in sequence
    • Parameter mapping between composite tool and backend tools
    • Response aggregation from multiple backend calls
    • Complex workflow orchestration

  5. Authentication and Security:

    • Incoming: OIDC authentication for clients
    • Outgoing: Automatic token exchange for backend authentication
    • Token caching with configurable TTL and capacity
    • Cedar authorization policies

  6. Backend Types:

    • MCPServer — Container-based: runs as a pod in the cluster
    • MCPRemoteProxy — Proxy-based: deploys a proxy pod that forwards to a remote server
    • MCPServerEntry — Zero-infrastructure: declares a remote endpoint that VirtualMCPServer connects to directly (no pods, services, or deployments)

Example use case:

# Combine GitHub, Slack, and Jira into one "team-tools" virtual server
apiVersion: toolhive.stacklok.dev/v1beta1
kind: VirtualMCPServer
metadata:
  name: team-tools
spec:
  groupRef:
    name: team-backend-group  # Contains github, slack, jira servers
  aggregation:
    conflictResolution: prefix
    tools:
    - filter:
        allow: ["create_issue", "update_issue"]
      toolConfigRef:
        name: jira-tool-config

Deployment:

  • Kubernetes: Via VirtualMCPServer CRD managed by the operator
    • Creates Deployment, Service, and ConfigMap
    • Mounts vmcp configuration as ConfigMap
    • Uses thv-proxyrunner to run vmcp binary
  • CLI: Standalone via the vmcp binary for development or non-Kubernetes environments

Implementation:

  • CRD: cmd/thv-operator/api/v1beta1/virtualmcpserver_types.go
  • Controller: cmd/thv-operator/controllers/virtualmcpserver_controller.go
  • Binary: cmd/vmcp/ (virtual MCP server runtime)

For architecture details, see Virtual MCP Server Architecture.

Related concepts: Group, MCPServer (Kubernetes), Workload, Client

Registry

A registry is a catalog of MCP server definitions with metadata, configuration, and provenance information.

Registry types:

  1. Built-in Registry: Curated by Stacklok

  2. Custom Registry: User-provided

    • Configured via config file
    • JSON file or remote URL
    • Organization-specific servers

  3. Registry API: MCP Registry API endpoint

    • Connect to any MCP Registry API-compliant server
    • ToolHive Registry Server available for enterprise deployments
    • Supports PostgreSQL, multiple registry types, enterprise authentication

Registry entry types:

  • servers - Container-based MCP servers
  • remoteServers - Remote MCP servers (HTTPS endpoints)
  • groups - Predefined groups of servers

Implementation:

  • Registry types: github.com/stacklok/toolhive-core/registry/types
  • Provider abstraction: pkg/registry/provider.go, pkg/registry/factory.go
  • Local provider: pkg/registry/provider_local.go
  • Remote provider: pkg/registry/provider_remote.go
  • API client: pkg/registry/api/client.go
  • API provider: pkg/registry/provider_api.go

Related concepts: Image Metadata, Remote Server Metadata

Session

A session tracks state for MCP client connections, particularly for transports that require session management.

Session types:

  1. SSE Session: For stdio transport with SSE proxy mode

    • Tracks connected SSE clients (multiple clients can connect, but share single stdio connection to container)
    • Message queue per client
    • Endpoint URL generation
    • Note: stdio transport has single connection/session to container

  2. Streamable Session: For stdio transport with streamable proxy mode

    • Tracks Mcp-Session-Id header
    • Request/response correlation
    • Ephemeral sessions for sessionless requests

  3. MCP Session (SessionTypeMCP): For transparent proxy (SSE/Streamable transports when containers speak HTTP natively)

    • Session ID detection from headers
    • Session ID detection from SSE body
    • Minimal state tracking
    • Note: Distinct from stdio transport + SSE/Streamable proxy modes which use SSESession/StreamableSession

Session lifecycle:

  • Created on first request or explicit initialize
  • Tracked via session manager with TTL
  • Cleaned up after inactivity or explicit deletion

Implementation:

  • Session manager: pkg/transport/session/manager.go
  • Session implementations: pkg/transport/session/sse_session.go, streamable_session.go, proxy_session.go
  • Storage abstraction: pkg/transport/session/storage.go

Related concepts: Transport, Proxy

Runtime

A runtime is an abstraction over container orchestration systems. It provides a unified interface for container operations.

Runtime types:

  1. Docker Runtime: Docker Engine API
  2. Podman Runtime: Podman socket API
  3. Colima Runtime: Docker-compatible (uses Docker runtime)
  4. Kubernetes Runtime: Kubernetes API (StatefulSets)

Runtime interface:

  • DeployWorkload - Create and start workload
  • StopWorkload - Stop workload
  • RemoveWorkload - Delete workload
  • ListWorkloads - List all workloads
  • GetWorkloadInfo - Get workload details
  • GetWorkloadLogs - Retrieve logs
  • AttachToWorkload - Attach to stdin/stdout (stdio only)
  • IsWorkloadRunning - Check if running

Runtime detection: Runtimes are registered with a numeric Priority (lower wins) in the runtime registry (pkg/container/runtime/registry.go). Today the registered runtimes are:

  • Docker runtime (Priority: 100, registered in pkg/container/docker/register.go) — covers Docker, Podman, Colima, Rancher Desktop, and OrbStack via per-runtime socket discovery (Podman → Docker → Colima).
  • Kubernetes runtime (Priority: 200, registered in pkg/container/kubernetes/register.go) — activated when running in-cluster (via KUBERNETES_SERVICE_HOST) or when TOOLHIVE_RUNTIME=kubernetes is set.

Implementation:

  • Interface: pkg/container/runtime/types.go
  • Registry: pkg/container/runtime/registry.go
  • Docker SDK factory and socket discovery: pkg/container/docker/sdk/factory.go, pkg/container/docker/sdk/client_unix.go
  • Detection: pkg/container/runtime/types.go

Related concepts: Deployer, Workload, Container

Client

An MCP client is an application that uses MCP servers (e.g., Claude Desktop, IDEs, AI tools).

Client types:

  • claude-code - Claude Code
  • cursor - Cursor editor
  • vscode - VS Code
  • code-server - VS Code Server (VS Code in the browser)
  • cline - Cline extension
  • windsurf - Windsurf editor
  • Many more...

Client configuration: ToolHive can automatically configure clients to use MCP servers:

  • Reads client config files
  • Adds server URLs
  • Updates on workload start/stop
  • Supports multiple config formats

Client discovery and management:

  • Automatic client detection through platform-specific directories
  • Client-specific server configurations
  • Configuration migration support for version upgrades

Implementation:

  • Configuration: pkg/client/config.go
  • Manager: pkg/client/manager.go
  • Discovery: pkg/client/discovery.go

Related concepts: Workload, Group

Skill

A skill is an Agent Skill -- a markdown-based instruction set (SKILL.md) that extends an AI coding assistant's capabilities. Skills are not MCP servers; they provide knowledge and conventions rather than callable tools.

Key characteristics:

  • Defined by a SKILL.md file with YAML frontmatter
  • Distributed as OCI artifacts (tar.gz layers)
  • Can also be installed directly from git repositories
  • Scoped to user (global) or project (local)
  • Support multi-client installation (Claude Code, Cursor, etc.)

Lifecycle:

  1. Discover - Browse skills from registry catalog
  2. Build - Package local SKILL.md into OCI artifact
  3. Publish - Push OCI artifact to remote registry
  4. Install - Pull from registry/git and extract to client skill directory
  5. Uninstall - Remove files and metadata

Implementation:

  • Service interface: pkg/skills/service.go; implementation in pkg/skills/skillsvc/ (entry point pkg/skills/skillsvc/service.go)
  • Types: pkg/skills/types.go
  • Storage: pkg/storage/sqlite/skill_store.go
  • CLI: cmd/thv/app/skill*.go
  • API: pkg/api/v1/skills.go

For architecture details, see Skills System.

Related concepts: Registry, Group, Client

Verbs (Actions)

Deploy

Deploy creates and starts a workload with all its components.

For containers:

  1. Create container with image
  2. Configure networking and ports
  3. Apply permission profile
  4. Start container
  5. Attach streams (if stdio)
  6. Start proxy
  7. Apply middleware
  8. Update state

For remote servers:

  1. Validate remote URL
  2. Start proxy
  3. Configure authentication (if needed)
  4. Apply middleware
  5. Update state

Commands:

  • thv run <image|url> - Deploy and start
  • thv run --from-config <file> - Deploy from config

Implementation:

  • CLI: cmd/thv/app/run.go
  • Workloads: pkg/workloads/manager.go
  • Runtime: pkg/container/runtime/types.go

Related concepts: Workload, Runtime, Transport

Proxy

Proxy forwards MCP traffic between clients and servers while applying middleware.

Proxy types:

  • Transparent: Forwards HTTP without parsing
  • Protocol-specific: Parses and translates messages

Proxy operations:

  1. Start HTTP server on proxy port
  2. Apply middleware chain to requests
  3. Forward to destination (container or remote)
  4. Return responses to clients
  5. Track sessions
  6. Expose telemetry and health endpoints

Implementation:

  • Transparent: pkg/transport/proxy/transparent/transparent_proxy.go
  • SSE: pkg/transport/proxy/httpsse/http_proxy.go
  • Streamable: pkg/transport/proxy/streamable/streamable_proxy.go

Related concepts: Transport, Middleware, Session

Attach

Attach connects to a container's stdin/stdout streams for stdio transport.

Attach process:

  1. Container must be running
  2. Request attach from runtime
  3. Receive stdin (WriteCloser) and stdout (ReadCloser)
  4. Start message processing goroutines
  5. Read JSON-RPC from stdout
  6. Write JSON-RPC to stdin

Framing:

  • Newline-delimited JSON-RPC messages
  • Each message ends with \n

Implementation:

  • Transport: pkg/transport/stdio.go
  • Runtime interface: pkg/container/runtime/types.go

Related concepts: Stdio Transport, Runtime

Parse

Parse extracts structured information from JSON-RPC MCP messages for middleware processing.

Parsing includes:

  • Message type (request, response, notification)
  • Method name (e.g., tools/call, resources/read)
  • Request ID
  • Parameters
  • Resource ID (for resource operations)
  • Arguments (for tool calls)

Parsed data stored in context:

  • Available to downstream middleware
  • Used by authorization for policy evaluation
  • Used by audit for event logging

Implementation:

  • Parser implementation: pkg/mcp/parser.go
  • Middleware: pkg/mcp/middleware.go
  • Tool filtering: pkg/mcp/tool_filter.go

Related concepts: Middleware, Authorization, Audit

Filter and Override

Filter and override controls which tools are available to MCP clients and how they are presented.

Two complementary operations:

  1. Tool Filtering: Whitelist specific tools by name

    • Configured via --tool flags or toolsFilter config
    • Tools not in filter list are hidden from clients
    • Empty filter list means all tools are available

  2. Tool Overriding: Customize tool presentation

    • Configured via toolsOverride map in config file
    • Override tool names and/or descriptions
    • Maps actual tool name to user-visible name/description

Two middlewares for consistency:

  • Tool Filter middleware: Processes outgoing tools/list responses
  • Tool Call Filter middleware: Processes incoming tools/call requests

Both middlewares share the same configuration to ensure clients only see tools they can call, and can only call tools they see.

Configuration:

  • toolsFilter - List of allowed tool names (from --tool flags)
  • toolsOverride - Map from actual name to override (from config file)

Implementation:

  • Middleware factories: pkg/mcp/middleware.go
  • Filter logic: pkg/mcp/tool_filter.go
  • Configuration: pkg/runner/config.go

Related concepts: Middleware, Authorization

Authorize

Authorize evaluates Cedar policies to determine if requests are permitted.

Authorization process:

  1. Get parsed MCP data from context
  2. Get JWT claims from auth middleware
  3. Create Cedar entities (Principal, Action, Resource)
  4. Evaluate Cedar policies
  5. Allow or deny request

Policy language: Cedar policies use:

  • principal - Who is making the request (from JWT)
  • action - What operation (from MCP method)
  • resource - What is being accessed (from MCP resource ID)

Example policy:

permit(
  principal == Client::"user@example.com",
  action == Action::call_tool,
  resource == Tool::"web-search"
);

Implementation:

  • Authz middleware: pkg/authz/middleware.go
  • Policy engine: Cedar (external library)

Related concepts: Middleware, Authentication, Parse

Audit

Audit logs MCP operations for compliance, monitoring, and debugging.

Audit event categories:

  • Connection events (initialization, SSE connections)
  • Operation events (tool calls, resource reads, prompt retrieval)
  • List operations (tools, resources, prompts)
  • Notification events (MCP notifications, ping, logging, completion)
  • Generic fallback events (unrecognized MCP requests, HTTP requests)

See pkg/audit/mcp_events.go for complete list of event types.

Event data:

  • Timestamp, source, outcome
  • Subjects (user, session)
  • Target (endpoint, method, resource)
  • Request/response data (configurable)
  • Duration and metadata

Implementation:

  • Audit middleware: pkg/audit/middleware.go
  • Event types: pkg/audit/event.go, pkg/audit/mcp_events.go
  • Auditor: pkg/audit/auditor.go
  • Config: pkg/audit/config.go

Related concepts: Middleware, Authorization, Parse

Export

Export serializes a workload's RunConfig to a portable JSON file.

Export process:

  1. Load workload state from disk
  2. Read RunConfig
  3. Serialize to JSON with formatting
  4. Write to file or stdout

Exported format:

  • JSON with schema version
  • All configuration fields
  • Permission profile included
  • Middleware configuration included

Commands:

  • thv export <workload> <path> - Export to file

Example: thv export my-server ./my-server-config.json

Implementation:

  • CLI: cmd/thv/app/export.go
  • Serialization: pkg/runner/config.go

Related concepts: RunConfig, Import, State

Import

Import creates a workload from an exported RunConfig file.

Import process:

  1. Read JSON file
  2. Deserialize to RunConfig
  3. Validate schema version
  4. Deploy workload with configuration

Commands:

  • thv run --from-config <file> - Import and run

Implementation:

  • CLI: cmd/thv/app/run.go
  • Deserialization: pkg/runner/config.go

Related concepts: RunConfig, Export, Deploy

Monitor

Monitor watches container health and lifecycle events.

Monitoring includes:

  • Container exit detection
  • Health checks (via MCP ping)
  • Automatic proxy shutdown on container exit

Health checking:

  • Send MCP ping request periodically
  • Check for valid response
  • Shutdown if unhealthy

Implementation:

  • Monitor: pkg/container/runtime/monitor.go
  • Health checker: pkg/healthcheck/healthcheck.go

Related concepts: Workload, Transport, Proxy

Relationships

Workload Composition

graph TB
    Workload[Workload]
    Workload --> RunConfig[RunConfig]
    Workload --> Runtime[Runtime]
    Workload --> Transport[Transport]
    Workload --> State[State]

    RunConfig --> Profile[Permission Profile]
    RunConfig --> Middleware[Middleware Configs]
    RunConfig --> EnvVars[Environment Variables]

    Transport --> Proxy[Proxy]
    Proxy --> Sessions[Sessions]

    style Workload fill:#90caf9
    style RunConfig fill:#e3f2fd
    style Transport fill:#81c784

Request Flow

graph LR
    Client[Client Request] --> Proxy[Proxy]
    Proxy --> Chain[Middleware Chain]
    Chain --> Container[MCP Server]

    style Proxy fill:#81c784
    style Container fill:#ffb74d
    style Chain fill:#fff9c4

Requests pass through a configurable chain of middleware components. See docs/middleware.md for the complete chain and execution order.

Data Hierarchy

Registry
├── Servers (Container-based)
│   └── ImageMetadata
│       ├── image
│       ├── transport
│       ├── envVars
│       └── permissionProfile
├── RemoteServers (Remote)
│   └── RemoteServerMetadata
│       ├── url
│       ├── transport
│       ├── headers
│       └── oauthConfig
└── Groups
    ├── servers (map)
    └── remoteServers (map)

Terminology Quick Reference

TermOne-line Definition
WorkloadA deployed MCP server with all its components
TransportProtocol for MCP client-server communication
ProxyComponent that forwards traffic + applies middleware
MiddlewareComposable request processing layer
RunConfigPortable JSON configuration for workloads
Permission ProfileSecurity policy (filesystem, network, privileges)
GroupLogical collection of related MCP servers
Virtual MCP ServerAggregates multiple MCP servers into unified interface
RegistryCatalog of MCP server definitions
SessionState tracking for MCP connections
RuntimeAbstraction over container systems
ClientApplication that uses MCP servers
SkillAgent Skill (SKILL.md) extending AI assistant capabilities
DeployCreate and start a workload
Proxy (verb)Forward traffic with middleware
AttachConnect to container stdin/stdout
ParseExtract structured info from JSON-RPC
Filter and OverrideControl available tools and how they're presented
AuthorizeEvaluate Cedar policies
AuditLog operations for compliance
ExportSerialize RunConfig to JSON
ImportCreate workload from JSON
MonitorWatch container health