agenterra-0.2.1 is not a library.

🚀 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)

Download the latest release for your platform from Releases

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

agenterra 0.2.1