ToolHive Documentation

The VirtualMCPCompositeToolDefinition supports advanced workflow orchestration features including:

Completed Features

• DAG Execution: Steps are executed in parallel where possible based on a dependency graph.
• Step Output Access: You can reference outputs from previous steps within templates.
• Advanced Retry Policies: Supports exponential backoff with configurable retry counts and delays.
• Workflow State Management: Uses in-memory state tracking with a pluggable backend interface.
• Advanced Error Handling: Supports per-step and workflow-level strategies such as abort, continue, or retry.
• Workflow Timeouts: Configurable timeouts can be set at both the workflow and individual step levels.
• Conditional Execution: Steps can be skipped based on template conditions.

Planned Features (Future Releases)

• Distributed State Store: Support for Redis or Database backends for multi-instance deployments.
• Step Caching: Caching step results based on specific cache keys.
• Output Transformation: Advanced transformations using templates.
• Workflow Resumption: Ability to resume workflows after a system restart.

The ToolHive architecture documentation is organized into several functional layers to help different user roles understand the platform.

Documentation Structure

• Core Understanding: High-level overview, core concepts (nouns and verbs), and deployment modes (Local vs. Kubernetes).
• Communication Layer: Details on transport types (stdio, SSE, streamable-http) and the middleware system.
• Configuration & Security: Information on RunConfig, permission profiles, and secrets management (encrypted, 1password, environment).
• Distribution & Organization: Documentation on the Registry system and logical Groups.
• Runtime Management: Lifecycle management for workloads, the Kubernetes Operator (CRDs), Virtual MCP (vMCP) aggregation, and Auth Server storage.
• Agent Skills: The lifecycle and distribution of Agent Skills and the Plugins system.

Navigation by Role

• Platform Developers: Start with 00-overview.md $\rightarrow$ 02-core-concepts.md $\rightarrow$ 01-deployment-modes.md.
• Middleware Developers: Focus on 03-transport-architecture.md and the central middleware.md guide.
• Operators: Start with 01-deployment-modes.md $\rightarrow$ 09-operator-architecture.md.
• Contributors: It is recommended to review all documents in sequential order (00 through 16).

The ToolHive skills system implements several security layers to ensure safe execution and installation:

Archive Extraction Safety

• Size Limits: Maximum 500MB total decompressed size, 100MB per file, and 1000 files max.
• Symlink/Hardlink Rejection: Archives containing symlinks or hardlinks are rejected.
• Path Traversal Prevention: Rejects archives with .. components or absolute paths.
• Permission Sanitization: Strips setuid/setgid/sticky bits; permissions are capped at 0644.
• Validation: Performs pre-extraction parent path checks and post-extraction filesystem anomaly scans.

Path and Supply Chain Protection

• Dangerous Path Protection: Refuses to remove filesystem roots, home directories, or shallow paths (< 4 components).
• OCI Naming: The OCI artifact skill name must match the last path component of the OCI repository.
• Git Security: Git authentication is host-scoped (e.g., GitHub tokens are only sent to github.com). SSRF prevention rejects localhost and private IPs in git references.

Input Validation

• Skill Names: Must be 2-64 characters, lowercase alphanumeric plus hyphens, with no consecutive hyphens.
• Limits: Maximum 64KB for frontmatter and 100 dependencies per skill.

The 2026-07-28 revision of the Model Context Protocol (MCP) replaces server-initiated requests (like sampling/createMessage) with the Multi Round-Trip Requests (MRTR) pattern.

In this pattern, a server cannot initiate a request to a client. Instead, if a server cannot complete a request (specifically for tools/call, resources/read, or prompts/get), it must respond with a Result where the resultType is "input_required".

The MRTR Workflow:

1. Initial Request: The client sends a request (e.g., tools/call).
2. Input Required Response: The server responds with an InputRequiredResult containing inputRequests (the data needed) and an optional requestState (an opaque string).
3. Client Fulfillment: The client gathers the required inputs.
4. Retry: The client sends a new JSON-RPC request with a different id than the original. This retry must include the inputResponses and the echoed requestState from the server.

Key Constraints:

• Independence: Each round is a fully independent request; any server replica can handle any round.
• Capability Gating: Servers MUST NOT send inputRequests for capabilities that the client has not explicitly declared in its clientCapabilities.
• Security: The requestState is considered attacker-controlled input. Servers must treat it as untrusted and should use cryptographic binding (like HMAC/AEAD) if the state influences authorization or business logic.

// schema/draft/schema.ts
export type InputRequest = CreateMessageRequest | ListRootsRequest | ElicitRequest;
export interface InputRequests { [key: string]: InputRequest; }
export interface InputRequiredResult extends Result {
  inputRequests?: InputRequests;
  requestState?: string;   // opaque to the client
}
export interface InputResponseRequestParams extends RequestParams {
  inputResponses?: InputResponses;
  requestState?: string;
}