Execution Types

MCI supports four powerful execution types: Text, File, CLI, and HTTP. Each type is designed for different use cases and provides specific capabilities for tool execution.

Text Execution

Return static or templated text directly. Perfect for simple messages, templates, or computed strings.

Basic Text Tool

{
  "name": "generate_welcome",
  "title": "Welcome Message Generator",
  "description": "Generate a welcome message with current date",
  "inputSchema": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string",
        "description": "User's name"
      }
    },
    "required": ["username"]
  },
  "execution": {
    "type": "text",
    "text": "Welcome {{props.username}}! Today is {{env.CURRENT_DATE}}."
  }
}

Using Text Execution

from datetime import datetime
from mcipy import MCIClient

client = MCIClient(
    json_file_path="tools.mci.json",
    env_vars={"CURRENT_DATE": datetime.now().strftime("%Y-%m-%d")}
)

result = client.execute(
    tool_name="generate_welcome",
    properties={"username": "Alice"}
)

print(result.content)  # "Welcome Alice! Today is 2024-01-15."

Advanced Text Templates

Text execution supports complex templating with conditional logic:

{
  "execution": {
    "type": "text",
    "text": "Hello {{props.username}}!\n{{@if(props.is_premium)}}Welcome back, Premium Member!{{@else}}Consider upgrading to Premium!{{@endif}}\n\nServer: {{env.SERVER_NAME}}"
  }
}

Text execution is ideal for generating reports, email templates, configuration snippets, or any formatted text output.

File Execution

Read and return file contents with optional template substitution. Useful for loading configuration files, templates, or documentation.

Basic File Tool

{
  "name": "load_config",
  "title": "Load Configuration File",
  "description": "Load a configuration file with template substitution",
  "inputSchema": {
    "type": "object",
    "properties": {
      "config_name": {
        "type": "string",
        "description": "Name of the configuration"
      }
    },
    "required": ["config_name"]
  },
  "execution": {
    "type": "file",
    "path": "./configs/{{props.config_name}}.conf",
    "enableTemplating": true
  }
}

Template File Content

Create a file configs/database.conf:

database.conf

host={{env.DB_HOST}}
port={{env.DB_PORT}}
user={{env.DB_USER}}
database={{props.database_name}}
ssl_mode={{env.SSL_MODE}}

Using File Execution

client = MCIClient(
    json_file_path="tools.mci.json",
    env_vars={
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USER": "admin",
        "SSL_MODE": "require"
    }
)

result = client.execute(
    tool_name="load_config",
    properties={
        "config_name": "database",
        "database_name": "production_db"
    }
)

print(result.content)
# Output:
# host=localhost
# port=5432
# user=admin
# database=production_db
# ssl_mode=require

File Execution Options

string

required

Path to the file to load. Supports templating with {{props.name}} and {{env.VAR}}.

boolean

default:"false"

Whether to process template variables in the file content itself.

Ensure file paths are secure and don’t allow directory traversal attacks when using user input in path templates.

CLI Execution

Execute command-line programs and capture their output. Great for running system commands, scripts, or CLI tools.

Basic CLI Tool

{
  "name": "search_files",
  "title": "Search Files with Grep",
  "description": "Search for text patterns in files",
  "inputSchema": {
    "type": "object",
    "properties": {
      "pattern": {
        "type": "string",
        "description": "Search pattern"
      },
      "directory": {
        "type": "string",
        "description": "Directory to search"
      },
      "ignore_case": {
        "type": "boolean",
        "description": "Ignore case when searching"
      }
    },
    "required": ["pattern", "directory"]
  },
  "execution": {
    "type": "cli",
    "command": "grep",
    "args": ["-r", "-n", "{{props.pattern}}"],
    "flags": {
      "-i": {
        "from": "props.ignore_case",
        "type": "boolean"
      }
    },
    "cwd": "{{props.directory}}",
    "timeout_ms": 8000
  }
}

Using CLI Execution

client = MCIClient(json_file_path="tools.mci.json")

result = client.execute(
    tool_name="search_files",
    properties={
        "pattern": "TODO",
        "directory": "./src",
        "ignore_case": True
    }
)

if result.isError:
    print(f"Error: {result.error}")
else:
    # Process grep output
    lines = result.content.strip().split('\n')
    print(f"Found {len(lines)} matches:")
    for line in lines[:5]:  # Show first 5 matches
        print(f"  {line}")

