MCI Schema Reference

This document provides a complete reference for the Model Context Interface (MCI) JSON schema v1. It describes all fields, types, execution configurations, authentication options, and templating syntax supported by the MCI Python adapter.

Overview
Top-Level Schema Structure
Metadata
Tool Definition
Execution Types
Authentication
Templating Syntax
Execution Result Format

Overview

MCI (Model Context Interface) uses a JSON schema to define tools that AI agents can execute. Each tool specifies:

What it does (metadata and description)
What inputs it accepts (JSON Schema)
How to execute it (execution configuration)

The schema is designed to be platform-agnostic, secure (secrets via environment variables), and supports multiple execution types. Schema Version: 1.0

Top-Level Schema Structure

The root MCI context file has three main fields:

Field	Type	Required	Description
`schemaVersion`	string	Required	MCI schema version (e.g., `"1.0"`)
`metadata`	object	Optional	Descriptive metadata about the tool collection
`tools`	array	Required	Array of tool definitions

Example

{
  "schemaVersion": "1.0",
  "metadata": {
    "name": "My API Tools",
    "description": "Tools for interacting with my API",
    "version": "1.0.0",
    "license": "MIT",
    "authors": ["John Doe"]
  },
  "tools": []
}

Metadata

Optional metadata about the tool collection.

Field	Type	Required	Description
`name`	string	Optional	Name of the tool collection
`description`	string	Optional	Description of the tool collection
`version`	string	Optional	Version of the tool collection (e.g., SemVer)
`license`	string	Optional	License identifier (e.g., `"MIT"`, `"Apache-2.0"`)
`authors`	array	Optional	Array of author names

Example

{
  "name": "Weather API Tools",
  "description": "Tools for fetching weather information",
  "version": "1.2.0",
  "license": "MIT",
  "authors": ["Weather Team", "API Team"]
}

Tool Definition

Each tool in the tools array represents a single executable operation.

Field	Type	Required	Description
`name`	string	Required	Unique identifier for the tool
`title`	string	Optional	Human-readable title
`description`	string	Optional	Description of what the tool does
`inputSchema`	object	Optional	JSON Schema describing expected inputs
`execution`	object	Required	Execution configuration (see Execution Types)

Example

{
  "name": "get_weather",
  "title": "Get Weather Information",
  "description": "Fetch current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or zip code"
      },
      "units": {
        "type": "string",
        "enum": ["metric", "imperial"],
        "default": "metric"
      }
    },
    "required": ["location"]
  },
  "execution": {
    "type": "http",
    "method": "GET",
    "url": "https://api.weather.com/v1/current",
    "params": {
      "location": "{{props.location}}",
      "units": "{{props.units}}"
    }
  }
}

Execution Types

MCI supports four execution types: http, cli, file, and text. The type field in the execution object determines which executor is used.

HTTP Execution

Execute HTTP requests to external APIs. Type: "http"

Fields

Field	Type	Required	Default	Description
`type`	string	Required	-	Must be `"http"`
`method`	string	Optional	`"GET"`	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
`url`	string	Required	-	Target URL (supports templating)
`headers`	object	Optional	-	HTTP headers as key-value pairs (supports templating)
`auth`	object	Optional	-	Authentication configuration (see Authentication)
`params`	object	Optional	-	Query parameters as key-value pairs (supports templating)
`body`	object	Optional	-	Request body configuration
`timeout_ms`	integer	Optional	`30000`	Request timeout in milliseconds (must be ≥ 0)
`retries`	object	Optional	-	Retry configuration

Body Configuration

The body field defines the request body:

Field	Type	Required	Description
`type`	string	Required	Body type: `"json"`, `"form"`, or `"raw"`
`content`	object/string	Required	Body content (object for json/form, string for raw)

Retry Configuration

The retries field configures retry behavior:

Field	Type	Required	Default	Description
`attempts`	integer	Optional	`1`	Number of retry attempts (must be ≥ 1)
`backoff_ms`	integer	Optional	`500`	Backoff delay in milliseconds (must be ≥ 0)

Examples

GET Request with Query Parameters

