🚀 Agenterra: Model Context Protocol Generator

Generate production-ready MCP (Model Context Protocol) servers and clients from OpenAPI specs with minimal configuration.

Agenterra transforms your OpenAPI specifications into fully-functional MCP servers and clients with type-safe Rust code, ready for integration with AI tools and workflows. Perfect for:

• AI/ML Engineers 🤖 - Quickly expose APIs for LLM tool use
• API Developers 🛠️ - Generate production-ready MCP servers from existing OpenAPI specs
• FinTech & Data Teams 📊 - Build compliant financial data APIs with built-in validation
• Startups & Enterprises 🚀 - Accelerate development of AI-powered applications

✨ Features

• ⚡ Blazing Fast - Built with Rust for maximum performance and safety
• 🔌 OpenAPI 3.0+ Support - Seamless integration with existing API specifications
• 🦀 Type-Safe Rust - Generate idiomatic, production-ready Rust code
• 🎨 Template-Based - Customize every aspect with Tera templates
• 🔍 Built-in Validation - Automatic OpenAPI schema validation
• 🚀 Production Ready - Includes logging, error handling, and configuration out of the box
• 🔌 MCP Protocol Support - Full compatibility with Model Context Protocol
• 💾 SQLite Resource Caching - Built-in resource caching with connection pooling for MCP clients
• 🛡️ Client Permission Management - Interactive tool permission prompting with persistent preferences
• 📦 Binary Distribution - Easy installation and deployment
• 📚 Embedded Templates - Templates included in binary for cargo install support

🔒 Security

Agenterra generates code with security features built-in. Every generated server and client includes comprehensive protection against modern attack vectors.

Key Security Features:

• Input Validation: Protection against SQL injection, command injection, and prompt injection
• Unicode Security: Detection of zero-width characters and emoji-based attacks
• Transport Security: Secure SSE mode with URL validation
• Resource Protection: Size limits and rate limiting to prevent DoS

See Security Features for complete details.

🚀 Quick Start

Prerequisites

• Rust 1.86.0+

Method 1: Build & Run from Source

# Clone the repository
git clone https://github.com/clafollett/agenterra.git
cd agenterra

# Generate MCP server from a local file without install:
cargo run -- scaffold mcp server --schema-path ./tests/fixtures/openapi/petstore.openapi.v3.json --project-name petstore-server --base-url https://petstore3.swagger.io

# Generate MCP server from a remote URL without install:
cargo run -- scaffold mcp server --schema-path https://petstore3.swagger.io/api/v3/openapi.json --project-name petstore-remote

# Generate MCP client without install:
cargo run -- scaffold mcp client --project-name petstore-client

# Or install the CLI
cargo install --path .

# Generate your MCP server from a local file
agenterra scaffold mcp server --schema-path ./tests/fixtures/openapi/petstore.openapi.v3.json --project-name petstore-server --base-url https://petstore3.swagger.io

# Generate MCP server from a remote URL
agenterra scaffold mcp server --schema-path https://petstore3.swagger.io/api/v3/openapi.json --project-name petstore-remote

# Generate MCP client
agenterra scaffold mcp client --project-name petstore-client

Note: After the single-crate refactor, you can now install directly from the project root with cargo install --path .

Method 2: Install from Git

# Install latest version
cargo install --git https://github.com/clafollett/agenterra.git agenterra

# Install specific version. Example: v0.1.0
cargo install --git https://github.com/clafollett/agenterra.git --tag v<VERSION> agenterra

Method 3: From Pre-built Binary (Coming soon)

1. Download the latest release for your platform from Releases
2. Make it executable and run:

   chmod +x agenterra
   
   # Generate your MCP server from a local file
   ./agenterra scaffold mcp server --schema-path ./tests/fixtures/openapi/petstore.openapi.v3.json --project-name petstore-server --base-url https://petstore3.swagger.io
   
   # Generate MCP server from a remote URL
   ./agenterra scaffold mcp server --schema-path https://petstore3.swagger.io/api/v3/openapi.json --project-name petstore-remote
   
   # Generate MCP client
   ./agenterra scaffold mcp client --project-name petstore-client
   

🔌 Integrating with MCP Clients

VS Code Integration

Add this to your VS Code settings (File > Preferences > Settings > Open Settings JSON):

{
  "mcp": {
    "servers": {
      "petstore": {
        "command": "cargo",
        "args": ["run", "--manifest-path", "/path/to/petstore-server/Cargo.toml"]
      }
    }
  }
}

Cursor Integration

Add this to your Cursor settings (File > Preferences > Settings > Extensions > MCP):