CLI Configuration Options

string

required

The command to execute (e.g., “grep”, “python”, “node”, “git”).

array

Fixed arguments passed to the command. Supports templating.

object

Dynamic flags based on input properties.

Show Flag Types

string

required

"boolean": Include flag only if property is true - "value": Include flag with property value (e.g., --file value)

string

required

Property path to get the value from (e.g., “props.verbose”).

string

Working directory for command execution. Supports templating.

number

default:"30000"

Maximum execution time in milliseconds.

Advanced CLI Examples

Git Operations
Python Script
Docker Commands

{
  "name": "git_status",
  "execution": {
    "type": "cli",
    "command": "git",
    "args": ["status", "--porcelain"],
    "cwd": "{{props.repository_path}}",
    "timeout_ms": 5000
  }
}

{
  "name": "run_script",
  "execution": {
    "type": "cli",
    "command": "python",
    "args": ["{{props.script_path}}"],
    "flags": {
      "--verbose": {
        "from": "props.verbose",
        "type": "boolean"
      },
      "--output": {
        "from": "props.output_file", 
        "type": "value"
      }
    }
  }
}

{
  "name": "docker_ps",
  "execution": {
    "type": "cli", 
    "command": "docker",
    "args": ["ps"],
    "flags": {
      "--all": {
        "from": "props.show_all",
        "type": "boolean"  
      },
      "--format": {
        "from": "props.format",
        "type": "value"
      }
    }
  }
}

HTTP Execution

Make HTTP requests to APIs with full support for authentication, headers, query parameters, and request bodies.

Basic GET Request

{
  "name": "get_weather",
  "title": "Get Weather Information",
  "description": "Fetch current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": ["location"]
  },
  "execution": {
    "type": "http",
    "method": "GET",
    "url": "https://api.example.com/weather",
    "params": {
      "location": "{{props.location}}",
      "units": "metric"
    },
    "headers": {
      "Accept": "application/json"
    },
    "timeout_ms": 5000
  }
}

POST Request with JSON Body

{
  "name": "create_report",
  "title": "Create Report",
  "description": "Create a new report via API",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "content": { "type": "string" }
    },
    "required": ["title", "content"]
  },
  "execution": {
    "type": "http",
    "method": "POST",
    "url": "https://api.example.com/reports",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "type": "json",
      "content": {
        "title": "{{props.title}}",
        "content": "{{props.content}}",
        "timestamp": "{{env.CURRENT_TIMESTAMP}}"
      }
    },
    "timeout_ms": 10000
  }
}

Authentication Options

API Key (Header)
API Key (Query)
Bearer Token
Basic Auth

{
  "execution": {
    "type": "http",
    "method": "GET",
    "url": "https://api.example.com/data",
    "auth": {
      "type": "apiKey",
      "in": "header", 
      "name": "X-API-Key",
      "value": "{{env.API_KEY}}"
    }
  }
}

{
  "execution": {
    "type": "http",
    "method": "GET", 
    "url": "https://api.example.com/data",
    "auth": {
      "type": "apiKey",
      "in": "query",
      "name": "api_key",
      "value": "{{env.API_KEY}}"
    }
  }
}

{
  "execution": {
    "type": "http",
    "method": "POST",
    "url": "https://api.example.com/data",
    "auth": {
      "type": "bearer",
      "token": "{{env.BEARER_TOKEN}}"
    }
  }
}

{
  "execution": {
    "type": "http", 
    "method": "GET",
    "url": "https://api.example.com/data",
    "auth": {
      "type": "basic",
      "username": "{{env.USERNAME}}",
      "password": "{{env.PASSWORD}}"
    }
  }
}

Request Body Types

JSON Body
Form Body
Raw Body

{
  "body": {
    "type": "json",
    "content": {
      "user_id": "{{props.user_id}}",
      "data": "{{props.data}}"
    }
  }
}

{
  "body": {
    "type": "form", 
    "content": {
      "field1": "{{props.value1}}",
      "field2": "{{props.value2}}"
    }
  }
}

{
  "body": {
    "type": "raw",
    "content": "custom={{props.data}}&format=xml"
  }
}

Using HTTP Execution

from datetime import datetime
from mcipy import MCIClient

