Skip to main content

​
Introduction to MCI

The Model Context Interface (MCI) is an open-source, platform-agnostic system that revolutionizes how you create and share AI agent tools. By leveraging simple JSON schemas, MCI enables developers to define collections of tools that work universally across programming languages and platforms.

​
What is MCI?

Universal Tool Definition

Define AI tools using standardized JSON schemas that work in every programming language - Python, Node.js, Go, PHP, and beyond.

Multiple Execution Types

Support for HTTP, CLI, File, and Text operations, allowing you to wrap REST APIs, command-line tools, file operations, and templates.

Built-in Authentication

Comprehensive authentication support including API Keys, Bearer Tokens, Basic Auth, and OAuth2 - all configured declaratively.

Advanced Templating

Powerful template engine with environment variables, conditional logic (@if), and iteration (@foreach) for dynamic tool execution.
MCI transforms complex AI tool development into simple JSON configuration. Your entire toolset fits in a single file that’s easy to review, share, and maintain.

​
Why Use MCI?

​
🚀 Simplicity Over Complexity

Unlike complex server-based solutions, MCI tools are declarative JSON files that live directly in your project repository. No servers to maintain, no complex deployments - just clean, readable schemas. 
{
  "name": "greet_user",
  "description": "Generate a personalized greeting",
  "inputSchema": {
    "type": "object",
    "properties": {
      "username": { "type": "string" }
    }
  },
  "execution": {
    "type": "text",
    "text": "Hello, {{props.username}}! Welcome to MCI."
  }
}

​
🔒 Secure by Design

Your entire toolset is transparent and auditable. Every tool is defined in plain JSON that humans and AI can easily review. No black-box servers, no mysterious third-party code accessing your data.

​
🌍 Universal Compatibility

Write once, run everywhere. MCI works with any programming language because it uses operations available in every programming language - HTTP requests, CLI commands, file operations, and text processing.

​
📦 Maximum Flexibility

  • Project-Wide Tools
  • Agent-Specific Tools
  • API Wrappers
  • Mixed Sources
One .mci.json file containing all tools for your entire project.

​
How MCI Differs from MCP

MCI is designed as a supplement to MCP, not a replacement. Each serves different use cases in the AI tooling ecosystem.
AspectMCIMCP
ComplexitySimple JSON filesFull server implementations
Use CaseAPI/CLI wrappers, simple toolsComplex logic, stateful operations
LanguagesUniversal (JSON-based)Language-specific servers
SharingA few filesWhole project
ReviewEasy JSON auditFull codebase review
InfrastructureNone requiredServer infrastructure

​
When to Choose MCI

  • API Wrappers: Wrapping REST APIs with authentication
  • CLI Tool Integration: Executing command-line tools
  • Simple Workflows: File operations and text templating
  • Rapid Prototyping: Quick tool development and iteration
  • Easy Sharing: Tools that need to be shared across teams
  • Security-Conscious: Environments requiring full auditability
  • Complex Logic: Tools requiring sophisticated business logic
  • Stateful Operations: Tools that maintain state across calls
  • Real-time Features: Streaming or real-time data processing
  • Custom Protocols: Non-standard communication requirements
  • Performance Critical: High-throughput, low-latency operations
Pro Tip: Many teams use both! Start with MCI for quick API wrappers and simple tools, then graduate to MCP when you need complex server-side logic.

​
Quick Start Example

See MCI in action with this complete example:
1

Create Your Schema

weather-tools.mci.json
{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": { "type": "string" }
        },
        "required": ["city"]
      },
      "execution": {
        "type": "http",
        "method": "GET",
        "url": "https://api.weather.com/current?q={{props.city}}",
        "auth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key",
          "value": "{{env.WEATHER_API_KEY}}"
        }
      }
    }
  ]
}
2

Use in Python

from mcipy import MCIClient

client = MCIClient(
json_file_path="weather-tools.mci.json",
env_vars={"WEATHER_API_KEY": "your-key"}
)

weather = client.execute("get_weather", {"city": "London"})
print(weather)
3

Share Everywhere

Copy weather-tools.mci.json to any project, any language. It just works!

​
What’s Next: The MCI Ecosystem

MCI is rapidly evolving with an ambitious roadmap to make AI tool development universally accessible.

​
🔄 Language Adapters

Python ✅

Ready Now Full-featured adapter with 92%+ test coverage and comprehensive authentication support.

Node.js 🚧

In Development TypeScript-first implementation with the same simple API. Coming Q1 2024.

Go 📋

Planned High-performance Go implementation for system-level tools and microservices.

PHP 📋

Planned Bringing MCI to the PHP ecosystem for web applications and CMS integrations.

Rust 📋

Planned Ultra-fast Rust adapter for performance-critical applications.

Java 📋

Planned Enterprise-ready Java implementation for large-scale applications.

​
📚 MCI Library

A centralized repository of community-contributed MCI tools:
  • Curated Collections: Pre-built tools for popular APIs (GitHub, Slack, AWS)
  • Quality Assurance: All tools tested and documented
  • Version Management: Semantic versioning for tool schemas
  • Discovery: Search and browse tools by category and functionality

​
📦 MCI Package Manager

Coming soon - a dedicated package manager for MCI tools:
  • Easy Installation
  • Dependency Management
  • Publishing
  • Updates
mci install github-tools slack-integration aws-s3
Install tools from the community library with a single command.

​
🎯 Planned Features

Jinja2 Integration: Replace the current basic template engine with full Jinja2 support for more robust templating options.Include Directive: Add @include("path/to/file.md") to simplify reusing prompt parts and templates.
OAuth2 Flows: Complete OAuth2 implementation with refresh tokens and PKCE support.Dynamic Credentials: Runtime credential resolution and rotation.
Pipeline Tools: Chain multiple tools together in declarative workflows.Conditional Execution: Execute tools based on runtime conditions and previous results.
VS Code Extension: Syntax highlighting, validation, and debugging for MCI schemas.IntelliSense: Auto-completion and inline documentation for schema properties.

​
Getting Started

📖 Schema Reference

Complete documentation of the MCI JSON schema with examples and best practices.

🐍 Python Guide

Comprehensive Python adapter documentation with advanced usage patterns.

💬 Join Community

Connect with other developers, share tools, and get help from the community.
Ready to revolutionize your AI development? MCI makes building powerful AI tools as simple as writing JSON. Start with the quickstart guide and join thousands of developers already using MCI.
⌘I