{
  "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

{
  "type": "http",
  "method": "POST",
  "url": "https://api.example.com/reports",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  "body": {
    "type": "json",
    "content": {
      "title": "{{props.title}}",
      "content": "{{props.content}}",
      "timestamp": "{{env.CURRENT_TIMESTAMP}}"
    }
  },
  "timeout_ms": 10000
}

POST Request with Form Data

{
  "type": "http",
  "method": "POST",
  "url": "https://api.example.com/upload",
  "body": {
    "type": "form",
    "content": {
      "filename": "{{props.filename}}",
      "category": "documents"
    }
  }
}

Request with Retry Logic

{
  "type": "http",
  "method": "GET",
  "url": "https://api.example.com/data",
  "retries": {
    "attempts": 3,
    "backoff_ms": 1000
  }
}

CLI Execution

Execute command-line tools and scripts. Type: "cli"

Fields

Field	Type	Required	Default	Description
`type`	string	Required	-	Must be `"cli"`
`command`	string	Required	-	Command to execute
`args`	array	Optional	-	Fixed positional arguments
`flags`	object	Optional	-	Dynamic flags mapped from properties
`cwd`	string	Optional	-	Working directory (supports templating)
`timeout_ms`	integer	Optional	`30000`	Execution timeout in milliseconds (must be ≥ 0)

Flag Configuration

Each flag in the flags object has:

Field	Type	Required	Description
`from`	string	Required	Property path (e.g., `"props.ignore_case"`)
`type`	string	Required	Flag type: `"boolean"` or `"value"`

boolean: Flag is included only if the property is truthy (e.g., -i)
value: Flag is included with the property value (e.g., --file=myfile.txt)

Examples

Basic CLI Command

{
  "type": "cli",
  "command": "grep",
  "args": ["-r", "-n"],
  "flags": {
    "-i": {
      "from": "props.ignore_case",
      "type": "boolean"
    }
  },
  "cwd": "{{props.directory}}",
  "timeout_ms": 8000
}

CLI with Value Flags

{
  "type": "cli",
  "command": "convert",
  "args": ["input.png"],
  "flags": {
    "--resize": {
      "from": "props.size",
      "type": "value"
    },
    "--quality": {
      "from": "props.quality",
      "type": "value"
    }
  },
  "cwd": "/tmp"
}

File Execution

Read and parse file contents with optional templating. Type: "file"

Fields

Field	Type	Required	Default	Description
`type`	string	Required	-	Must be `"file"`
`path`	string	Required	-	File path (supports templating)
`enableTemplating`	boolean	Optional	`true`	Whether to process templates in file content

When enableTemplating is true, the file contents are processed with the full templating engine (basic placeholders, loops, and conditionals).

Examples

Load Template File

{
  "type": "file",
  "path": "./templates/report-{{props.report_id}}.txt",
  "enableTemplating": true
}

Load Raw File

{
  "type": "file",
  "path": "/etc/config/settings.json",
  "enableTemplating": false
}

Text Execution

Return templated text directly. Type: "text"

Fields

Field	Type	Required	Description
`type`	string	Required	Must be `"text"`
`text`	string	Required	Text template (supports templating)

The text is processed with the full templating engine (basic placeholders, loops, and conditionals).

Examples

Simple Message

{
  "type": "text",
  "text": "Hello {{props.username}}! This message was generated on {{env.CURRENT_DATE}}."
}

Report with Conditionals

{
  "type": "text",
  "text": "Report for {{props.username}}\n@if(props.premium)Premium features enabled@else Standard features available @endif"
}

Authentication

HTTP execution supports four authentication types: API Key, Bearer Token, Basic Auth, and OAuth2.

API Key Authentication

Pass an API key in headers or query parameters. Type: "apiKey"

Fields

Field	Type	Required	Description
`type`	string	Required	Must be `"apiKey"`
`in`	string	Required	Where to send the key: `"header"` or `"query"`
`name`	string	Required	Header/query parameter name
`value`	string	Required	API key value (supports templating, typically `{{env.API_KEY}}`)

Examples

API Key in Header

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

API Key in Query Parameter

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

Bearer Token Authentication

Pass a bearer token in the Authorization header. Type: "bearer"

Fields

Field	Type	Required	Description
`type`	string	Required	Must be `"bearer"`
`token`	string	Required	Bearer token (supports templating, typically `{{env.BEARER_TOKEN}}`)

Example

{
  "type": "http",
  "method": "POST",
  "url": "https://api.example.com/reports",
  "auth": {
    "type": "bearer",
    "token": "{{env.BEARER_TOKEN}}"
  },
  "body": {
    "type": "json",
    "content": {
      "title": "{{props.title}}"
    }
  }
}

Basic Authentication

Use HTTP Basic Authentication with username and password. Type: "basic"

Fields

Field	Type	Required	Description
`type`	string	Required	Must be `"basic"`
`username`	string	Required	Username (supports templating, typically `{{env.USERNAME}}`)
`password`	string	Required	Password (supports templating, typically `{{env.PASSWORD}}`)

Example

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

OAuth2 Authentication

Authenticate using OAuth2 client credentials flow. Type: "oauth2"

Fields

Field	Type	Required	Description
`type`	string	Required	Must be `"oauth2"`
`flow`	string	Required	OAuth2 flow type (e.g., `"clientCredentials"`)
`tokenUrl`	string	Required	Token endpoint URL
`clientId`	string	Required	OAuth2 client ID (supports templating)
`clientSecret`	string	Required	OAuth2 client secret (supports templating)
`scopes`	array	Optional	Array of scope strings

Example

{
  "type": "http",
  "method": "GET",
  "url": "https://api.example.com/weather",
  "auth": {
    "type": "oauth2",
    "flow": "clientCredentials",
    "tokenUrl": "https://auth.example.com/token",
    "clientId": "{{env.CLIENT_ID}}",
    "clientSecret": "{{env.CLIENT_SECRET}}",
    "scopes": ["read:weather", "read:forecast"]
  }
}

Templating Syntax

The MCI templating engine supports placeholder substitution, loops, and conditional blocks. Templating is available in:

Execution configurations (URLs, headers, params, body, etc.)
File contents (when enableTemplating: true)
Text execution

Context Structure

The templating engine has access to three contexts:

props: Properties passed to execute() method
env: Environment variables passed to the adapter
input: Alias for props (for backward compatibility)

Basic Placeholders

Replace placeholders with values from the context. Syntax: {{path.to.value}}

Examples

{{props.location}}
{{env.API_KEY}}
{{input.username}}
{{props.user.name}}
{{env.DATABASE_URL}}

In JSON:

{
  "url": "https://api.example.com/users/{{props.user_id}}",
  "headers": {
    "Authorization": "Bearer {{env.ACCESS_TOKEN}}",
    "X-Request-ID": "{{props.request_id}}"
  }
}

For Loops

Iterate a fixed number of times using a range. Syntax: @for(variable in range(start, end))...@endfor

variable: Loop variable name
start: Starting value (inclusive)
end: Ending value (exclusive)

Example

Template:

@for(i in range(0, 3))
Item {{i}}
@endfor

Output:

Item 0
Item 1
Item 2

Foreach Loops

Iterate over arrays or objects from the context. Syntax: @foreach(variable in path.to.collection)...@endforeach

variable: Loop variable name
path.to.collection: Path to an array or object in the context

Array Example

Context:

{
  "props": {
    "items": ["Apple", "Banana", "Cherry"]
  }
}

Template:

@foreach(item in props.items)
- {{item}}
@endforeach

Output:

- Apple
- Banana
- Cherry

Object Example

Context:

{
  "props": {
    "users": [
      { "name": "Alice", "age": 30 },
      { "name": "Bob", "age": 25 }
    ]
  }
}

Template:

@foreach(user in props.users)
Name: {{user.name}}, Age: {{user.age}}
@endforeach

Output:

Name: Alice, Age: 30
Name: Bob, Age: 25

Conditional Blocks

Execute code conditionally based on values in the context. Syntax:

@if(condition)
...
@elseif(condition)
...
@else
...
@endif

Supported Conditions

Truthy check: @if(path.to.value)
Equality: @if(path.to.value == "expected")
Inequality: @if(path.to.value != "unexpected")
Greater than: @if(path.to.value > 10)
Less than: @if(path.to.value < 100)

Examples

Simple Conditional:

@if(props.premium)
You have premium access!
@else
Upgrade to premium for more features.
@endif

Multiple Conditions:

@if(props.status == "active")
Status: Active
@elseif(props.status == "pending")
Status: Pending approval
@else
Status: Inactive
@endif

Numeric Comparison:

@if(props.age > 18)
Adult content available
@else
Restricted content
@endif

Execution Result Format

All tool executions return a consistent result format.

Field	Type	Description
`isError`	boolean	Whether an error occurred during execution
`content`	any	Result content (if successful)
`error`	string	Error message (if `isError: true`)
`metadata`	object	Optional metadata (e.g., HTTP status code, CLI exit code)

Successful Result

{
  "isError": false,
  "content": [
    {
      "type": "text",
      "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
    }
  ],
  "metadata": {
    "status_code": 200,
    "response_time_ms": 245
  }
}

Error Result

{
  "isError": true,
  "error": "HTTP request failed: 404 Not Found",
  "metadata": {
    "status_code": 404
  }
}

Complete Example

Here’s a complete MCI context file demonstrating all features:

{
  "schemaVersion": "1.0",
  "metadata": {
    "name": "Example API Tools",
    "description": "Comprehensive example of MCI features",
    "version": "1.0.0",
    "license": "MIT",
    "authors": ["MCI Team"]
  },
  "tools": [
    {
      "name": "get_weather",
      "title": "Get Weather",
      "description": "Fetch weather with API key auth",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      },
      "execution": {
        "type": "http",
        "method": "GET",
        "url": "https://api.weather.com/v1/current",
        "auth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key",
          "value": "{{env.WEATHER_API_KEY}}"
        },
        "params": {
          "location": "{{props.location}}"
        }
      }
    },
    {
      "name": "search_logs",
      "title": "Search Logs",
      "description": "Search log files with grep",
      "inputSchema": {
        "type": "object",
        "properties": {
          "pattern": { "type": "string" },
          "directory": { "type": "string" }
        },
        "required": ["pattern", "directory"]
      },
      "execution": {
        "type": "cli",
        "command": "grep",
        "args": ["-r", "{{props.pattern}}"],
        "cwd": "{{props.directory}}"
      }
    },
    {
      "name": "load_report",
      "title": "Load Report",
      "description": "Load report template",
      "execution": {
        "type": "file",
        "path": "./templates/report.txt",
        "enableTemplating": true
      }
    },
    {
      "name": "generate_greeting",
      "title": "Generate Greeting",
      "description": "Generate personalized greeting",
      "inputSchema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" }
        },
        "required": ["name"]
      },
      "execution": {
        "type": "text",
        "text": "Hello {{props.name}}! Welcome to MCI."
      }
    }
  ]
}