{
  "mcpServers": {
    "petstore": {
      "command": "cargo",
      "args": ["run", "--manifest-path", "/path/to/petstore-server/Cargo.toml"],
      "disabled": false,
      "alwaysAllowed": ["listPets", "showPetById"],
      "disabledTools": ["deletePet"]
    }
  }
}

🕵️‍♂️ Testing with MCP Inspector

Test your MCP server with the MCP Inspector:

# Test STDIO mode (default)
npx @modelcontextprotocol/inspector cargo run --manifest-path=/path/to/petstore-server/Cargo.toml

# Test SSE mode
npx @modelcontextprotocol/inspector cargo run --manifest-path=/path/to/petstore-server/Cargo.toml -- --transport sse

# Or install globally
npm install -g @modelcontextprotocol/inspector
modelcontextprotocol-inspector cargo run --manifest-path=/path/to/petstore-server/Cargo.toml

Testing SSE Endpoints

When running in SSE mode, the server exposes HTTP endpoints:

# Start server in SSE mode
cargo run -- --transport sse --sse-addr 127.0.0.1:8080

# Test SSE endpoint with curl
curl -N -H "Accept: text/event-stream" http://localhost:8080/sse

# Send MCP messages via POST
curl -X POST http://localhost:8080/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

⚡ Best Practices

Agenterra is designed to scaffold a well-structured MCP servers from OpenAPI specs. This is a great starting point, not necessarily a Best Practice. Wrapping an OpenAPI spec under an MCP facade is convenient, but not always the “proper” way to build MCPs. For robust, agent-friendly tools, consider how your server can best expose business logic, aggregate data, and provide clear, useful tool contracts.

Considerations:

• Treat the generated code as a foundation to extend and customize.
• Don't assume a 1:1 mapping of OpenAPI endpoints to MCP tools is ideal; you may want to aggregate multiple API calls into a single tool, or refactor handlers for advanced logic.
• Use the scaffold to rapidly stub out endpoints, then iterate and enhance as needed.

🤔 Why Agenterra?

Postman now offers robust support for the Model Context Protocol (MCP), including:

• MCP client and server features
• Code generation
• A catalog of hosted, discoverable MCP endpoints
• Visual agent-building and cloud collaboration

When should you use Agenterra?

• Offline, air-gapped, or regulated environments where cloud-based tools aren't an option
• Rust-first, codegen-centric workflows: Generate type-safe, production-grade Rust MCP servers from OpenAPI specs, ready for CI/CD and self-hosting
• Full template control: Tweak every line of generated code, use custom templates, and integrate with your own infra
• CLI-first automation: Perfect for embedding in build scripts and automated workflows

When should you use Postman?

• Visual design, rapid prototyping, and cloud collaboration
• Building, testing, and deploying MCP agents with a GUI
• Discovering and consuming public MCP endpoints

Summary:

• Use Postman for visual, collaborative, and cloud-first agent development
• Use Agenterra for local, reproducible, code-first MCP server generation with maximum control and zero cloud dependencies

🏛️ Architecture

Agenterra is built for extensibility, automation, and code quality. Here's how the core pieces fit together:

Core Modules:

• openapi: Loads and validates OpenAPI specs (YAML/JSON, local or URL)
• generator: Orchestrates code generation from the parsed OpenAPI model
• template: Handles Tera-based templates for idiomatic Rust code
• cli: Command-line interface for scaffolding, configuration, and workflow

Code Generation Flow:

OpenAPI Spec (local file or URL)
         │
         ▼
   [openapi module]
         │
         ▼
   [generator module]
         │
         ▼
   [template module]
         │
         ▼
Generated Rust MCP Server (Axum, etc.)

• The generated servers support both STDIO and SSE (Server-Sent Events) transports for MCP protocol
• All code is idiomatic Rust, ready for further customization and production deployment

🚀 Transport Configuration

Generated servers and clients support multiple transport modes:

Server Transport Options

# STDIO mode (default) - for direct process communication
./my-server

# SSE mode - for HTTP-based communication
./my-server --transport sse --sse-addr 127.0.0.1:8080

# With custom keep-alive interval
./my-server --transport sse --sse-addr 0.0.0.0:9000 --sse-keep-alive 60

# Configuration via command-line arguments only
./my-server --transport sse --sse-addr 127.0.0.1:8080

Client Transport Options

# STDIO mode (default) - connects to server process
./my-client --server /path/to/server

# SSE mode - connects to HTTP endpoint
./my-client --transport sse --sse-url http://localhost:8080

💾 Resource Caching

