MCP Scripts Specification | GitHub Agentic Workflows
Skip to main content MCP Scripts Specification Version : 1.1.0 Status : Draft Specification Latest Version : mcp-scripts-specification JSON Schema : mcp-scripts-config.schema.json Editor : GitHub Agentic Workflows Team Abstract Section titled “Abstract” This specification defines MCP Scripts, an extension to the MCP Gateway that enables inline definition of custom MCP tools directly in workflow frontmatter using JavaScript, shell scripts, Python, or Go.
MCP Scripts provides ephemeral, containerized tool execution with controlled secret access through a standardized MCP tools interface. Tool execution is stateless and session-independent, providing process isolation and security boundaries for custom functionality. Status of This Document Section titled “Status of This Document” This section describes the status of this document at the time of publication. This is a draft specification and may be updated, replaced, or made obsolete by other documents at any time.
This document is governed by the GitHub Agentic Workflows project specifications process. Table of Contents Section titled “Table of Contents” Introduction Conformance Architecture Configuration Format Tool Execution Language Support Security Model Large Output Handling Integration with MCP Gateway Safeguards Norms Compliance Testing Sync Notes 1. Introduction Section titled “1. Introduction” 1.1 Purpose Section titled “1.1 Purpose” MCP Scripts enables developers to define custom MCP tools inline in workflow frontmatter without requiring external MCP server implementations.
It solves the following problems: Rapid Tool Development : Define tools directly in workflow without creating separate services Secret Isolation : Provide controlled access to secrets through explicit environment variable mapping Language Flexibility : Support multiple implementation languages (JavaScript, Shell, Python, Go) Process Isolation : Execute tools in containerized environments with security boundaries Ephemeral Execution : Stateless tool invocations without session management overhead 1.2 Scope Section titled “1.2 Scope” This specification covers: MCP Scripts configuration format in workflow frontmatter Tool definition structure and validation rules Supported implementation languages and their execution models Secret access and environment variable handling Tool input/output schemas and validation Large output handling mechanisms Integration with MCP Gateway infrastructure This specification does NOT cover: MCP Gateway core protocol (see MCP Gateway Specification ) MCP protocol semantics (see Model Context Protocol Specification ) External MCP server implementations Agent client implementations UI or interactive features 1.3 Design Goals Section titled “1.3 Design Goals” MCP Scripts is designed for: Developer Convenience : Minimal configuration overhead for common tool patterns Security by Default : Explicit secret access, process isolation, output sanitization Stateless Execution : No session management, each invocation is independent Language Agnostic : Support multiple implementation languages with consistent behavior Gateway Integration : Seamless integration with MCP Gateway as configuration extension 1.4 Relationship to MCP Gateway Section titled “1.4 Relationship to MCP Gateway” MCP Scripts is an extension to the MCP Gateway Specification.
The MCP Gateway allows additional fields in its configuration format, and MCP Scripts leverages this extensibility to provide inline tool definitions. MCP Scripts configurations are processed during workflow compilation and translated into MCP server configurations that are gatewayed by the MCP Gateway infrastructure. 2. Conformance Section titled “2. Conformance” 2.1 Conformance Classes Section titled “2.1 Conformance Classes” A conforming MCP Scripts implementation is one that satisfies all MUST, REQUIRED, and SHALL requirements in this specification.
A partially conforming MCP Scripts implementation is one that satisfies all MUST requirements for JavaScript tools but MAY lack support for Shell, Python, or Go implementations. 2.2 Requirements Notation Section titled “2.2 Requirements Notation” The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 .
2.3 Compliance Levels Section titled “2.3 Compliance Levels” Implementations MUST support: Level 1 (Required) : JavaScript tools, basic input validation, HTTP transport Level 2 (Standard) : Shell and Python tools, timeout handling, secret isolation Level 3 (Complete) : Go tools, large output handling, all optional features 3. Architecture Section titled “3. Architecture” 3.1 System Architecture Section titled “3.1 System Architecture” ┌─────────────────────────────────────────────────────────┐ │ Workflow Frontmatter │ │ (mcp-scripts:) │ └──────────────────────┬──────────────────────────────────┘ │ Compilation ▼ ┌─────────────────────────────────────────────────────────┐ │ MCP Scripts Server │ │ ┌───────────────────────────────────────────────────┐ │ │ │ Tool Registry & Configuration Loader │ │ │ └───────────────────────────────────────────────────┘ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ HTTP MCP Server (JSON-RPC over HTTP) │ │ │ └───────────────────────────────────────────────────┘ │ └──────┬──────────────┬──────────────┬───────────────────┘ │ │ │ │ JavaScript │ Shell │ Python/Go ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ In- │ │ Docker │ │ Docker │ │ Process │ │ Container│ │ Container│ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ 3.2 Execution Model Section titled “3.2 Execution Model” MCP Scripts operates with the following execution model: Compilation Phase : Workflow frontmatter is parsed and validated Server Startup : MCP Scripts server starts with tool configurations Tool Registration : Each tool is registered with the MCP server Invocation : Agent invokes tool via MCP protocol (HTTP transport) Execution : Tool handler executes in appropriate runtime environment Response : Result is returned via JSON-RPC response Cleanup : Ephemeral resources are cleaned up after invocation 3.2.1 Operations Ordering (Normative Cross-Link) Section titled “3.2.1 Operations Ordering (Normative Cross-Link)” Implementations MUST preserve the invocation operation ordering defined in §5.1.1.
Architecture changes in this section MUST NOT weaken or reorder the §5.1.1 sequence. 3.3 Transport Model Section titled “3.3 Transport Model” MCP Scripts MUST use HTTP transport for MCP communication. The transport architecture is: Client → Gateway : HTTP with JSON-RPC payloads Gateway → MCP Scripts Server : HTTP with JSON-RPC payloads MCP Scripts
The rest of this page is on the live site.