Getting Started

​MCI Schema Reference

​Table of Contents

​Overview

​Top-Level Schema Structure

​Example

​Metadata

​Example

​Tool Definition

​Example

​Execution Types

​HTTP Execution

​Fields

​Body Configuration

​Retry Configuration

​Examples

​CLI Execution

​Fields

​Flag Configuration

​Examples

​File Execution

​Fields

​Examples

​Text Execution

​Fields

​Examples

​Authentication

​API Key Authentication

​Fields

​Examples

​Bearer Token Authentication

​Fields

​Example

​Basic Authentication

​Fields

​Example

​OAuth2 Authentication

​Fields

​Example

​Templating Syntax

​Context Structure

​Basic Placeholders

​Examples

​For Loops

​Example

​Foreach Loops

​Array Example

​Object Example

​Conditional Blocks

​Supported Conditions

​Examples

​Execution Result Format

​Successful Result

​Error Result

​Complete Example

​See Also

MCI Schema Reference

Table of Contents

Overview

Top-Level Schema Structure

Example

Metadata

Example

Tool Definition

Example

Execution Types

HTTP Execution

Fields

Body Configuration

Retry Configuration

Examples

CLI Execution

Fields

Flag Configuration

Examples

File Execution

Fields

Examples

Text Execution

Fields

Examples

Authentication

API Key Authentication

Fields

Examples

Bearer Token Authentication

Fields

Example

Basic Authentication

Fields

Example

OAuth2 Authentication

Fields

Example

Templating Syntax

Context Structure

Basic Placeholders

Examples

For Loops

Example

Foreach Loops

Array Example

Object Example

Conditional Blocks

Supported Conditions

Examples

Execution Result Format

Successful Result

Error Result

Complete Example

See Also