Generated MCP clients include a sophisticated SQLite-powered resource caching system:

Features:

• Connection Pooling - r2d2 connection pool for concurrent access
• TTL Support - Configurable time-to-live for cache entries
• Analytics - Built-in cache hit/miss tracking and performance metrics
• ACID Transactions - Database integrity with rollback support
• Auto-cleanup - Configurable expired resource cleanup

Configuration Options:

// Resource cache configuration
let cache_config = CacheConfig {
    default_ttl: Duration::from_secs(3600),
    max_size_mb: 100,
    auto_cleanup: true,
};

// Database connection configuration (separate from cache config)
let db_config = DatabaseConfig {
    database_path: PathBuf::from("cache.db"),
    pool_max_connections: 10,
    pool_connection_timeout: Some(Duration::from_secs(5)),
    pool_max_lifetime: Some(Duration::from_secs(300)),
};

🤝 Contributing

We welcome contributions from the community! To keep Agenterra high-quality and maintainable, please follow these guidelines:

• Fork & Clone: Fork the repo and clone your fork locally.
• Branch Naming: Use the convention <type>/issue-<number>/<description> (e.g., docs/issue-57/update-readme).
• Pull Requests:
  • All PRs require review.
  • All tests must pass (cargo test and integration tests).
  • Code coverage must not decrease.
  • Update documentation for any user-facing or API changes.
• Testing:
  • Add or update unit and integration tests for all new features or bugfixes.
  • Run: cargo test --test e2e_mcp_test
• Docs:
  • Update relevant docs and add examples for new features.
  • Document any new patterns or conventions.
• CI/CD:
  • Ensure your branch passes all checks before requesting review.

For more details, see CONTRIBUTING.md if available.

🛠️ Developer Workflow

Here's how to work productively with Agenterra as a contributor or advanced user:

🧪 Running Tests

• Unit & Integration Tests:
  • Run all tests: cargo test
  • Run integration tests (all templates with OpenAPI specs):

    cargo test --test e2e_mcp_test
    

• Test Location: See tests/e2e_mcp_test.rs for integration coverage.
• Test-First Principle: Add failing tests before implementing new features or bugfixes.

🏗️ Building

• Standard build:

  cargo build --release
  

🧩 Custom Templates

• See docs/TEMPLATES.md for template development
• Add templates under templates/ directory

📚 Examples & Configuration

Basic Example: Petstore API

# Download the Petstore OpenAPI spec
curl -o petstore.json https://petstore3.swagger.io/api/v3/openapi.json

# Generate the MCP server
agenterra scaffold mcp server --schema-path petstore.json --project-name petstore-server

# Generate the MCP client
agenterra scaffold mcp client --project-name petstore-client

# Build and run the server
cd petstore-server
cargo run

Configuration Options

Agenterra is configured through command-line arguments. By default, projects are created in the current directory (like cargo new):

# Generate MCP server (creates ./my_server/)
agenterra scaffold mcp server --schema-path your_api.json --project-name my_server

# Generate MCP client (creates ./my_client/)
agenterra scaffold mcp client --project-name my_client

# Specify a parent directory with --output-dir
agenterra scaffold mcp server --schema-path api.json --project-name my_server --output-dir ~/projects
# Creates: ~/projects/my_server/

Environment Variables:

• AGENTERRA_OUTPUT_DIR - Default parent directory for generated projects
• AGENTERRA_TEMPLATE_DIR - Custom template directory location

Templates

Agenterra uses Tera templates for code generation. Templates are embedded in the binary for easy distribution and can be managed using the built-in template commands.

Built-in Server Templates:

• rust - Rust MCP server using Axum web framework

Built-in Client Templates:

• rust - Rust MCP client with REPL interface and SQLite resource caching

Managing Templates:

# List all available embedded templates
agenterra templates list

# Show detailed information about a specific template
agenterra templates info mcp/server/rust

# Export all templates to a directory
agenterra templates export ./my-templates

# Export a single template
agenterra templates export ./my-templates --template mcp/server/rust

Custom Templates:

• Use exported templates as a starting point for customization
• Specify custom template directory with --template-dir when scaffolding
• Create templates under templates/mcp/server/ or templates/mcp/client/
• Details: See docs/TEMPLATES.md

Project Structure: Each generated project includes a detailed README.md with template-specific project structure documentation, usage examples, and configuration options.

📄 License

MIT License - see LICENSE for details.

🔗 Related Projects

• MCP Protocol - Model Context Protocol specification
• RMCP - Rust MCP implementation
• Axum - Web framework for Rust
• Tera - Template engine for Rust