client = MCIClient(
    json_file_path="api-tools.mci.json",
    env_vars={
        "API_KEY": "your-secret-key",
        "BEARER_TOKEN": "your-bearer-token",
        "CURRENT_TIMESTAMP": datetime.now().isoformat()
    }
)

# Execute GET request
weather_result = client.execute(
    tool_name="get_weather",
    properties={"location": "New York"}
)

if not weather_result.isError:
    import json
    try:
        weather_data = json.loads(weather_result.content)
        print(f"Temperature: {weather_data.get('temperature')}°C")
    except json.JSONDecodeError:
        print("Invalid JSON response")

# Execute POST request
report_result = client.execute(
    tool_name="create_report",
    properties={
        "title": "Q1 Sales Report",
        "content": "Sales increased by 15%"
    }
)

if not report_result.isError:
    print(f"Report created: {report_result.content}")

HTTP Configuration Options

string

required

HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

string

required

Target URL. Supports templating for dynamic URLs.

object

HTTP headers as key-value pairs. Supports templating.

object

Query parameters as key-value pairs. Supports templating.

object

Request body configuration.

Show Body Types

object

JSON body with automatic Content-Type header.

object

Form-encoded body with appropriate Content-Type.

string

Raw string body for custom formats.

object

Authentication configuration.

number

default:"30000"

Request timeout in milliseconds.

Execution Type Comparison

Text Execution

Best for: Templates, reports, messagesPros: Simple, fast, no dependenciesCons: Static output only

File Execution

Best for: Configs, templates, documentation Pros: Supports templating, file system access Cons: Requires file system access

CLI Execution

Best for: System commands, scripts, tools Pros: Access to system utilities, flexible Cons: Platform-dependent, security considerations

HTTP Execution

Best for: API integration, web servicesPros: Rich protocol support, authenticationCons: Network dependency, API rate limits

Best Practices

Security

CLI Execution: Validate and sanitize all user/LLM inputs to prevent command injection attacks/errors.

File Execution: Use absolute paths or restrict file access to prevent directory traversal.

HTTP Execution: Always use HTTPS for sensitive data and store API keys in environment variables.

Performance

Set appropriate timeouts for each execution type to prevent tools from hanging indefinitely.

Use caching for expensive operations, especially for HTTP requests that return static data.

Error Handling

Always check result.isError before processing tool outputs, and provide meaningful error messages to users.

Getting Started

Learn more

Execution Types

Execution Types

Text Execution

Basic Text Tool

Using Text Execution

Advanced Text Templates

File Execution

Basic File Tool

Template File Content

Using File Execution

File Execution Options

CLI Execution

Basic CLI Tool

Using CLI Execution

CLI Configuration Options

Advanced CLI Examples

HTTP Execution

Basic GET Request

POST Request with JSON Body

Authentication Options

Request Body Types

Using HTTP Execution

HTTP Configuration Options

Execution Type Comparison

Text Execution

File Execution

CLI Execution

HTTP Execution

Best Practices

Security

Performance

Error Handling

Next Steps

Advanced Features

API Reference

​Execution Types

​Text Execution

​Basic Text Tool

​Using Text Execution

​Advanced Text Templates

​File Execution

​Basic File Tool

​Template File Content

​Using File Execution

​File Execution Options

​CLI Execution

​Basic CLI Tool

​Using CLI Execution

​CLI Configuration Options

​Advanced CLI Examples

​HTTP Execution

​Basic GET Request

​POST Request with JSON Body

​Authentication Options

​Request Body Types

​Using HTTP Execution

​HTTP Configuration Options

​Execution Type Comparison

Text Execution

File Execution

CLI Execution

HTTP Execution

​Best Practices

​Security

​Performance

​Error Handling

​Next Steps

Advanced Features

API Reference

Execution Types

Text Execution

Basic Text Tool

Using Text Execution

Advanced Text Templates

File Execution

Basic File Tool

Template File Content

Using File Execution

File Execution Options

CLI Execution

Basic CLI Tool

Using CLI Execution

CLI Configuration Options

Advanced CLI Examples

HTTP Execution

Basic GET Request

POST Request with JSON Body

Authentication Options

Request Body Types

Using HTTP Execution

HTTP Configuration Options

Execution Type Comparison

Best Practices

Security

Performance

Error Handling

Next Steps