DEV Community: Shuttle

Shuttle MCP Server - Deploy Your App with a Prompt

Shuttle — Wed, 08 Oct 2025 14:25:35 +0000

AI agents are changing how we build software, and the Model Context Protocol (MCP) is at the heart of this shift. MCP lets AI agents connect with external tools and APIs - kind of like giving your AI assistant hands to actually do things instead of just talking about them.

We've updated our Shuttle MCP server, and it's a proper workflow upgrade. Here's what's new.

What Does the Shuttle MCP do?

The Shuttle MCP server gives AI agents direct access to Shuttle's platform and documentation. Your AI agent can now:

Search through Shuttle documentation to understand how things work, ensuring you have the latest information
Deploy projects directly to Shuttle
List all your Shuttle projects
Get detailed information about specific projects
View deployment logs in real-time for debugging

Instead of copy-pasting commands and switching between your terminal, documentation, and AI chat, your agent handles the entire workflow.

The Problem With the Previous Version

The first version of our MCP server worked well for most users. The tools were functional, AI agents could call them, and they'd return the expected data for common workflows.

But we noticed struggles in edge cases. When dealing with unusual deployment configurations or error states, agents would sometimes call the wrong tool or miss required parameters. When something failed in these scenarios, they'd get stuck because error messages didn't provide enough context to self-correct.

We realized the problem wasn't the tools themselves as they were powerful enough - it was how we presented them to the agents. In edge cases, agents didn't have enough guidance to understand when or how to use each tool. We'd built powerful functionality but needed to be documented better for AI agents to understand.

What's New in This Version

The updated server doesn't add flashy new features - it makes the existing ones actually work the way they should. The Agents now have much higher success rates, and even when things go wrong, they know how to recover and fix issues on their own.

We've enhanced how AI agents understand Shuttle. Each MCP tool includes detailed instructions that help agents understand not just what a tool does, but when and how to use it.

We've also reworked error handling. When something goes wrong now, the error messages are designed for AI agents - they provide enough context and guidance for the agent to understand what happened and how to fix it. Instead of getting stuck, agents can self-correct and try again with a high chance of success.

With this, your AI agent works faster and makes fewer mistakes. It understands deployment workflows and can troubleshoot issues on its own.

What We Learned About Building MCP Servers

Building MCP tools isn't just about writing the code that exposes functionality. It's about documentation and context - specifically, documentation written for AI models rather than humans.

A powerful tool isn't very efficient if the agent doesn't know when and how to use it. You need to provide condensed, structured context that models can actually parse and understand. Otherwise, you're handing your agent a toolbox without labels on any of the tools leaving the agent to guess what to do with it.

This means thinking differently about how you write tool descriptions, parameter explanations, and error messages. Every piece of text needs to be optimized for model comprehension, not human readability.

If you're building your own MCP server, spend as much time on how you describe your tools as you do on implementing them. The quality of that documentation directly determines whether AI agents can actually use what you've built.

Real-World Benefits

Here's where this gets practical. You can now tell your AI agent "Deploy my Shuttle App" and it handles everything using the Shuttle MCP server:

Creates a project for you if you don't have one already
Deploys the project to the cloud
Handles edge cases
Catches and fixes common deployment issues automatically

The entire workflow - from project creation to a live deployment - happens through your AI agent.

We tested this with Claude Sonnet 4.5 to build a complete Rust API from scratch, you can see the MCP server in action. See the full walkthrough here.

Getting Started

Prerequisites

First, you'll need the latest Shuttle CLI. If you don't have it installed:

Linux/macOS:

curl -sSfL https://www.shuttle.dev/install | bash

Windows (PowerShell):

iwr https://www.shuttle.dev/install-win | iex

If you already have Shuttle installed, upgrade to the latest version:

shuttle upgrade

Configuring the MCP Server

After installing the CLI, configure the MCP server in your IDE or MCP client. For Cursor, add this to your mcp.json:

{
  "mcpServers": {
    "Shuttle": {
      "command": "shuttle",
      "args": ["mcp", "start"]
    }
  }
}

For other IDEs and MCP clients, check the configuration guide to learn more.

Quick Start

The fastest way to try this is with a Shuttle template.

shuttle init --from shuttle-hq/shuttle-examples --subfolder axum/hello-world

Connect your AI agent with the MCP server, and tell it to deploy. Your app will be live in minutes.

How to Use the Shuttle MCP Server

Here are some practical prompts to test with your AI agent once you have the MCP server configured:

Note: If the AI agent tries to execute the prompt directly without using the MCP tools first, make sure to prompt it explicitly to use the Shuttle MCP server.

Deployment and Migration:

Deploy my app to Shuttle
Migrate my Rust app to a Shuttle app
Set up a Shuttle Database for me

Debugging and Monitoring:

Check my production logs and see if we have any issues
How many Shuttle projects do I have?

Questions and Documentation:

How to scale my compute size on Shuttle?
How to set up a Shuttle Database?

Conclusion

This changes how you code with Shuttle. Your AI agent becomes a proper development partner that understands your entire deployment workflow - it can answer questions about your project configuration, check deployment status, review logs when something breaks, and guide you through scaling decisions. The friction between writing code and shipping it basically disappears.

Try it now and see the difference for yourself. Check out our getting started guide to set everything up.

Or get started with our most popular template:

shuttle init --from shuttle-hq/shuttle-examples --subfolder axum/hello-world

We would love to see what you build with this. Join our Discord community and share your feedback with us.

Building a Rust API with Claude Sonnet 4.5

Shuttle — Wed, 01 Oct 2025 15:04:55 +0000

Anthropic just dropped Sonnet 4.5 with a very BOLD CLAIM: it's the "best coding model in the world." That's a pretty confident statement in a crowded field of AI coding models.

Sonnet has proven itself to be very powerful and capable of handling complex tasks, but lately the community were claiming that Claude is slowly getting worse and it's not as good as it first was. This is especially after OpenAI released their leading coding model Codex model for their open source Codex CLI.

To bring back their users, Anthropic is finally back with a new model Sonnet 4.5 and the Claude Code VSCode extension has also been updated, so you can use Sonnet 4.5 directly in VSCode or Cursor for a better experience.

So let's see if Sonnet 4.5 is actually worth the hype and put it to the test, we as Rust developers like coding in Rust so this is what this blog post is about, we'll let Sonnet 4.5 build a Rust API for us that collects from 3 RSS feeds and serves them through an HTTP API.

Building an RSS Aggregator API with Sonnet 4.5

The goal might seem simple at first, but it's not what we're interested in, building the API is easy, what matters is how well Sonnet 4.5 can handle the task and with how many prompts and iterations we can get the API to work exactly as we want.

Here is what we care about:

Up to date code: Writing up to date code without out of date dependencies
Accuracy: How well Sonnet 4.5 can understand the task and deliver the correct code
Speed: How fast Sonnet 4.5 compared to Sonnet 4
MCP Capabilities: How good is it in calling MCP tools
Error Prediction: How well Sonnet 4.5 can predict and handle errors

Let's give it the first prompt:

Build a Rust RSS aggregator API that fetches these 3 feeds:

Hacker News: https://news.ycombinator.com/rss

Rust Blog: https://blog.rust-lang.org/feed.xml

XKCD: https://xkcd.com/rss.xml

Endpoints:

GET /feeds - all items as JSON

GET /feeds/{source} - filtered by source

Use Axum

This is a very high level prompt, the only technical requirement is to use Axum and the endpoints should be GET /feeds and GET /feeds/{source}.

First Impressions

Sonnet 4.5 got to work immediately, created the project and wrote the code for implementing all requirements.

A few things stood out right away:

The Good:

It nailed the implementation. The code was straightforward, idiomatic Rust with proper async/await patterns
Noticeably faster than Sonnet 4.0. The responses came back quicker, and it seemed more decisive in its approach
It understood the task completely and delivered exactly what we asked for

The Not-So-Good:

It used Axum 0.7 instead of the current 0.8, which has been out for almost 10 months.
The RSS feeds we provided actually have different XML formats, Sonnet was supposed to normalize them into a unified JSON structure, but it didn't.

Looking at the code, the code compiles and runs, the API however isn't returning the feed for the Rust Blog due to lack of normalization.

Iterating: Normalizing the Feeds

I gave Sonnet a follow-up prompt to normalize the feeds:

The structure of each feed is different, make sure you fetch them first and then normalize them into a unified JSON structure.

It performed exceptionally well, it first sent a GET request to each of the RSS feeds to fetch the data and understand their structure, then it normalized the data into a unified JSON structure, which is exactly what I wanted it to do.

Testing the /feeds endpoint, everything was working as expected.

Two prompts. That's all it took to go from initial implementation to a fully working, normalized RSS aggregator. That's really impressive, and the speed in which it did it is something I can't express enough.

Keeping Dependencies Fresh

There was still one thing bugging me: the outdated Axum version. Let's give another high level prompt and ask it to update the dependencies:

Some of the crates you've used are outdated. Make sure they're all up to date and read their documentation to make sure there aren't any breaking changes.

Didn't specify which crates were outdated, let's let Sonnet figure it out itself.

There's something to note here, Axum 0.8 has a breaking change in the route syntax, the old 0.7 way was /:id for path parameters, but 0.8 requires /\{id\} instead. If Sonnet doesn't catch this breaking change, it will cause the application to panic at runtime.

As you might be aware by now, MCPs aren't very friendly when it comes to keeping the context clean, my first thought was "Too many MCP calls is going to blow up the context window." which is true but the important thing is that the model stays sharp and doesn't lose focus.

It actually loooked up the documentation for Axum 0.8 and updated the route syntax correctly. cargo build works, and no runtime errors and both endpoints work perfectly.

Three prompts total with zero compilation errors so far is quite impressive.

Deploying to Shuttle

With a working API in hand, there was one more test: deployment. Claude Code has MCP (Model Context Protocol) integration with Shuttle, so I wanted to see if Sonnet could handle the entire deployment workflow.

I have the Shuttle MCP installed in Claude, so it can interact with the Shuttle platform. To install it, you can run:

claude mcp add Shuttle shuttle mcp start

You should also have the Shuttle CLI installed and logged in to Shuttle, I recommend running shuttle upgrade if you already have it installed, you can do this by running:

shuttle login

I gave it this prompt:

I want you to use the Shuttle MCP to search the docs on how to convert the app to a Shuttle app and then deploy it to Shuttle.

It identified the required changes and updated the dependencies to include Shuttle runtime.

Then converted the app to a Shuttle app.

With the conversion complete, it proceeded to deploy the API.

There you go, the RSS aggregator was live and accessible. The days have changed, the entire process from prompt to production took three simple instructions and maybe five minutes of actual work.

Results Summary

Here's how Sonnet 4.5 performed on our key criteria:

Criteria	Performance	Notes
Up to date code	⚠️ Mixed	Initially used Axum 0.7, but quickly updated to 0.8 when prompted and correctly handled breaking changes
Accuracy	✅ Excellent	Nailed the implementation on first try, understood complex requirements like feed normalization and no compilation errors
Speed	✅ Excellent	Noticeably faster than Sonnet 4.0, responses came back quicker and more decisively
MCP Capabilities	✅ Excellent	Seamlessly used MCP tools to fetch RSS feeds, check documentation, and deploy to Shuttle
Error Prediction	⚠️ Good	Caught Axum 0.8 breaking changes and updated route syntax correctly, but missed that RSS feeds have different structures

Overall Score: 9/10 - Sonnet 4.5 delivered a production-ready API in just 3 prompts with zero compilation errors and successful deployment.

Conclusion

Sonnet 4.5 delivered on its promise. Three prompts, zero compilation errors, and a fully deployed Rust API. The speed improvements are noticeable, and the MCP integration makes deployment seamless. While it's not perfect (it did use outdated dependencies initially), it quickly corrected course when prompted.

What matters is that you always keep the context clean and write your CLAUDE.md files with caution, do not overfill the context window with junk and always keep updating it and iterating on it until you get the results you want.

The "best coding model" could be true. The combination of accuracy, speed, and tool integration makes it a compelling choice for Rust development.

Want to try building something similar? Get started quickly with:

shuttle init --from shuttle-hq/shuttle-examples --subfolder axum/ai-assisted

Pandas vs Polars: Which Data Processor Runs Faster

Shuttle — Thu, 25 Sep 2025 12:06:16 +0000

When your data science workflows start hitting performance walls, the choice between Python's Pandas and Rust's Polars becomes critical. I recently discovered this firsthand while processing millions of rows of data that pushed my Python scripts to their breaking point.

The problem many data engineering teams face today isn't just about handling large datasets; it's about doing it efficiently without burning through compute resources or waiting hours for ETL processes to complete. Traditional Python approaches with Pandas, while familiar and feature-rich, often become bottlenecks as data volumes grow.

This article will walk you through a comprehensive performance comparison between Pandas and Polars using real-world data processing tasks. You'll see exact code implementations, actual benchmark results, and learn how to deploy high-performance data pipelines using Shuttle. The results will change how you approach data processing in production.

Benchmark Dataset: NYC Taxi Trip Data for Real-World ETL

For this comparison, I used the NYC Yellow Taxi dataset from January 2015—12.7 million trip records stored in CSV files totalling about 2.1 GB. This dataset serves as an excellent proxy for real-world ETL challenges that data science teams encounter daily.

The dataset characteristics make it representative of typical production scenarios:

Scale: 12.7 million rows with 19 columns across multiple data types
Data quality issues: Missing values, invalid coordinates, and outlier detection requirements
Mixed operations: Requires loading data, cleaning, aggregations, and complex filtering
Real-world complexity: Timestamps, geospatial coordinates, and categorical data sources

The ETL pipeline covers five core operations that appear in most data processing workflows:

Load: Reading CSV data from storage into memory or lazy frames
Clean: Handling missing data, filtering invalid values, and data type conversions
Aggregate: Grouping operations across temporal and categorical dimensions
Filter: Complex multi-condition filtering and sorting operations
Export: Writing processed results back to storage systems

This represents typical data pipeline tasks in production environments where teams process transaction logs, sensor data, or user behaviour analytics regularly.

Performance Bottlenecks in Python ETL with Pandas

Before diving into solutions, let's examine the specific performance bottlenecks that make Pandas challenging for large-scale data processing operations. These limitations become apparent when working with datasets that exceed available system memory or require complex data transformations.

Eager Loading and Memory Bloat

Pandas uses eager evaluation, meaning every operation executes immediately and creates intermediate results in memory. When you load CSV files, Pandas reads the entire dataset into RAM regardless of whether you'll use all columns or rows:

import pandas as pd
import time

# Pandas immediately loads entire file into memory
start = time.time()
df = pd.read_csv("yellow_tripdata_2015-01.csv")  # 2.1 GB file
load_time = time.time() - start

print(f"Loaded {len(df):,} rows in {load_time:.2f}s")
print(f"Memory usage: ~4.6 GB peak")

This eager approach creates memory pressure as each transformation step generates new DataFrames, leading to memory usage that can exceed 2-3x the original dataset size during processing operations.

The Global Interpreter Lock Problem

Python's GIL prevents true multi-threaded execution for CPU-intensive operations, meaning Pandas can only utilize one CPU core at a time for most data processing tasks:

# This aggregation uses only one CPU core despite having 8+ cores available
daily_stats = df.groupby(df['tpep_pickup_datetime'].dt.date).agg({
    'trip_distance': ['count', 'mean', 'sum'],
    'total_amount': ['mean', 'sum', 'std'],
    'passenger_count': ['sum', 'mean']
})

Modern systems with 8, 16, or more CPU cores remain underutilized, creating a significant performance bottleneck for data-intensive operations.

Handling Missing Values and Data Types

Pandas processes missing values through multiple passes over the data, with each operation requiring a full scan of all rows and columns:

# Each operation scans the entire dataset separately
df_cleaned = df.dropna(subset=['pickup_longitude', 'pickup_latitude'])
df_filled = df_cleaned.fillna({'passenger_count': 1})
df_typed = df_filled.astype({'passenger_count': 'int32'})

These sequential operations become increasingly expensive as datasets grow, particularly when dealing with wide schemas containing many columns with different data types.

How Polars Uses Rust for Fast, Multi-Threaded Data Processing

Polars takes a fundamentally different approach to data processing by leveraging Rust's performance characteristics and implementing lazy evaluation throughout the system. This architecture enables significant performance improvements for ETL operations on large datasets. To understand why polars works so well, let's look at the key features of polars:

Lazy Evaluation and Query Planning

Instead of executing operations immediately, Polars builds a query plan that gets optimized before any actual data processing begins:

use polars::prelude::*;

// Create lazy frame - no data loading yet
let df = LazyFrame::scan_csv("yellow_tripdata_2015-01.csv", ScanArgsCSV::default())?
    .filter(col("trip_distance").gt(0))
    .select([col("pickup_datetime"), col("trip_distance"), col("total_amount")])
    .group_by([col("pickup_datetime").dt().date()])
    .agg([col("trip_distance").mean(), col("total_amount").sum()]);

// Only execute when explicitly requested
let result = df.collect()?;

This lazy approach allows Polars to analyze the entire pipeline and apply optimizations like predicate pushdown, column pruning, and operation fusion before touching any data.

Query Optimization Techniques

Polars automatically applies several query optimization techniques that reduce I/O operations and memory usage:

Predicate Pushdown: Filters get moved closer to data sources, reducing the amount of data that needs to be loaded:

// Polars pushes this filter down to the CSV reader level
let filtered_data = LazyFrame::scan_csv("data.csv", ScanArgsCSV::default())?
    .filter(col("passenger_count").gt(0))  // Applied during file reading
    .select([col("trip_distance"), col("total_amount")]);

Column Pruning: Only required columns get loaded from storage, reducing memory usage and I/O:

// Only loads pickup_datetime and trip_distance columns
let df = LazyFrame::scan_csv("data.csv", ScanArgsCSV::default())?
    .select([col("pickup_datetime"), col("trip_distance")])
    .collect()?;

Multi-Core Processing and Memory Efficiency

Rust's native threading capabilities allow Polars to utilize all available CPU cores automatically. Operations like aggregations, joins, and sorting distribute work across threads without the GIL limitations that constrain Python:

// Automatically uses all CPU cores for groupby operations
let daily_stats = LazyFrame::scan_csv("data.csv", ScanArgsCSV::default())?
    .group_by([col("pickup_datetime").dt().date()])
    .agg([
        col("trip_distance").count().alias("trip_count"),
        col("trip_distance").mean().alias("avg_distance"),
        col("total_amount").sum().alias("total_revenue")
    ])
    .collect()?;  // Parallel execution across all cores

Memory efficiency comes from Rust's ownership system and Polars' streaming capabilities, which process data in chunks rather than loading entire datasets into memory. As the graph belows shows, Polars also maximizes CPU utilization, distributing work across all cores for consistently fast execution.

Pandas vs Polars ETL Pipeline Examples

Let's examine side-by-side implementations of the same ETL pipeline using both libraries. These examples show identical data processing logic implemented with each tool's best practices.

Pandas Implementation: Traditional ETL Approach

import pandas as pd
import numpy as np
from datetime import datetime
import time
import json

class PandasETL:
    def __init__(self, file_path):
        self.file_path = file_path
        self.df = None
        self.metrics = {}

    def load_and_clean_data(self):
        """Load CSV data and perform cleaning operations"""
        print("Loading and cleaning data...")
        start_time = time.time()

        # Load entire CSV into memory
        self.df = pd.read_csv(self.file_path)

        # Clean invalid coordinates and trip data
        self.df = self.df[
            (self.df['pickup_longitude'] != 0) &
            (self.df['pickup_latitude'] != 0) &
            (self.df['trip_distance'] > 0) &
            (self.df['trip_distance'] < 100) &
            (self.df['passenger_count'] > 0) &
            (self.df['passenger_count'] <= 6)
        ]

        # Convert datetime columns
        self.df['tpep_pickup_datetime'] = pd.to_datetime(
            self.df['tpep_pickup_datetime']
        )
        self.df['tpep_dropoff_datetime'] = pd.to_datetime(
            self.df['tpep_dropoff_datetime']
        )

        # Calculate trip duration
        self.df['trip_duration_minutes'] = (
            self.df['tpep_dropoff_datetime'] - self.df['tpep_pickup_datetime']
        ).dt.total_seconds() / 60

        # Remove trips with invalid duration
        self.df = self.df[
            (self.df['trip_duration_minutes'] > 0) &
            (self.df['trip_duration_minutes'] < 480)
        ]

        load_clean_time = time.time() - start_time
        self.metrics['load_clean_time'] = load_clean_time

        print(f"✅ Loaded and cleaned {len(self.df):,} rows in {load_clean_time:.2f}s")
        return self

    def aggregate_data(self):
        """Perform aggregation operations"""
        print("Performing aggregations...")
        start_time = time.time()

        # Add date columns for grouping
        self.df['date'] = self.df['tpep_pickup_datetime'].dt.date
        self.df['hour'] = self.df['tpep_pickup_datetime'].dt.hour

        # Daily statistics
        daily_stats = self.df.groupby('date').agg({
            'trip_distance': ['count', 'mean', 'sum'],
            'trip_duration_minutes': 'mean',
            'passenger_count': 'sum',
            'total_amount': ['mean', 'sum']
        })

        # Hourly patterns
        hourly_stats = self.df.groupby('hour').agg({
            'trip_distance': ['count', 'mean'],
            'total_amount': 'mean'
        })

        aggregate_time = time.time() - start_time
        self.metrics['aggregate_time'] = aggregate_time

        print(f"✅ Aggregations completed in {aggregate_time:.2f}s")
        return self

Polars Implementation: Lazy ETL Pipeline

use polars::prelude::*;
use std::collections::HashMap;
use std::time::Instant;

pub struct PolarsETL {
    metrics: HashMap<String, f64>,
}

impl PolarsETL {
    pub fn new() -> Self {
        Self { metrics: HashMap::new() }
    }

    pub fn run_etl_pipeline(&mut self, file_path: &str) -> PolarsResult<DataFrame> {
        println!("🚀 Starting Polars ETL pipeline...");
        let total_start = Instant::now();

        // Build lazy query plan
        let lazy_df = LazyFrame::scan_csv(file_path, ScanArgsCSV::default())?
            .select([
                col("pickup_longitude"),
                col("pickup_latitude"),
                col("trip_distance"),
                col("passenger_count"),
                col("tpep_pickup_datetime"),
                col("tpep_dropoff_datetime"),
                col("total_amount")
            ])
            // Apply filters (pushed down to scan level)
            .filter(
                col("pickup_longitude").neq(lit(0.0))
                    .and(col("pickup_latitude").neq(lit(0.0)))
                    .and(col("trip_distance").gt(lit(0.0)))
                    .and(col("trip_distance").lt(lit(100.0)))
                    .and(col("passenger_count").gt(lit(0)))
                    .and(col("passenger_count").lt_eq(lit(6)))
            )
            // Parse datetime columns
            .with_columns([
                col("tpep_pickup_datetime").str().strptime(
                    DataType::Datetime(TimeUnit::Microseconds, None),
                    StrptimeOptions::default(),
                    lit("coerce")
                ),
                col("tpep_dropoff_datetime").str().strptime(
                    DataType::Datetime(TimeUnit::Microseconds, None),
                    StrptimeOptions::default(),
                    lit("coerce")
                )
            ])
            // Calculate trip duration
            .with_columns([
                (col("tpep_dropoff_datetime") - col("tpep_pickup_datetime"))
                    .dt().total_minutes()
                    .alias("trip_duration_minutes")
            ])
            // Filter by trip duration
            .filter(
                col("trip_duration_minutes").gt(lit(0.0))
                    .and(col("trip_duration_minutes").lt(lit(480.0)))
            );

        // Execute aggregations
        let daily_stats = lazy_df
            .clone()
            .with_columns([col("tpep_pickup_datetime").dt().date().alias("date")])
            .group_by([col("date")])
            .agg([
                col("trip_distance").count().alias("trip_count"),
                col("trip_distance").mean().alias("avg_trip_distance"),
                col("trip_distance").sum().alias("total_trip_distance"),
                col("trip_duration_minutes").mean().alias("avg_duration"),
                col("passenger_count").sum().alias("total_passengers"),
                col("total_amount").mean().alias("avg_fare"),
                col("total_amount").sum().alias("total_revenue")
            ])
            .collect()?;

        let total_time = total_start.elapsed().as_secs_f64();
        self.metrics.insert("total_time".into(), total_time);

        println!("✅ ETL pipeline completed in {:.2f}s", total_time);
        Ok(daily_stats)
    }
}

Environment Setup for Reproducible Results

To run these benchmarks consistently, I used the following setup:

# Python environment
python3 -m venv pandas_env
source pandas_env/bin/activate
pip install pandas==2.1.0 numpy==1.24.0 psutil

# Rust environment
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo --version
rustc --version

# System specifications for reproducibility
# CPU: 8-core Intel i7 (16 threads)
# RAM: 32GB DDR4
# Storage: NVMe SSD
# OS: Ubuntu 22.04 LTS

These side-by-side implementations highlight the key design differences between Pandas and Polars. Pandas follows an eager, memory-intensive approach, while Polars builds an optimized lazy query plan that executes more efficiently. With both pipelines producing the same analytical outputs, the real distinction emerges in how they perform at scale.

Polars vs Pandas Performance on ETL Tasks

After running identical ETL operations on the 12.7 million row NYC taxi dataset, the performance differences are substantial. Here are the detailed benchmark results across all major operations:

Execution Time Comparison

ETL Operation	Pandas (seconds)	Polars (seconds)	Speedup Factor	Notes
Load + Clean	43.60	Deferred	-	Polars defers load/clean until execution phase
Aggregations	9.21	13.80	0.67x *	Polars executes load + clean + aggregation together
Filter + Sort	9.42	5.25	1.8x	Polars benefits from predicate pushdown & parallelism
Export Results	0.14	0.05	2.8x	Polars writes faster due to streaming
Total Pipeline	62.37s	19.10s	3.3x

*Includes deferred load/clean phase in Polars

Memory Usage Analysis

These results are environment-specific. In practice, Polars often uses 30-60% less memory on large CSV workloads due to column pruning and streaming, though actual savings depend on schema and operations.

Pandas Memory Profile

Peak usage: 4,658 MB during processing operations
Memory pattern: Immediate spike during CSV loading
Garbage collection: Frequent pauses for cleanup
Intermediate objects: Multiple DataFrame copies in memory

Polars Memory Profile

Peak usage: ~2,100 MB during aggregation execution
Memory pattern: Steady increase only during actual processing
No garbage collection: Rust's ownership system manages memory
Streaming operations: Data processed in manageable chunks

CPU Utilization Patterns

Polars automatically parallelizes across available cores. Pandas relies on single-threaded execution for most operations unless explicitly offloaded (e.g., via Dask, Modin).

Pandas CPU Usage

Single-thread utilization: ~12.5% of 8-core system (1 core)
GIL limitations: Other threads blocked during computation
Load balancing: Uneven system resource usage

Polars CPU Usage

Multi-thread utilization: ~85% of 8-core system (all cores)
Parallel operations: Concurrent processing across cores
Efficient scheduling: Even load distribution across threads

Why Polars is Faster

The dramatic performance differences stem from fundamental architectural choices. Understanding these differences helps explain when and why you might choose one approach over the other for your data processing systems.

Eager vs Lazy Execution Models

Pandas Eager Execution:

# Each operation executes immediately
df = pd.read_csv("data.csv")           # Load: 32.5s
df_clean = df[df['distance'] > 0]      # Filter: 8.2s
df_agg = df_clean.groupby('date').sum() # Aggregate: 9.1s
# Total: 49.8s across separate operations

Polars Lazy Execution:

// Build query plan without execution
let df = LazyFrame::scan_csv("data.csv", ScanArgsCSV::default())?
    .filter(col("distance").gt(0))     // Added to plan: ~0s
    .group_by([col("date")])           // Added to plan: ~0s
    .sum()                             // Added to plan: ~0s
    .collect()?;                       // Execute all: 13.8s

The lazy approach allows Polars to optimize the entire pipeline as a single operation, eliminating intermediate steps and reducing data movement.

Efficient Memory Access Patterns

Polars leverages several memory optimization techniques:

Columnar Data Layout: Data stored column-wise enables better cache locality and vectorized operations.

SIMD Instructions: Single Instruction, Multiple Data processing accelerates numerical computations.

Zero-Copy Operations: Data transformations avoid unnecessary memory allocation when possible.

Streaming Execution: Large datasets are processed in chunks that fit in the CPU cache.

Query Rewriting and Optimization

Polars automatically rewrites queries for better performance:

// Original query
let result = LazyFrame::scan_csv("data.csv", ScanArgsCSV::default())?
    .select([col("*")])                    // Select all columns
    .filter(col("amount").gt(100))         // Filter expensive trips
    .select([col("date"), col("amount")])  // Select subset
    .collect()?;

// Polars optimization rewrites this to:
// 1. Scan only date and amount columns (column pruning)
// 2. Apply filter during CSV reading (predicate pushdown)
// 3. Skip unnecessary intermediate selections

These optimizations occur automatically, without requiring code changes, making Polars faster while maintaining simplicity. But performance alone isn't the full story. Once you've squeezed every ounce of speed from your ETL pipeline, the next challenge emerges: how do you take that optimized workflow and actually run it in production at scale, reliably, and without DevOps headaches?

Benchmarking on your laptop is one thing; managing deployments, scaling, SSL certificates, and infrastructure is another. That's where Shuttle comes in. With Shuttle, you can deploy your Polars ETL pipeline as a production-ready API in just a few commands, no containers, no load balancers, no endless YAML files.

Deploying a Rust ETL Pipeline with Shuttle

Of course, benchmarks are only half the story. The real challenge is turning a fast local pipeline into something production-ready. That's where Shuttle helps: it lets you deploy Polars pipelines as APIs without wrestling with infra. Traditional Rust deployment can be complex, but Shuttle abstracts away the infrastructure management.

Building a Production ETL API

Here's how to wrap our Polars ETL pipeline in a web API suitable for production use:

use axum::{routing::get, Router, Json};
use serde::{Serialize, Deserialize};
use shuttle_runtime::main;
use tower_http::cors::CorsLayer;

#[derive(Serialize)]
struct ETLResults {
    processing_time_seconds: f64,
    rows_processed: u64,
    daily_statistics: Vec<DailyStats>,
    performance_summary: String,
}

#[derive(Serialize)]
struct DailyStats {
    date: String,
    trip_count: u64,
    avg_distance: f64,
    total_revenue: f64,
}

async fn run_etl_benchmark() -> Json<ETLResults> {
    let mut etl = PolarsETL::new();

    // In production, you'd load from your data warehouse
    // For demo purposes, we return representative results
    let results = ETLResults {
        processing_time_seconds: 19.1,
        rows_processed: 12_748_986,
        daily_statistics: create_sample_stats(),
        performance_summary: "Processed 12.7M taxi records in 19.1 seconds using Polars".to_string(),
    };

    Json(results)
}

async fn health_check() -> Json<serde_json::Value> {
    Json(serde_json::json!({
        "status": "healthy",
        "service": "Polars ETL Pipeline",
        "capabilities": ["high_throughput_processing", "multi_core_execution", "memory_efficient"]
    }))
}

#[main]
async fn main() -> shuttle_axum::ShuttleAxum {
    let router = Router::new()
        .route("/", get(health_check))
        .route("/etl/benchmark", get(run_etl_benchmark))
        .route("/health", get(health_check))
        .layer(CorsLayer::permissive());

    Ok(router.into())
}

Simple Shuttle Deployment Process

Deploying this ETL pipeline to production requires minimal configuration:

1. Deploy with three commands:

# Install Shuttle CLI
cargo install cargo-shuttle

# Login to Shuttle
shuttle login

# Deploy to production
shuttle deploy

Shuttle handles all the complex infrastructure concerns:

Container orchestration and scaling
Load balancing and networking
SSL certificate management
Monitoring and logging systems
Automatic deployments from Git

Integration with Data Systems

For production use, you can connect this pipeline to various data sources and destinations:

// Example: Reading from cloud storage
let df = LazyFrame::scan_csv("s3://data-bucket/taxi-data/*.csv", ScanArgsCSV::default())?;

// Example: Writing to data warehouse
let result = df.collect()?;
result.write_parquet("s3://output-bucket/processed-data.parquet", ParquetWriteOptions::default())?;

// Example: Streaming processing
let streaming_df = LazyFrame::scan_csv("data/*.csv", ScanArgsCSV::default())?
    .with_streaming(true)  // Process in chunks
    .collect()?;

Migrating from Pandas to Polars: A Practical Guide

The decision to migrate from Pandas to Polars shouldn't be all-or-nothing. Here's a practical approach for teams considering the transition while minimizing risk and disruption.

When to Switch and When to Stick with Pandas

Consider Polars when:

Processing datasets larger than available RAM
ETL operations take more than a few minutes to complete
Memory usage becomes a limiting factor in your systems
CPU cores remain underutilized during data processing
You need predictable performance characteristics

Stick with Pandas when:

Working with datasets under 1GB consistently
Heavy use of domain-specific libraries that integrate with Pandas
Rapid prototyping, where development speed matters more than execution speed
Team lacks Rust experience, and the timeline is tight
Complex data science workflows with many specialized functions

Hybrid Workflows: Wrapping Heavy Steps in Polars

You don't need to rewrite entire systems. Start by identifying performance bottlenecks and replacing them with Polars operations:

import pandas as pd
import polars as pl

def hybrid_etl_pipeline(data_path):
    # Use Polars for heavy data loading and cleaning
    polars_df = pl.scan_csv(data_path)\
        .filter(pl.col("amount") > 0)\
        .with_columns([
            pl.col("timestamp").str.strptime(pl.Date),
            (pl.col("end_time") - pl.col("start_time")).alias("duration")
        ])\
        .collect()

    # Convert to Pandas for specialized analysis
    pandas_df = polars_df.to_pandas()

    # Use existing Pandas-based analysis code
    result = perform_statistical_analysis(pandas_df)

    # Convert back to Polars for final aggregation
    final_result = pl.from_pandas(result)\
        .group_by("category")\
        .agg([pl.col("value").sum(), pl.col("count").count()])\
        .collect()

    return final_result

def perform_statistical_analysis(df):
    # Existing Pandas code remains unchanged
    return df.apply(lambda x: complex_statistical_function(x))

Testing Polars Without Rewriting Your Pipeline

Start with a proof-of-concept approach that validates performance improvements:

# 1. Benchmark existing Pandas operations
import time

def benchmark_pandas_operation():
    start = time.time()
    df = pd.read_csv("large_dataset.csv")
    result = df.groupby("category").agg({
        "amount": ["sum", "mean", "count"],
        "duration": "mean"
    })
    pandas_time = time.time() - start
    return result, pandas_time

# 2. Implement equivalent Polars version
def benchmark_polars_operation():
    start = time.time()
    result = pl.scan_csv("large_dataset.csv")\
        .group_by("category")\
        .agg([
            pl.col("amount").sum().alias("amount_sum"),
            pl.col("amount").mean().alias("amount_mean"),
            pl.col("amount").count().alias("amount_count"),
            pl.col("duration").mean().alias("duration_mean")
        ])\
        .collect()
    polars_time = time.time() - start
    return result, polars_time

# 3. Compare results and performance
pandas_result, pandas_time = benchmark_pandas_operation()
polars_result, polars_time = benchmark_polars_operation()

print(f"Pandas: {pandas_time:.2f}s")
print(f"Polars: {polars_time:.2f}s")
print(f"Speedup: {pandas_time/polars_time:.1f}x")

Gradual Migration Strategy

Phase 1: Identify bottlenecks

Profile existing code to find slowest operations
Measure current memory usage and processing time
Document data types and transformations used

Phase 2: Proof of concept

Implement one critical operation in Polars
Validate identical results between implementations
Measure performance improvements

Phase 3: Expand coverage

Replace additional heavy operations
Build team familiarity with Polars syntax
Update deployment processes to handle Rust code

Phase 4: Full migration

Convert remaining operations where beneficial
Optimize query patterns for maximum performance
Update monitoring and alerting systems

Final Takeaways

Our benchmarks showed Polars delivering a 3.3x speedup over Pandas for this ETL workload, with significantly lower memory usage and full CPU utilization. This performance comes from its modern architecture: lazy evaluation, query optimization, and native multi-threading powered by Rust.

However, performance isn't everything. Pandas remains the pragmatic choice for smaller datasets (<1 GB), rapid prototyping, and tasks deeply integrated with the broader Python data science ecosystem. In practice, many teams adopt a hybrid strategy: using Polars for heavy data preparation and falling back to Pandas for specialized analysis and ML model integration.

Ultimately, if your current pipelines are hitting performance walls, Polars offers a clear path to faster, more scalable processing. But turning that local speed into a production-ready system presents the next hurdle. This is where Shuttle completes the picture. It abstracts away the complexity of containers and infrastructure, allowing you to deploy a high-performance Polars pipeline as a scalable API in minutes, not days. It turns benchmarks into real-world applications without the DevOps overhead.

Ready to see the difference yourself? Deploy the complete Polars ETL benchmark and run your own comparisons with real data.

View the complete benchmark code on GitHub →

How to Monitor Data Pipelines in Rust Using OpenTelemetry and Shuttle

Shuttle — Wed, 24 Sep 2025 12:24:29 +0000

TL;DR: Data pipelines often fail silently, corrupting data before anyone notices. We show you how to build a high-performance, observable ETL pipeline in Rust using Polars for speed, OpenTelemetry for detailed metrics and traces, and Shuttle for zero-config deployment and telemetry export. This guide provides commented code, deployment steps, and dashboard examples to help you catch failures early, pinpoint bottlenecks, and ensure data quality from start to finish.

ETL and data engineering workflows break silently in production. A CSV file processes millions of records, but somewhere in the pipeline, wrong values slip through data validation, memory usage spikes during aggregation stages, or processing slows to a crawl without clear indicators of where the bottleneck occurs. By the time data engineers notice the issue, corrupted data has already propagated downstream.

Python developers working with Pandas frequently encounter this challenge. Memory blowups happen during large dataset processing, errors cascade across transformation stages with minimal context, and debugging performance issues requires manually adding print statements throughout the code. Traditional application monitoring tools focus on web request metrics such as latency, throughput, and error rates, but data pipelines need visibility into processing stages, memory consumption patterns, and data quality indicators.

Here's the alternative: Rust applications with Polars deliver predictable performance, OpenTelemetry provides standardized observability, and Shuttle eliminates infrastructure complexity. By implementing such a combination, you get clean, fast, observable data pipelines that surface issues before they corrupt your data.

This article explains building a production-ready data pipeline that processes real-world datasets while maintaining complete visibility into every processing stage, memory usage pattern, and performance characteristic.

Benchmark Pipeline: CSV Processing with Polars

Let me show you a working ETL example that processes NYC taxi CSV files. This pipeline demonstrates the observability challenges that make data engineering workflows different from typical web applications.

The data pipeline follows these stages: load massive CSV files (1.9GB with 12.7 million records), parse datetime fields and geographic coordinates, filter invalid records and outliers, aggregate trip patterns by time periods, and write results for downstream analysis.

Each stage presents monitoring challenges. Loading CSV files requires tracking memory allocation patterns as data enters the system. Parsing operations can fail silently when date formats don't match expectations. Filtering stages need visibility into how many records get rejected and why. Aggregation operations consume the most memory and require peak usage tracking. Output operations need validation that results match expected patterns.

Polars provides the performance foundation for this pipeline. Its lazy evaluation approach minimizes memory pressure, columnar data processing delivers consistent performance across large datasets, and structured operations make precise measurement possible. Unlike Pandas operations that can consume unpredictable amounts of memory, Polars operations have measurable resource requirements that can be monitored and alerted on.

The NYC taxi dataset contains all the characteristics that make observability critical: high record volume, data quality issues with missing coordinates and invalid timestamps, complex geographic and temporal transformations, and memory-intensive aggregation operations. Processing this dataset demonstrates how proper instrumentation reveals bottlenecks and data quality issues before they impact production systems.

What to Monitor in Data Pipelines (and Why)

Data pipeline monitoring differs fundamentally from web application observability. Instead of request latency and error rates, you need visibility into processing characteristics that determine pipeline reliability and data quality.

Stage-level execution time reveals processing bottlenecks. While web applications measure individual request duration, data pipelines need timing for load operations, parsing stages, transformation steps, aggregation phases, and output generation. A single slow stage can bottleneck the entire pipeline.
Throughput and record counts provide data volume insights. Monitor records processed per second, total record counts per stage, and record rejection rates during validation. These metrics help identify processing capacity limits and data quality trends.
Peak memory consumption per stage prevents out-of-memory failures. Filtering operations might spike memory usage when loading large intermediate results. Aggregation stages require materializing grouped data. Memory patterns vary dramatically based on dataset characteristics and processing logic.
Error paths and panics in Rust code need special attention. Unlike garbage-collected languages, Rust memory safety prevents many runtime failures, but data pipeline errors often relate to schema mismatches, missing files, or invalid data formats. Capturing error context enables rapid debugging.

These metrics differ from typical web application monitoring because data pipelines process discrete batches rather than continuous streams, consume resources in predictable patterns based on dataset size, and fail differently than request-response applications.

Traditional application observability focuses on user-facing performance and system health. Data pipeline observability focuses on data quality, processing efficiency, and resource utilization patterns that affect downstream systems and analysis accuracy.

Adding Observability to Rust ETL Pipeline with OpenTelemetry

Instrumenting Rust applications for data pipeline monitoring requires strategic placement of tracing spans and metrics collection. The observability approach needs to capture processing stage performance, memory usage patterns, and data quality indicators without significantly impacting pipeline throughput.

Here's how to structure observability in your Rust data pipeline using OpenTelemetry and tracing:

use polars::prelude::*;
use std::collections::HashMap;
use std::time::Instant;
use tracing::{info, instrument, span, Level};

// Memory monitoring function for RSS tracking
fn rss_mb() -> f64 {
    if let Ok(s) = std::fs::read_to_string("/proc/self/status") {
        for line in s.lines() {
            if let Some(val) = line.strip_prefix("VmRSS:") {
                let kb: f64 = val.split_whitespace().nth(0).unwrap_or("0").parse().unwrap_or(0.0);
                return kb / 1024.0;
            }
        }
    }
    0.0
}

// Track peak memory across processing stages
fn bump_peak(metrics: &mut HashMap, label: &str) {
    let m = rss_mb();
    metrics.insert(format!("{}_memory_mb", label), m);
    let peak = metrics.get("peak_memory_mb").cloned().unwrap_or(0.0);
    if m > peak {
        metrics.insert("peak_memory_mb".into(), m);
    }
}

pub struct PolarsETL {
    df: Option,
    metrics: HashMap, // Custom metrics storage for pipeline-specific data
}

impl PolarsETL {
    pub fn new() -> Self {
        Self { df: None, metrics: HashMap::new() }
    }

    // Automatic span creation with contextual attributes (file path)
    #[instrument(level = "info", skip(self))]
    pub fn load_data(&mut self, file_path: &str) -> PolarsResult<&mut Self> {
        // Manual span creation for nested tracing hierarchy
        let load_span = span!(Level::INFO, "etl_load", file = file_path);
        let _enter = load_span.enter();

        // Structured logging with contextual information
        info!("Loading CSV file: {}", file_path);
        let start = Instant::now(); // Performance timing measurement

        let lf = LazyCsvReader::new(file_path)
            .with_has_header(true)
            .with_infer_schema_length(Some(2000))
            .finish()?
            .select([
                col("pickup_longitude"),
                col("pickup_latitude"), 
                col("trip_distance"),
                col("passenger_count"),
                col("total_amount"),
            ]);

        self.df = Some(lf);
        let t = start.elapsed().as_secs_f64(); // Duration calculation
        self.metrics.insert("load_time".into(), t); // Custom metric storage
        bump_peak(&mut self.metrics, "after_load"); // Memory usage tracking

        // Structured logging with key-value metrics for observability platforms
        info!(
            etl.load.duration = t,                    // Performance metric
            etl.load.memory_mb = self.metrics.get("after_load_memory_mb").unwrap_or(&0.0), // Resource usage
            stage = "load",                           // Pipeline stage identifier
            "CSV load completed"                      // Human-readable message
        );

        Ok(self)
    }

    // Automatic instrumentation with span naming and skipping of complex parameters
    #[instrument(level = "info", skip(self))]
    pub fn clean_data(&mut self) -> PolarsResult<&mut Self> {
        // Nested span for detailed tracing hierarchy
        let clean_span = span!(Level::INFO, "etl_clean");
        let _enter = clean_span.enter();

        // Stage-specific logging with contextual information
        info!("Starting data cleaning stage");
        let start = Instant::now(); // Performance measurement start

        if let Some(df) = &self.df {
            let cleaned = df
                .clone()
                .filter(
                    col("pickup_longitude").neq(lit(0.0))
                        .and(col("pickup_latitude").neq(lit(0.0)))
                        .and(col("trip_distance").gt(lit(0.0)))
                        .and(col("passenger_count").gt(lit(0)))
                )
                .cache();

            self.df = Some(cleaned);
        }

        let t = start.elapsed().as_secs_f64(); // Performance timing
        self.metrics.insert("clean_time".into(), t); // Stage-specific metrics
        bump_peak(&mut self.metrics, "after_clean"); // Memory tracking per stage

        // Multi-dimensional metrics emission with contextual attributes
        info!(
            etl.clean.duration = t,                   // Stage performance
            etl.clean.memory_mb = self.metrics.get("after_clean_memory_mb").unwrap_or(&0.0), // Resource consumption
            stage = "clean",                          // Pipeline stage tag
            "Data cleaning completed"                 // Completion status
        );

        Ok(self)
    }
}

Spans with contextual attributes provide distributed tracing capability. Each processing stage gets its own span with resource attributes like stage, file, and processing metadata. This enables tracing the whole process across complex pipeline operations.
Instrumented functions using the #[instrument] attribute automatically capture function entry/exit, execution time, and error conditions. The tracing framework handles span lifecycle management and context propagation.
Metrics emission follows OpenTelemetry conventions with structured field names like etl.load.duration and etl.clean.memory_mb. These metrics integrate with observability platforms for dashboard creation and alerting.

Memory monitoring through rss_mb() reads actual RSS memory consumption from /proc/self/status, providing accurate memory usage data during each processing stage. This approach works reliably in containerized environments and cloud deployments.

⚠️ Platform-Specific Code: This memory monitoring function reads from the /proc filesystem, which is specific to Linux. For cross-platform compatibility, consider using a crate like sysinfo that provides unified system information APIs across Windows, macOS, and Linux.

The image below shows the memory usage monitoring for Polars, demonstrating increased memory consumption during processing.

These images show the system monitoring during ETL pipeline execution, where the first image displays baseline performance with low CPU utilization (1-8%) and stable 5.1GB memory usage, the next image shows increased processing activity with CPU8 reaching 32.4% while memory remains stable, and the last one captures peak ETL operations with significantly higher CPU utilization (CPU8 at 85.9%) and elevated memory consumption at 9.9GB, effectively demonstrating how the Rust pipeline scales resource usage during different processing phases and validating the importance of memory monitoring.

By establishing these observability goals upfront, tracking performance, memory usage, and data quality, you create a foundation for reliable monitoring.

Exporting Observability Data to BetterStack via Shuttle

Shuttle provides out-of-the-box OpenTelemetry integration that eliminates traditional observability infrastructure complexity. Instead of configuring collectors, managing exporters, or writing YAML configurations, you get automatic telemetry data export to your chosen observability platform.

To enable this integration, include Shuttle's setup-otel-exporter feature in your runtime configuration:

[dependencies]
shuttle-runtime = { version = "0.56", features = ["setup-otel-exporter"] }
shuttle-axum = "0.56"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["json"] }
opentelemetry = { version = "0.30", features = ["trace"] }

Then configure observability in your application code:

use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};

pub fn init_tracing(service_name: &str) {
    let env_filter = EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| EnvFilter::new("info"));

    let fmt_layer = tracing_subscriber::fmt::layer()
        .json()
        .with_current_span(true)
        .with_timer(tracing_subscriber::fmt::time::UtcTime::rfc_3339());

    tracing_subscriber::registry()
        .with(env_filter)
        .with(fmt_layer)
        .init();
}

Shuttle's approach eliminates the infrastructure complexity typically associated with observability. No Docker containers running collectors, no YAML configuration files for exporters, no manual OTLP endpoint management. The platform handles OpenTelemetry protocol export, authentication, and routing automatically.

When you enable BetterStack integration in your Shuttle project settings, telemetry data flows directly from your Rust application to BetterStack's ingestion endpoints. The integration includes automatic retry logic, batching for performance, and error handling that would normally require manual configuration.

This approach works because Shuttle's runtime includes a tracer provider that automatically exports spans and metrics when observability integrations are enabled. Your application code focuses on emitting telemetry data using standard OpenTelemetry patterns, while the platform handles infrastructure concerns.

The images above demonstrate the BetterStack observability platform receiving telemetry data from the Rust ETL pipeline, where the first screen shows basic log streams with application startup events including tracing subscriber initialization and service startup messages, while the second reveals detailed OpenTelemetry span data displaying trace IDs, span IDs, and stage timing information, showcasing how the integration captures both high-level application logs and granular distributed tracing data for comprehensive pipeline monitoring.

Deploying the Observable Pipeline with Shuttle

Shuttle deployment transforms your observable Rust application into a production service with a single command. The platform's infrastructure-from-code approach means your deployment configuration lives in your application rather than external configuration files. The deployment process is broken down into steps:

Step 1: Set up your application for Shuttle deployment:

mod etl;
mod observability;

use axum::{routing::get, extract::Query, response::Json, Router};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use tower_http::{cors::CorsLayer, trace::TraceLayer};
use tracing::info;

#[shuttle_runtime::main]
async fn shuttle_main() -> shuttle_axum::ShuttleAxum {
    observability::init_tracing("polars-etl-pipeline");

    let app = api_router()
        .layer(CorsLayer::permissive())
        .layer(TraceLayer::new_for_http());

    info!(event = "startup", service = "polars-etl", "Application ready");
    Ok(app.into())
}

#[derive(Serialize)]
struct BenchmarkResult {
    metrics: HashMap,
    message: String,
    throughput_summary: String,
}

async fn health() -> &'static str {
    info!(
        etl.health.check = 1,
        endpoint = "/health",
        "Health check performed"
    );
    "OK"
}

async fn benchmark(_query: Query>) -> Json {
    let start = std::time::Instant::now();

    info!(
        etl.benchmark.start = 1,
        endpoint = "/benchmark", 
        "Benchmark endpoint called"
    );

    // Representative pipeline metrics (avoiding heavy processing on production dyno)
    let mut metrics = HashMap::new();
    metrics.insert("load_duration_ms".to_string(), 1200.0);
    metrics.insert("clean_duration_ms".to_string(), 800.0);
    metrics.insert("aggregate_duration_ms".to_string(), 400.0);
    metrics.insert("total_duration_ms".to_string(), 2800.0);
    metrics.insert("records_processed".to_string(), 12_748_986.0);

    // Emit metrics for BetterStack dashboards
    info!(
        etl.load.duration = 1.2,
        etl.clean.duration = 0.8,
        etl.aggregate.duration = 0.4,
        etl.rows.processed = 12_748_986_i64,
        stage = "complete",
        "Pipeline benchmark completed"
    );

    let elapsed = start.elapsed().as_millis() as f64;
    info!(
        etl.request.duration = elapsed,
        endpoint = "/benchmark",
        "Request completed"
    );

    let throughput = 12_748_986.0 / 2.8;
    Json(BenchmarkResult {
        metrics,
        message: "Benchmark completed successfully".to_string(),
        throughput_summary: format!("Processed 12.7M records in 2.8s → {:.0} rows/sec", throughput),
    })
}

fn api_router() -> Router {
    Router::new()
        .route("/", get(health))
        .route("/health", get(health))
        .route("/benchmark", get(benchmark))
}

Step 2: Deploy your observable pipeline:

# Deploy to Shuttle platform
shuttle deploy

# Monitor deployment and access logs
shuttle status
shuttle logs --follow

Step 3: Testing endpoints confirms telemetry data flows correctly:

# Test health endpoint
curl https://your-app.shuttle.app/health

# Generate benchmark telemetry
curl https://your-app.shuttle.app/benchmark

Shuttle automatically streams metrics to BetterStack once you configure the integration in your project settings. The platform handles authentication, retry logic, and batching that would normally require manual OTLP configuration.

The above images demonstrate the complete development-to-production workflow for the observable Rust ETL pipeline. The initial screens show local CLI execution with structured JSON logging, revealing detailed performance metrics including 108-second total runtime and stage-by-stage timing breakdown, while subsequent displays present comprehensive telemetry output with dataset information, processing statistics of 12.7M records processed at 4.5M records/second, and deployment configuration details. The workflow continues with the deployed Shuttle application's API endpoints for health checks and benchmarking, followed by captures of the Shuttle deployment process and dashboard showing the running application with telemetry integration and log streaming capabilities, further showing how the same codebase provides both detailed local benchmarking and production-ready observability through feature flags and deployment automation.

Building Dashboards for ETL Monitoring in BetterStack

When running ETL pipelines, it's not enough to just know they work; you need visibility into how they perform over time. BetterStack dashboards provide that visibility at a glance by transforming your telemetry data into actionable monitoring dashboards. The platform automatically recognises the metric naming patterns from your Rust application and enables sophisticated visualization and alerting capabilities.

Here are some common ETL-specific metrics and their naming conventions you should follow:

etl.load.duration: measures the time spent loading CSV
etl.clean.duration: tracks the performance of data cleaning stage
etl.aggregate.duration: captures how long aggregation operation takes
etl.rows.processed: shows record throughput and overall volume
etl.memory.peak: reports peak memory consumption per stage

You can configure dashboard for data pipeline monitoring like:

Memory Usage Over Time Dashboard:

{
  "metric": "etl.memory.peak",
  "aggregation": "max",
  "group_by": ["stage"],
  "visualization": "line_chart",
  "time_range": "1h"
}

Stage-by-Stage Duration Analysis:

{
  "metrics": ["etl.load.duration", "etl.clean.duration", "etl.aggregate.duration"],
  "aggregation": "avg",
  "visualization": "stacked_area",
  "group_by": ["stage"]
}

Processing Throughput Tracking:

{
  "metric": "etl.rows.processed",
  "aggregation": "rate",
  "time_window": "1m",
  "visualization": "gauge"
}

These visualizations provide insights into processing performance trends, memory consumption patterns during different pipeline stages, and throughput characteristics that help with capacity planning and performance optimization.

These images show Betterstack monitoring dashboards tracking ETL pipeline performance, where the Telemetry interface displays Clean Time and Aggregate Time charts with regular periodic spikes indicating scheduled batch operations, while a separate CPU usage chart reveals sustained high utilization around 1,200-1,500T during data processing, providing essential visibility into pipeline performance and resource monitoring.

With BetterStack's alerting capabilities, you can enable proactive monitoring by setting alerts for memory usage exceeding thresholds, processing duration degradation, or throughput drops below expected levels with integration into incident management systems for automated escalation.

Local Development and Testing Setup

So, how can you test and benchmark this pipeline on your own local machine with a real dataset? Running the full ETL process within our deployed web service isn't practical; web endpoints need fast responses, not long-running data processing jobs. Instead, we'll use Rust's feature flags to create a separate CLI for local, in-depth testing. This approach lets you experiment with different datasets, measure actual performance characteristics, and validate your observability setup before deploying to production.

Feature flags enable different build targets for local development versus production deployment. This approach allows for comprehensive local testing with real datasets while maintaining production builds as lightweight and cost-effective as possible.

Configure feature-based compilation in Cargo.toml:

[features]
bench-cli = []
default = []

Local development implementation with full ETL processing:

#[cfg(feature = "bench-cli")]
fn main() -> Result<(), Box> {
    observability::init_tracing("polars-etl-benchmark-cli");

    println!("Starting Polars ETL benchmark with observability");

    let data_file = std::env::var("DATA_PATH")
        .unwrap_or_else(|_| "data/yellow_tripdata_2015-01.csv".to_string());

    if !std::path::Path::new(&data_file).exists() {
        eprintln!("CSV file not found: {}", &data_file);
        eprintln!("Set DATA_PATH environment variable or place file at default location");
        return Ok(());
    }

    let total_start = std::time::Instant::now();
    let mut etl = PolarsETL::new();

    match etl
        .load_data(&data_file)?
        .clean_data()?
        .aggregate_data()?
        .save_results("results")
    {
        Ok(_) => {
            let total_time = total_start.elapsed().as_secs_f64();
            println!("ETL benchmark completed in {:.2} seconds", total_time);

            let metrics = etl.get_metrics();
            println!("Performance metrics:");
            for (key, value) in metrics {
                if key.contains("time") {
                    println!("  {}: {:.2}s", key.replace('_', " "), value);
                }
            }
        }
        Err(e) => {
            eprintln!("ETL processing error: {}", e);
        }
    }

    Ok(())
}

CLI workflow for benchmarking locally with comprehensive logs and metrics:

# Process full dataset with detailed telemetry
RUST_LOG=debug cargo run --release --features bench-cli

# Use custom dataset location
DATA_PATH=/path/to/your/dataset.csv \
RUST_LOG=info cargo run --release --features bench-cli

Dataset loading via CLI enables testing with different data characteristics. The CLI version processes actual CSV files and provides accurate performance measurements, memory usage patterns, and processing throughput data that inform production capacity planning.

Local testing reveals performance characteristics that aren't visible in production monitoring. Memory allocation patterns during aggregation stages, processing bottlenecks with different dataset sizes, and error handling behaviour with malformed data files.

Wrapping Up: Fast Pipelines with Precise Monitoring

Rust with Polars delivers consistent performance that traditional Python workflows often lack. While Python pipelines struggle with unpredictable memory spikes, Rust provides predictable resource usage that scales linearly with dataset size. Moreover, compile-time error checking prevents the runtime failures that typically corrupt downstream analysis in dynamically-typed environments.

Building on this foundation, OpenTelemetry adds precise monitoring with minimal performance overhead. This enables comprehensive dashboards and proactive alerts that surface issues before they impact data quality. Meanwhile, Shuttle eliminates the deployment complexity that often delays pipeline rollouts, providing zero-config OTLP export, automatic retry handling, and managed authentication out of the box.

The business impact is substantial: teams ship data products 3x faster without infrastructure bottlenecks, process larger datasets with predictable costs, and maintain higher system reliability that directly improves user experience. Together, these tools create production-ready workflows that deliver fast processing through Rust and Polars, comprehensive visibility via OpenTelemetry, and frictionless deployment through Shuttle. This proactive monitoring approach prevents costly memory failures, enables accurate capacity planning, and catches performance bottlenecks before they affect end users.

Ready to build observable data pipelines? Try the complete example on Shuttle with one-click deployment: Deploy Observable Pipeline

Troubleshooting Telemetry Issues in Rust Pipelines - FAQ

Q: My metrics aren't showing up in BetterStack. What's wrong?

A: First, double-check your integration settings in the Shuttle console and verify your source token hasn't expired. Second, confirm your metric names in the code (e.g., etl.load.duration) exactly match your dashboard queries—BetterStack requires precise field name matching. Finally, redeploy your application after making integration changes, as the OTLP exporter configuration updates during deployment. Test the flow by running curl https://your-app.shuttle.app/benchmark and checking if logs appear in BetterStack's log stream before expecting dashboard data.

Q: Why are my spans missing or not connecting in distributed traces?

A: Check that your OpenTelemetry dependencies use compatible versions; mismatches between tracing-opentelemetry and opentelemetry crates can break span context propagation. Ensure your instrumented functions include appropriate resource attributes like stage or file, as missing context reduces trace value. Also, verify your tracer provider configuration includes your service name and resource attributes needed for filtering and grouping in trace analysis.

Q: My pipeline works in production but fails during local testing. What should I check?

A: Start by validating CSV file locations and permissions—your application needs read access to data files and write access to results directories. Check that your dataset format is compatible with Polars CSV parsing, as schema mismatches or encoding issues can cause silent failures. Monitor memory consumption during testing since large datasets might exceed available memory during aggregation stages. Finally, debug your environment variable configuration, ensuring DATA_PATH points to accessible file locations.

Q: How can I get better error information when my pipeline fails?

A: Implement structured error logging that includes file paths, record counts, and processing stage information in error messages. This context enables rapid issue resolution by showing exactly where and why failures occur, rather than generic error messages that require extensive debugging to understand.

A Hands-on Comparison of Best MCP Servers for Rust Developers

Shuttle — Tue, 23 Sep 2025 15:38:13 +0000

Model Context Protocol (MCP) servers boost developer productivity by working with an AI coding assistants like GitHub Copilot, Cursor, and Claude. With MCP having full access to the Rust project, the AI assistants are no longer limited to the currently open file; they can now follow instructions to execute commands, analyze the entire codebase, run tests, and automate workflows, making development faster.

Most developers don't rely on a single MCP; instead, they use multiple servers, depending on their task. Each MCP comes with its own strengths and limitations.

In this article, we'll walk through the best MCP servers for Rust developers. We will also compare the most popular MCP servers to break down what each server does best, and show you how to deploy your Rust applications directly from your IDE.

Here is a quick overview of the comparison between the best MCP Servers

MCP Server	Rust Integration	AI Compatibility	Security Setup	Deployment Support	Notes
Context7 MCP	Provides up-to-date, version-specific documentation for all libraries including Rust crates	AI assistant can fetch real-time docs and code examples for accurate code generation	Low risk, read-only access to documentation APIs	None	Essential for preventing hallucinated APIs and outdated code examples
Docker MCP	Good for developing containerized Rust applications.	AI assistance can issue Docker commands through MCP	Requires elevated privileges for certain operations, which can pose risks if not isolated	Can build, package, and push Rust apps to a Docker Registry	Suitable for those interested in or running Rust applications in Docker containers
GitHub Server MCP	Integrates with Rust code repositories and supports CI/CD workflows (GitHub Actions)	The AI assistant can raise PRs, manage issues, and interact with GitHub workflows	Requires GitHub auth token access with limited or supervised privileges	Works effectively with GitHub Actions workflow	Great for managing repositories and automating workflows
File System MCP Servers	Provide direct access to Rust source code	AI assistance has complete visibility of the Rust project	Risky because AI assistant can read and modify project files. Sandbox is recommended	Requires a custom script for deployment	Useful for testing workflows that rely on code modifications
Memory MCP Servers	No direct Rust project support	Helpful in maintaining conversational context across tasks	Low risk since it operates only in memory	None	It is used in combination with other MCPs or systems
Browsing MCP Servers	No direct Rust integration. This is useful for fetching Rust documentation and creating crates.io packages	AI assistant can read and retrieve information from Rust documentation	None	None	Great for referencing external Rust documentation and libraries
Shuttle MCP	Built specifically for Rust. It integrates perfectly into the Rust ecosystem	It works well with AI assistants to manage and deploy Rust applications	It handles secrets and other sensitive details securely on the Shuttle Platform	It can deploy Rust applications directly from a developer's IDE	It is helpful for Rust deployment

Before we deploy our Rust applications directly from the IDE, let's understand what Model Context Protocol (MCP) is and what makes a good MCP for Rust developers.

What is the Model Context Protocol (MCP)?

Large Language Models (LLMs) such as GPT, Claude, and Gemini are powerful tools that significantly increase developer productivity. However, they share a fundamental limitation: their knowledge is restricted to the time of their training. For example, an LLM trained in early 2024 will not be aware of new frameworks, events, libraries, or any new information that emerges in 2025 or beyond unless it is updated. MCP was designed to close a critical gap in the AI coding assistant ecosystem. It allows AI assistants to go beyond code generation.

MCP is an open standard that was introduced by Anthropic in November 2024. It enables LLMs to connect to various data sources, tools, and APIs, thereby fetching realtime information or performing tasks that exceed their built-in knowledge.

What Makes a Good MCP for Rust Developers?

When evaluating an MCP server for Rust development, it is essential to keep a few key criteria in mind:

Rust-Native Workflows: Does the MCP work smoothly with Cargo and popular frameworks like Axum, Actix-Web, or Rocket? The best servers will integrate effectively with the existing Rust ecosystem.
AI Assistant Compatibility: Can your AI assistant access the MCP server, either through LLMs or a developer IDE? Developers should consider how the MCP will fit into their current workflow. Ideally, the MCP should support both IDE and LLM integrations.
Security and Access: Security is a crucial factor when choosing the right MCP. Developers need to be confident that their secrets are kept safe and that the MCP server avoids unnecessary privilege escalation.
Setup Complexity: A good MCP server should be simple to configure and use. It shouldn't require complex installation steps, whether in an IDE or through an LLM.
Deployment Capability: Can the MCP server assist with end-to-end deployment, beyond just code generation? The best MCPs should be able to generate code, build, test, package, and even deploy Rust applications directly from an IDE.

With these criteria in mind, let's look at the seven most common MCP servers Rust developers actually use.

The 7 Most Common MCP Servers for Rust Developers

Here is a list of popular MCP servers that are particularly useful for Rust development.

1. Context7 MCP Server

Context7 MCP Server addresses one of the most critical challenges in AI-assisted Rust development: outdated and hallucinated documentation. When working with Rust's rapidly evolving ecosystem, developers often encounter AI assistants that generate code based on year-old training data, leading to deprecated APIs, incorrect function signatures, and non-existent methods.

Context7 solves this by providing real-time access to up-to-date, version-specific documentation directly from the source. For Rust developers, this means accurate code examples for popular crates like Axum, Tokio, Serde, and emerging libraries that weren't in the AI's training data.

The main advantage is eliminating the frustration of debugging AI-generated code that uses outdated APIs. Instead of spending time fixing deprecated methods or non-existent functions, developers can trust that the AI assistant has access to current documentation and working code examples.

2. Docker MCP Server

Docker MCP Server is ideal for Rust developers managing complex dependencies or building applications that require isolated environments. By running a Rust project inside a Docker container, the AI assistant can conveniently perform builds, run tests, and refactor code in a secure and reproducible way. Developers can easily reproduce builds and dependencies consistently without affecting the other parts of the codebase.

Developers can also run commands inside the Docker container, such as cargo build, with confidence that the results will be identical in both production and non-production environments. This consistency is helpful when resolving dependency-related build problems.

Rust developers can leverage pairing Docker MCP with File system MCP to streamline their day-to-day coding activities and automate a smooth workflow. Docker MCP is best used for integration testing, Continuous Integration workflow, or sandbox experimentation.

3. GitHub MCP Server

Rust developers derive the most benefits from using the GitHub MCP server when their code repository is hosted on GitHub. This MCP server automates workflows such as setting up Continuous Integration (CI) pipelines with GitHub Actions and managing releases. Developers can ask their AI assistant to handle tasks such as bumping crate versions, generating and maintaining changelog files, and other routine repository management tasks.

The GitHub MCP Server is tightly coupled to GitHub, which means that its full capabilities are only available within the GitHub ecosystem. Teams hosting their code on GitLab, Bitbucket, or other platforms may not find the GitHub MCP server as useful. The GitHub MCP Server is best used when paired with Docker MCP to provide a complete workflow from development to deployment.

4. File System MCP Server

The File System MCP Server provides the AI assistant with direct access to read, write, and modify Rust project files. This allows Rust developers to perform tasks such as refactoring code, automatically fixing errors in the codebase, creating new features, and updating Rust files accordingly.

When using the MCP server, developers should have measures in place to track which files that have been modified by the assistant. Combined with GitHub MCP server, version control can be implemented, making it easier to track the changes introduced by File system MCP. For example, an AI assistant could create a new feature, test it within a Docker container, and then set up a CI workflow using GitHub's MCP; this demonstrates how Docker, GitHub, and File System MCP can all work together.

5. Memory MCP

Memory MCP stores project-specific knowledge across sessions, making it easier for an AI assistant to remember naming conventions, coding standards, and recurring compiler errors. For Rust developers working across different teams or modules, this helps to enforce consistency and maintain project wide standards.

The main limitation is that the MCP is bound to a single context, which may restrict productivity in large projects that demand switching between multiple contexts. However, when paired with File System or Docker MCP, it can guide developers or an AI assistant during editing or refactoring, ensuring modifications align with the project standard.

6. Browsing MCP

Browsing MCP gives the AI assistant realtime access to external information such as crates documentation, Rust official documentation, or usage examples. This MCP is beneficial when working on a task and needing to look up an example implementation or consult documentation without leaving the development workflow.

The main limitation is that Browsing MCP can not modify the file system directly. When combined with other MCPs, such as File System or Docker MCP, the AI assistant can utilize the information it discovers to apply it to the project by creating code, updating files, or testing changes.

7. Shuttle MCP

Shuttle MCP is tailored for deploying Rust applications, such as Axum, Actix, or Rocket. For a development team focused on rapid iteration, this MCP allows developers to deploy the application quickly from code to a live environment. Developers can concentrate on writing code while Shuttle handles server setup, SSL certificate management and deployment.

Shuttle focuses on Rust projects and it integrates smoothly with Rust ecosystem. When combined with Docker and File System MCPs, developers can build and test their Rust projects locally. Then deploy to live environment with Shuttle, providing a smooth and end to end workflow

The Challenges of Managing Multiple MCPs

Using individual MCPs can help accelerate developer productivity, but managing multiple MCPs simultaneously introduces additional complexity. Here are some of the challenges I have encountered while working with various MCPs.

Resource Management and Performance

When working with multiple MCP servers, there is always the possibility that they will compete for system resources such as CPU and memory. In large Rust projects, this competition can negatively impact IDE performance. It becomes a significant bottleneck when projects rely heavily on multiple MCP servers.

To ensure you get the most out of these MCPs while still maintaining top performance in your Rust projects, here are a few best practices to follow:

Monitor and limit resource usage: Carefully track CPU and memory usage and limit the number of active MCPs to prevent overload.
Allocate CPU and memory per MCP: Assign specific resources to each MCP server to ensure no single server dominates system resources.

Security and Authentication Complexity

As a developer, when I want to use an MCP server, each server requires its own authentication and security setup. When multiple MCP servers, such as Docker, GitHub, file system, and browsing MCPs, are running simultaneously, managing all the secrets, API keys, access tokens, and security configurations can become challenging. If one MCP is compromised or becomes vulnerable, it could put the entire MCP setup at risk.

To make multiple MCPs safe for use, you can do the following:

Implement strict isolation between servers to prevent a compromised MCP from affecting others. This can be achieved by:
- Running each MCP on its own container or virtual machine.
- Storing secrets or API Keys in a dedicated, secure vault with a separate namespace, so that if one secret is compromised, it does not affect others.
Perform regular secret rotation, for example, yearly or quarterly, to minimize the risk of leaked credentials.
Continuously monitor the environment for any suspicious activity.

The real challenge arises when developers need to use multiple MCP servers simultaneously, such as Docker and GitHub. Each server has its own authentication, logs, and configuration, which can quickly turn into an overwhelming experience. Without a unifying layer, developers end up spending more time managing connections than actually building.

How MCP Aggregators and API Gateways Solve These Problems

As a developer, I want a solution that enables me to leverage multiple MCP servers with my AI assistant, unifying different tools and data sources into a single, seamless workflow. Platforms like Lunar.dev, along with other MCP aggregators such as Solo.io and MCP Bridge, help tackle the complexity of managing multiple MCP servers. These platforms act as middleware, allowing you to configure various MCPs through a single interface.

Here is how MCP aggregators help:

Unified logging: Developers can view a stream of logs from multiple MCP servers, which is more helpful in debugging than viewing logs from a single MCP server.
Security monitoring and access control: Aggregators provide fine-grained access control, making it easier to identify which permissions are granted to a specific developer.
Performance optimization and caching: Frequently accessed or requested results can be cached at the aggregator level, reducing latency, improving response times for developers, and ultimately saving time.

Rust developers can increase their productivity by integrating AI-assisted workflows into their ecosystem. These aggregators add tremendous value by simplifying integration, reducing overhead, and maintaining a secure and performant development environment, allowing engineers to focus on building code.

How Shuttle Solves the Deployment Problem

Rust developers are currently facing a significant challenge with deployment. With the assistance of AI in accelerating the generation of code, deploying Rust projects to live environments often requires extra steps compared to other languages like Python or Node JS, which benefits from a mature Platform as a Service (PaaS) solutions, strong community support and extensive resources. On the other hand, Rust ecosystem is still evolving with fewer tutorials, deployment focused tools and best practices available.

You may have generated clean Axum handlers, written comprehensive tests, and even have users waiting for your feature. Yet the moment you are ready to deploy, you are forced into manual deployment processes.

The current deployment workflows for Rust applications require developers to:

Set up cloud infrastructure
Set up monitoring and logging
Handle SSL certificates and domain configuration

There should be a workflow that allows developer to deploy their Rust project directly from their IDE.

Shuttle MCP enables Rust developers to deploy applications directly from their IDE by integrating with Shuttle CLI, which requires a separate installation. This approach boosts productivity by removing the manual steps involved in traditional deployment. Shuttle packages, compiles, and deploys your application automatically, so that you can stay focused on building.

Unlike other solutions that requires complex scripts or Infrastructure as a Code (IaC) configurations which rely on YAML files or provider specific configuration. Shuttle follows an Infrastructure from Code (IfC) approach, which means that your infrastructure is defined directly in your Rust codebase alongside with the application logic.

You can ask your AI assistant to:

Deploy your Axum API to the live environment
Check the logs of the deployed service

Hands-on Example: Build and Deploy a Snippet Sharing API with Shuttle

In this hands-on section, we'll build a Rust + Axum API that powers a simple code snippet sharing service (similar to Pastebin) and demonstrate how to fetch documentation with Context7 MCP Server, create a pull request with GitHub MCP Server and deploy the Rust code using Shuttle MCP Server, with Cursor AI assistance.

The API will include:

Endpoints to create and retrieve snippets
Filtering snippets by programming language
Clean, shareable URLs with 8-character IDs

API Endpoints

Method	Endpoint	Description
GET	/health	Health check endpoint
POST	/snippets	Create a new code snippet
GET	/snippets	List all snippets
GET	/snippets/{id}	Get a single snippet
DELETE	/snippets/{id}	Delete a snippet

Step 1: Setting Up Your Environment: Install Rust and Shuttle CLI

Firstly, ensure you have the following software running:

Rust and Cargo: For local development and testing.
Shuttle CLI: For deployment into a live environment. You can install it via Cargo, or use the installation script by following this link: Shuttle CLI Installation.
Cursor: An AI coding assistant. We will use it to interact with MPC Servers (Context7, GitHub and Shuttle) for documentation lookup, creating PRs and deploying the Rust application.

Step 2: Log in to Shuttle

Authenticate your Shuttle account:

shuttle login

This connects your CLI to your Shuttle account, enabling authorized deployments.

Step 3: Setting Up Our Project

Next, we will create our Rust project. Below is an example of the Cargo.toml configuration. You can also generate the below file Cargo.toml by running the shuttle command shuttle init . Running the command will initializes a new Shuttle project in your current directory.

[package]
name = "code-snippet-sharing-app"
version = "0.1.0"
edition = "2021"

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
shuttle-axum = "0.57.0"
shuttle-runtime = "0.57.0"
shuttle-shared-db = { version = "0.57.0", features = ["postgres", "sqlx"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
uuid = { version = "1.0", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
nanoid = "0.4"
sqlx = { version = "0.8", features = [
  "runtime-tokio-rustls",
  "postgres",
  "chrono",
  "uuid",
] }

Step 3: Build the Rust Code Locally

Build the Rust code by running this command below to build the Rust project to confirm that there are no errors:

cargo build

Step 4: Run the Rust Code Locally

Run the Rust code by running this command below:

shuttle run

Step 5: Deploy your app

Now, let's deploy your application using Shuttle and see how it makes deployment easier by handling all the heavy lifting for you. We will be deploying the application using Shuttle MCP Server.

The URLs used in the following steps are examples. When you deploy your own application, Shuttle will provide you with a unique URL.

From your cursor IDE. Run the command on the prompt

#Prompt 
Deploy the Rust code

Use the Shuttle MCP server.

The AI assistant will deploy the application and a link will be generated. You can access your application with the provided link.

For instance, in this case, the link is https://code-snippet-share-ow2x.shuttle.app.

Shuttle will:

Package your code
Compile it in the cloud
Provision infrastructure
Manage SSL certificate
Deploy your app to a live environment

Step 6: Test Your App Deployed Using Shuttle: Health Endpoint

Let's test the application we deployed with Shuttle to ensure all the endpoints are working correctly.

Health Endpoint: https://code-snippet-share-ow2x.shuttle.app/health

You can use curl from the command line or a tool like Postman. In this example, we will use Postman.

Step 8: Test Your App Deployed Using Shuttle: POST Snippet Endpoint

Send a POST request to https://code-snippet-share-ow2x.shuttle.app/snippets with a JSON payload to create a new snippet record.

{
  "content": "A Hands-on Comparison of Best MCP Servers for Rust Developers",
  "language": "Rust",
  "title": "Shuttle MCP",
  "description": "Explore Shuttle MCP",
  "expires_in_hours": 24,
  "is_public": true
}

Step 8: Test Your App Deployed Using Shuttle: GET APl Snippet Endpoint

Send a GET request to https://code-snippet-share-ow2x.shuttle.app/snippets to retrieve all snippets.

Step 9: Test Your App Deployed Using Shuttle: GET a Single Snippet Endpoint

Send a GET request to https://code-snippet-share-ow2x.shuttle.app/snippets/qjs0BzAq to retrieve a specific snippet by its ID.

Step 10: Use GitHub MCP Server

We will explore how to use the GitHub MCP Server to create a Pull Request (PR) and manage the Rust project on GitHub.

# Prompt

Raise a PR with my new changes

Using GitHub MCP Server

Step 11: Use Context7 MCP Server

We will explore how to use Context7 MCP Server to ask questions about the Rust code and access documentation related to the project. In the example below, we demonstrate how to use Context7 MCP Server to ask a question and reference documentation "I need to reference a Rust documentation on how i can persistent snippet data instead of using in memory HashMap".

# Prompt 

I need to reference a Rust documentation on how i can persistent snippet data instead of using in memory HashMap.

Using context7 MCP

Wrapping Up

The MCP ecosystem is opening new possibilities for Rust developers. Whether you are managing repositories with GitHub MCP, restructuring projects through the Filesystem MCP, or streamlining research with the Browser MCP, each option reduces friction in its own way. By combining multiple MCP servers, AI assistants can support the entire application lifecycle, allowing developers to focus on writing Rust instead of wrestling with complex infrastructure tools.

Shuttle simplifies deployment, letting you build features, test ideas, and ship production-ready applications in minutes.

Ready to try this out for yourself? Run the following command to get started immediately:

shuttle init --from shuttle-hq/shuttle-examples --subfolder axum/code-snippet-sharing-app

Other ways to get started:

Sign up for Shuttle to start building with Shuttle.
Clone the repository used in this article to explore how to build with Shuttle.
Learn more about Shuttle to get started quickly.

Whichever MCP fits your workflow, Shuttle makes deploying Rust applications effortless.

Best AI Coding Tools for Rust Projects: IDEs vs Terminals

Shuttle — Thu, 11 Sep 2025 14:04:37 +0000

As Rust developers, we tend to rely on familiar setups like Visual Studio Code (VS Code) or the terminal because they offer the speed and control we need. AI coding tools extend these workflows but approach them in different ways. Some plug directly into IDEs, while others work in the terminal. If you are building Rust projects, the real question is which of these tools are actually useful in practice.

To find out, we tested five popular AI coding assistants by building the same Rust HTTP server with Axum. We compared how quickly they generated code, the quality of what they produced, and how well they fit into everyday Rust workflows.

Because each tool outputs code differently, we also needed a way to deploy their results without switching stacks or starting from scratch. We will walk you through how we solved that as well.

The table below summarizes the key differences between IDE-based and terminal-based AI coding tools:

Aspect	IDE-Based Tools	Terminal-Based Tools
Integration	Deep editor integration with real-time suggestions	Command-line focused with file system awareness
Workflow	Seamless coding experience within a familiar environment	Context-switching between the terminal and the editor
Context Awareness	Full project context with syntax highlighting	File-based context with smart project understanding
Learning Curve	Minimal - extends existing IDE workflow	Moderate - requires learning CLI commands
Collaboration	Individual developer focused	Often better for pair programming and code review
Customization	Limited to IDE extension capabilities	Highly customizable through configuration files

AI Coding Tools: IDEs vs. Terminals

Choosing an AI coding tool is about features, as well as matching the tool to how you think and work. Some developers thrive with constant AI suggestions appearing in their editor. Others find this distracting and prefer tools that allow them to describe a problem and then generate complete solutions. The divide between IDE-integrated and terminal-based tools reflects these different working styles.

What Are IDE-based AI Coding Tools?

IDE-based AI coding tools integrate directly into graphical Integrated Development Environments (IDEs). They enhance the development experience with intelligent code completion, refactoring, optimization, and debugging. Many also bring real-time suggestions, multi-file editing, project-wide refactoring, and built-in chat panels for natural language queries.

With IDE-based tools, you can expect:

Graphical Interface: Work inside a visual IDE with inline code suggestions, multiple views, and interactive chat panels for prompts.
Context-Based Suggestions: Get completions and refactoring ideas based on the IDE's deep understanding of your codebase.
Deep Integration: Leverage the IDE's ecosystem, including project navigation, file management, and version control, all enhanced by AI.
Higher Resource Usage: Keep in mind that graphical interfaces and IDE overhead usually demand more system resources.

Some of the most popular IDE-based AI coding tools are:

Cursor
Windsurf (formerly Codeium)
VS Code + GitHub Copilot
Kiro by AWS

Cursor:

Cursor is an AI-first code editor built with AI assistance at its core. It takes the familiar foundation of VS Code and layers in advanced AI capabilities, so you can work faster and smarter without giving up your usual workflow. If you've used VS Code before, you'll instantly recognize the interface and navigation, but you'll also see new tools that make coding feel collaborative.

Key features include:

Native AI Chat Interface: Talk to AI right inside your editor.
Multi-File Editing with AI: Edit across multiple files in one request.
Codebase-Wide Understanding: AI understands your whole project.
Custom AI Model Selection: Pick the AI engine that fits your needs.
Real-Time Code Generation: Code gets written as you type.
Smart Autocomplete: Smarter, context-aware autocomplete.

Windsurf (formerly Codeium):

Windsurf, rebranded from Codeium, is an AI-powered IDE forked from VS Code and designed to weave AI assistance throughout the entire code development process. Compared to Cursor, Windsurf leans toward a more polished and minimal aesthetic. You can think of it as Apple-like refinement compared to Microsoft's functionality-first approach.

One of Windsurf's standout features is Cascade, which enables true agentic programming. With Cascade, the AI can understand your project across multiple files and take coordinated action without requiring you to micromanage every step.

Key features include:

Intelligent Code Refactoring: Automatically clean up and restructure code without breaking functionality.
Architecture-Aware Suggestions: Get recommendations that fit your project's overall design.
Cross-Language Project Support: Seamlessly work across multiple programming languages.
Advanced Debugging Assistance: Understand errors and get targeted, multi-file fixes.
Code Quality Insights: Instant feedback on clarity, maintainability, and best practices.
Deep Static Analysis Integration: Catch hidden bugs, security risks, and performance issues early.

VS Code + GitHub Copilot:

GitHub Copilot is one of the most widely used AI coding assistants. It integrates directly into VS Code as well as other popular IDEs and works in real time to suggest code, generate functions from natural language prompts, and explain existing code. Whether you're writing in JavaScript, Python, Go, or working across multiple languages, Copilot blends seamlessly into your environment while tying neatly into the broader GitHub ecosystem.

Key features include:

AI-Powered Code Suggestions: Get instant code completions from single lines to full functions.
Natural Language to Code: Describe it in plain English, and let AI write the code.
Chat and Inline Assistance (Copilot Chat): Ask coding questions and get inline help without leaving your editor.
Code Explanation and Documentation: Turn complex code into clear explanations.
Test and Code Refactoring Support: Auto-generate tests and improve code readability safely.
Multi-Language and Framework Support: Works across dozens of languages and frameworks.
Integration with GitHub Ecosystem: Easily connects with repos, PRs, and Actions.

Kiro by AWS:

Kiro is an AI-native IDE built by AWS and launched in 2025. It was designed to solve the challenges of "vibe coding" by introducing structured, spec-driven development. With this approach, Kiro generates a requirements document that includes user stories, mermaid diagrams, acceptance criteria, and more about what you want to build. You can review the spec, tweak it, and customize it to your needs before writing a single line of code. This way, you don't have to keep prompting over and over to get what you're looking for.

Key features include:

Spec-Driven Development: Work from a single spec file that acts as your source of truth. AI agents generate, maintain, and evolve your code directly from it.
Customizable Agent Behavior: Fine-tune how agents operate using steering configs in .kiro/steering/. Set rules like avoiding blocking calls, enforcing structured logging, or running tests on every commit to keep quality consistent.
Automation Hooks: Add event-based automations to streamline your workflow. For example, regenerate scaffolding when specs change or trigger end-to-end tests when a pull request is opened.
Multimodal Chat Interface: Collaborate with AI through text, code, and other formats. Get natural help with debugging, explanations, and brainstorming.
Agentic Programming: Let AI agents handle multi-step tasks. They can plan projects, update specs, and keep changes synced across your codebase.
AWS Integration: Connect seamlessly with AWS services for deployment, monitoring, and scaling so your projects move smoothly into production.

The key difference between IDE-based AI coding tools is in their approach. Cursor, Windsurf, and Copilot focus on real-time code suggestions and inline assistance for quick iteration. Kiro, on the other hand, takes a different path with agentic, spec-driven workflows that emphasize production readiness and cut down on ad-hoc "vibe coding" chaos. This makes it more agent-led and customizable, giving teams the guardrails and automations they need instead of just editor-centric features.

What are Terminal-Based AI Coding Tools?

Terminal-based AI coding tools run entirely in the command-line interface (CLI), letting you work with AI models through simple commands and prompts. If you prefer a lightweight, text-driven workflow and often rely on Git or other version control systems, these tools will feel right at home.

With terminal-based tools, you can expect:

Command Line Interface: Operates fully in the terminal with commands and prompts, often with little or no GUI.
Lightweight and Fast: Uses minimal system resources, making it ideal for low-spec machines or headless environments such as servers.
Direct LLM Access: Connect directly to large language models (LLMs) like Claude, GPT, or Gemini, with support for multiple providers.
Git Integration: Streamline version control workflows by automatically committing changes to Git.
Automation-Focused: Excel at automating repetitive tasks, running tests, and executing commands without leaving the terminal.
Steeper Learning Curve: Requires comfort with command-line workflows and provides less visual feedback compared to IDE-based tools.

Popular terminal-based AI coding tools include:

Claude Code
Aider
Gemini CLI
OpenAI Codex CLI

Claude Code:

Claude Code is an AI coding assistant built to run directly in your terminal, designed for developers who want a hands-on but intelligent coding partner. You can delegate complex tasks to it, and it will plan, execute, and explain its work step by step. Whether you're writing new code, testing, debugging, or exploring a large codebase, Claude Code acts as an agentic AI that can navigate files, run multi-step processes, and integrate with your existing tools through natural conversation.

Key features include:

Natural Language Task Description: Describe what you want in plain English, and Claude handles it.
File System Awareness: Understands and edits your project's files in context.
Multi-Step Task Execution: Plans and completes tasks across multiple files seamlessly.
Flexible Configuration Management: Set up coding preferences and project rules using dotfile-style configuration with claude.md files. Configure global settings in your home directory, project-specific rules in your project root, or granular settings in subfolders for large projects. This hierarchical approach lets you define coding standards, architectural patterns, and team conventions that Claude will automatically follow.
Integration with Development Tools: Works smoothly with editors, build tools, tests, and version control.
Conversational Debugging: Debug interactively with step-by-step guidance.
Code Explanation and Documentation: Turn complex code into clear explanations and documentation.

Aider:

Aider is an open-source AI pair programming assistant built to work hand-in-hand with Git. Unlike other coding tools that simply suggest snippets, Aider operates inside your version control workflow, making it especially powerful for collaborative and production-grade projects. It uses large language models to understand your codebase, propose intelligent changes, and keep everything neatly tracked in commits.

Key features include:

Git-Aware Editing: Understands your Git context and suggests edits easily.
Multi-file Coordinated Changes: Update multiple files at once for consistent refactoring.
Automatic Commit Messages: Generate clear, descriptive commits automatically.
Support for Multiple AI Models: Choose the AI model that fits your project and workflow.
Real-Time Collaboration: Get live, pair-programmer-style coding suggestions.

Gemini CLI:

Gemini CLI is Google's lightweight, open-source AI coding agent that brings Gemini models (like Gemini 2.5 Pro) directly into your terminal. With an ascended context window of 1 million tokens, it can analyze entire codebases at once and handle complex workflows with ease.

Key features include:

Massive Context Window: Powered by Gemini 2.5 Pro, with support for up to 1 million tokens. This gives the AI a deep understanding of your codebase and enables full project analysis.
Real-time Web Search and Diagrams: Look up information on the web instantly and generate diagrams on the fly to speed up debugging and feature development.
Open-Source Flexibility: Fully open-source under Apache 2. You can customize it, extend it, and contribute back to the community.
Generous Free Tier: Get 60 requests per minute and 1,000 requests per day for free with just a personal Google account.
Security and Sandboxing: Runs in a secure, sandboxed environment with network restrictions, ensuring safe code execution.

OpenAI Codex CLI:

OpenAI Codex CLI is an open-source, lightweight coding agent that brings ChatGPT-level reasoning to your terminal. Powered by OpenAI's o3 and o4-mini models, it emphasizes local execution, privacy, and multimodal input, letting you handle tasks like code generation, file manipulation, and test execution directly from the terminal.

Key features include:

Multimodal Input: Supports text, screenshots, and diagrams to generate or edit code, making feature implementation faster and more intuitive.
Local Privacy: Runs entirely on your machine, keeping your source code private unless you choose to share it.
Flexible Approval Modes: Choose from Suggest, Auto-Edit, and Full Auto modes for different levels of control over code changes and command execution.
Open-Source and Community-Driven: Encourages community contributions and supports multiple AI providers like Gemini and OpenRouter via the Chat Completion API.
Sandbox Security: Executes commands in secure, sandboxed environments using Docker on Linux and Apple Seatbelt on macOS to ensure safe operations.

With the details of both IDE-based and terminal-based AI coding tools covered, let's now explore why they behave differently when you put them to work on a Rust project.

What Makes These Categories Behave Differently in Rust?

Rust's strict type system, borrow checker, and focus on safety make AI coding tools behave differently depending on how they integrate with your workflow.

IDE-based tools like Cursor, Windsurf, and GitHub Copilot hook directly into the Rust Language Server Protocol (LSP) through rust-analyzer. This means you get real-time, type inference, inline diagnostics, and borrow checker suggestions. The immediate feedback helps catch ownership issues or lifetime mismatches early, reducing compile cycles and making it easier to write idiomatic Rust code. These tools shine in visual debugging and refactoring, using the IDE's deeper understanding of Rust's semantics to speed up iteration in larger projects.

Pros and Cons of IDE-Based AI Tools in Rust Projects

Below are some of the benefits you get when you use IDE-based AI tools in your Rust projects:

Strong support for multi-file refactoring and debugging, reducing time on ownership issues.
Visual feedback and multi-view interfaces make navigating complex Rust projects easier.
Deep integration with rust-analyzer provides context-aware fixes for the borrow checker and type errors.
Seamless real-time suggestions and autocomplete help maintain flow during Rust's error-prone early stages.
While the visuals make it ideal for building and debugging large-scale projects, they still come with some limitations:
Reliance on a GUI makes them less ideal for headless or remote Rust environments, such as servers.
Higher resource consumption, which can slow things down on lower-spec machines during Rust compilations.

In contrast to IDE-based tools, terminal-based tools such as Claude Code and Aider lean on command-line interactions and external commands like cargo check or cargo build for validation. Instead of inline suggestions, they generate suggestions on-demand through prompts, which takes an agentic approach of planning and applying multi-file changes or automations in one go. This makes them powerful for strategic code generation or bulk edits, though you'll likely need more manual builds to catch errors. They're lightweight and well-suited for server-side or low-resource development environments, but can feel less intuitive when dealing with Rust's more intricate ownership and lifetime rules without visual aids.

Pros and Cons of Terminal-Based AI Tools in Rust Projects

Below are some of the benefits you get when you use terminal-based AI tools in your Rust projects:

Direct access to LLMs for in-depth explanations of Rust concepts without IDE overhead.
Strong reasoning capabilities for planning Rust architectures or algorithms.
Lightweight and fast, making them great for Rust development on servers or low-power devices.
Well-suited for automation and Git-integrated workflows, including running builds and tests via commands. While they are fast and less resource-intensive, they also come with some drawbacks:
Less immediate feedback, as validation depends on manual runs of cargo tools, which can slow iteration.
Steeper learning curve, since you'll need comfort with the CLI to handle Rust's verbose error messages.

Hands-On: Building a Rust API with Each Tool

Now it's time to put these tools to the test by building a task management API in Rust and seeing how each one handles the challenge.

Project Scope: Five REST endpoints (create_task, get_task, list_tasks, update_task, delete_task)

Architecture: In-memory store (no database, state held in-memory with a HashMap)

Toolchain: Rust 2024 edition, without pinned crate versions (axum, tokio, serde, uuid)

Evaluation Method: Each tool was tested with the same starting prompt. We recorded the generated code, its completeness and accuracy, and its integration into the Rust workflow.

Building with Cursor

We opened a folder rust-tasks-cursorin Cursor, launched the AI chat panel (Cmd/Ctrl + L) and entered the baseline prompt:

Create a new Rust project for a task management API using Axum

Cursor created a new Rust project structure that includes a Cargo.toml file with the required dependencies:

[package]
name = "task_manager_api"
version = "0.1.0"
edition = "2024"

[dependencies]
axum = "0.8.4"
hyper = "1.6.0"
serde = { version = "1.0.219", features = ["derive"] }
serde_json = "1.0.142"
tokio = { version = "1.47.1", features = ["full"] }
tower-http = "0.6.6"

It also generated a main.rs file with the API entry point.

use axum::{Json, Router, routing::get, serve};
use serde_json::json;
use std::net::SocketAddr;
use tokio::net::TcpListener;

async fn health_check() -> Json {
    Json(json!({ "status": "ok" }))
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/health", get(health_check));
    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("Listening on {}", addr);
    let listener = TcpListener::bind(addr).await.unwrap();
    serve(listener, app).await.unwrap();
}

Next, we refined the prompt in the chat panel to flesh out the endpoints:

Implement the complete task API with models, handlers, and main server setup

Cursor then updated the main.rs file with the API models, handlers, and expose the CRUD endpoints.

What worked:

Multi-file editing kept models, routes, and main in sync.
Inline fixes suggested after compiler errors.
Excellent for scaffolding large chunks of code fast.

What didn't:

Sometimes hallucinated crate versions.
Needed a re-prompt to get the right crates and correct some logic.

Verdict: Great for rapid prototyping and multi-file Rust projects, especially for developers comfortable with VS Code-style workflows.

Building with Windsurf

We created a rust-tasks-windsurf folder in Windsurf and used the same prompt. Windsurf scaffolded a Rust project but took longer due to its Cascade checks. The upside is that it proposed project structure refinements (splitting handlers.rs and routes.rs) and enforced pinned versions in Cargo.toml.

What worked:

Architecture-aware suggestions (modularized better than Cursor).
Helpful explanations for async/await and error handling.
Strong static analysis integration caught subtle mistakes.

What didn't:

Generation was slower (20-30s per major step).
Occasionally over-engineered (extra traits not needed for in-memory scope).

Verdict: Great for planning long-lived Rust projects where architecture matters.

Building with VS Code + GitHub Copilot

We created a new folder rust-tasks-copilot in VS Code and initialized the project by running the command below:

cargo init

Copilot helped fill in dependencies, models, and handler boilerplate as we typed. It excelled at incremental completions but required additional guidance to assemble the full API.

What worked:

Excellent line-by-line and function-level completions.
Copilot Chat explained compiler errors clearly.
Fastest at suggesting snippets.

What didn't:

Weak at cross-file consistency (needed manual edits to sync model types).
Less effective at scaffolding entire APIs in one shot.

Verdict: Great for incremental coding and filling gaps rather than full project generation.

Building with Claude Code

In Claude, we entered the same prompt in the terminal. Claude generated a project scaffold, listed the steps it would take, then produced Cargo.toml and main.rs. It explained async concepts and ownership trade-offs in detail while building.

What worked:

Clear step-by-step reasoning.
Accurate async handling with axum.
Strong at explaining lifetimes and error messages.

What didn't:

Slower to reach a runnable version (lots of intermediate narration).
Sometimes verbose in generated comments, cluttering code.

Verdict: Great for learning Rust while building (doubles as tutor + generator) and building large-scale projects.

Building with Aider

For this, we initialized Git and prompted Aider. It scaffolded a Cargo project, generated dependencies, and committed each step with descriptive messages. Its Git-aware workflow was unique: each file edit was atomic, with matching commit messages.

What worked:

Excellent Git integration (perfect history for each change).
Multi-file updates stayed consistent.
Easy rollback when things went wrong.

What didn't:

Required more prompt iteration than Cursor/Windsurf.
Less context than IDE-native tools (sometimes needed manual cargo fixes).

Verdict: Great for collaborative, Git-driven workflows in Rust.

If you're weighing up any of the AI coding tools against each other, here's a quick reference to help decide which fits best in different contexts:

Tool	Category	Code Quality	Best For
Cursor	IDE	9	Fast prototyping, full-feature builds
Windsurf	IDE	8.5	Architecture planning, complex logic
Copilot	IDE	8	Incremental completions, patterns
Claude Code	Terminal	9	Learning and explaining Rust and large-scale projects
Aider	Terminal	8.5	Git-aware, team-oriented dev

Using AI to generate Rust code can be powerful, but even the best tools have their blind spots. IDEs may overlook context rules, terminal tools can feel slower, and both risk introducing subtle bugs if not monitored. The gap between a quick prototype and a maintainable project often comes down to workflow design, rule enforcement, and consistent testing. In the next section, we'll cover best practices for getting the most out of AI coding tools so your Rust projects stay reliable, predictable, and scalable.

Best Practices for Getting the Most from AI Coding Tools

AI coding tools can feel like magic, but to get reliable Rust projects, you need guardrails. Start by treating your project like a product. Define the kinds of documents a PM would normally create: project rules, coding standards, API conventions, and so on. A practical approach is to create claude.md files (or equivalent) for each directory, describing the rules explicitly, and load them into the AI's context. This makes it much easier for any AI tool to generate code within your intended scope, especially in larger projects.

Next, build testing discipline into your workflow. AI is excellent at TDD, but it will not enforce policy on its own. For example:

Run unit tests after every code step.
Run end-to-end tests after major milestones.
Avoid mocks and stubs unless absolutely necessary.

These practices help reduce subtle errors that AI tools can introduce. Keep in mind that IDE-based tools such as Cursor, Copilot, and Windsurf sometimes ignore context-loaded rule files. CLI-based tools combined with dotfiles tend to respect them more consistently. That is why CLI workflows can be especially valuable for large or complex Rust projects.

Security and permissions are another important consideration. CLI tools usually give you fine-grained control. You can grant permissions per command, or opt in to full access with flags like --dangerously-skip-permissions in Claude CLI. IDEs, by contrast, often require broader access and provide fewer safeguards.

Cost is also a factor. CLI tools typically consume tokens directly from your AI subscription, which can add up quickly on big projects. IDEs such as Cursor or Windsurf let you switch between models, but the most capable ones often sit behind pay-as-you-go tiers that can exceed $1,000 for heavy usage. Anthropic Max, for example, offers a predictable monthly price with a token reset system. This makes budgeting easier for long-term Rust projects.

In short, enforce guardrails, define clear rules, and think like a PM. With that mindset, both IDE and CLI AI environments will work more predictably, generate higher-quality Rust code, and integrate smoothly into your deployment pipeline.

How We Deployed the Rust Applications

Each tool got us to a working Rust API, but in different ways. Some needed a bit of re-prompting, while others were more direct. Instead of setting up separate Dockerfiles, CI pipelines, or custom cloud configs for each tool, we kept things simple with a single deployment workflow powered by Shuttle's Model Context Protocol (MCP). Here's how you can do the same:

Set up Shuttle:

Create a free Shuttle account.
Install the Shuttle CLI, which lets you deploy straight from your machine.
Configure the CLI by running:

  Shuttle login

This will open a browser where you can log in with your credentials.

Connect your AI Coding Tool to Shuttle MCP:

Add the Shuttle MCP server to your tool of choice. For example, in Windsurf:

Go to Settings → Windsurf Settings → Manage MCPs → View raw config.

Paste the server configuration below into the config file:

{
  "mcpServers": {
    "Shuttle": {
      "command": "shuttle",
      "args": ["mcp", "start"]
    }
  }
}

Check Shuttle's documentation for the full list of MCP configurations.

Prompt the Tool to Deploy:

Now, ask your AI coding tool to deploy the API through the Shuttle MCP server. For example:

Deploy the API to Shuttle.

Use the Shuttle MCP server.

As a rule of thumb, always include the phrase _Use the Shuttle MCP server. when deploying through the Shuttle MCP server so it can reference the documentation during deployment._

Let the Tool Update your Project:

When you run the prompt, the tool will update your project for deployment on Shuttle. This includes updating Cargo.toml to add the required dependencies:

shuttle-axum = "0.56.0"
shuttle-runtime = "0.56.0"

It will also update the main function to use the Shuttle runtime:

#[shuttle_runtime::main]
async fn main() -> shuttle_axum::ShuttleAxum {
    let app_state = AppState::new();
    let app = Router::new()
        .route("/tasks", get(get_tasks).post(create_task))
        .route("/tasks/{id}", get(get_task).put(update_task).delete(delete_task))
        .route("/health", get(health_check))
        .layer(CorsLayer::permissive())
        .with_state(app_state);
    Ok(app.into())
}

View your Deployment:

Finally, open your Shuttle console to grab your API URL and other deployment artifacts.

Beyond Deployment with Shuttle

Shuttle goes further than just deployment. It provides tools and resources that make day-to-day development smoother and more productive:

Ready-to-deploy resources like databases and built-in secrets for managing environment variables.
Low-effort prototyping and framework support, so you can spin up projects quickly with Axum, Actix, Rocket, and more.
Community-driven development and support, with an active open-source community, Discord, and programs to support your workflow.
Fast redeploys and local iteration, making it easy to test changes without waiting on long build times.
Infrastructure as Code (IaC) powered by Rust macros, which means your infrastructure lives directly inside your Rust code instead of separate config files.

Wrapping Up

The AI coding landscape for Rust is more powerful and flexible than ever. Whether you prefer the visual depth of IDE-based tools or the speed and focus of terminal applications, there's a tool that matches your style.

One thing that never changes is the importance of Rust's core principles. The best AI tool for coding is the one that helps you write idiomatic, safe, and performant Rust while fitting naturally into your workflow.

Whatever tool you choose, Shuttle makes building and deploying your applications effortless. Ready to see it in action? Run this command to get started with a simple Axum web server:

shuttle init --from shuttle-hq/shuttle-examples --subfolder axum/hello-world

How to Build and Deploy an SSE MCP Server with OAuth in Rust

Shuttle — Mon, 01 Sep 2025 16:19:54 +0000

AI agents have become integral to modern development workflows, transforming how we build and maintain software. While these tools are already powerful, they reach their full potential when enhanced with MCP (Model Context Protocol) servers that extend their capabilities through specialized tools and integrations.

For developers running hosted applications or platforms, MCP servers offer a unique opportunity to provide users with natural language interfaces to your services. Consider a project management platform: instead of navigating through multiple screens, users could authorize an MCP server and then create tasks, update project statuses, or generate reports using simple conversational commands through their preferred AI client.

Building secure MCP servers requires adherence to two critical standards: the Model Context Protocol specification and OAuth 2.1. When implemented correctly, your MCP server becomes universally compatible with any MCP-enabled AI tool—whether users prefer Cursor, Claude Desktop, Windsurf, or other platforms.

This tutorial provides a comprehensive guide to OAuth authentication patterns and walks through building a production-ready MCP server. We'll implement secure authentication flows that allow AI agents to safely interact with your hosted services, then deploy the complete solution using Shuttle's streamlined cloud deployment.

MCP Transport Types

MCP servers use two transport mechanisms: STDIO (standard input/output) and SSE (Server-Sent Events). The stdio transport runs as a local subprocess and communicates through standard input/output streams, which we covered in detail in our comprehensive guide to building stdio MCP servers in Rust. SSE transport type servers, on the other hand, use HTTP-based communication with Server-Sent Events for real-time messaging.

SSE servers operate as cloud-hosted services, making them accessible from anywhere with proper network connectivity. Users don't need to install anything locally—they can access your MCP server through a simple URL. SSE transport type servers integrate directly with your existing backend infrastructure and support robust authentication mechanisms like OAuth 2, enabling secure access control and user management.

This tutorial focuses on building an SSE MCP server with OAuth—the cloud-based approach that connects to your backend application and provides authenticated access to your services.

Understanding OAuth 2 for MCP Servers

In order for users to authorize their MCP clients and AI agents to perform actions on their behalf, MCP servers must implement OAuth 2 specifications. In this section, we'll dive deep into the OAuth 2 requirements, what MCP clients expect, and what the flow looks like.

OAuth Flow

The OAuth flow consists of five key phases:

Discovery Phase: Client discovers authorization server metadata
Registration Phase: Client registers itself with the authorization server
Authorization Phase: User consent and authorization code generation
Token Exchange: MCP client exchanges the authorization code for an access token and refresh token
Authenticated Access: Using access tokens to connect to the protected MCP SSE endpoints

OAuth 2 Flow Deep Dive

OAuth might seem intimidating at first glance, but it's actually a straightforward flow once you understand the components. Let's dive into the OAuth flow.

Step 1: Discovery Phase (Metadata Endpoint)

For MCP clients to discover your authorization server endpoints, we need to create a well-known route that MCP clients will always query before starting the authentication flow.

MCP clients query the /.well-known/oauth-authorization-server endpoint to retrieve the Authorization Server Metadata (RFC 8414). This JSON document lists your OAuth 2.0 endpoints, grant types, and scopes. Implementing it is mandatory. Without it, MCP clients can't authenticate with your server.

The metadata endpoint provides important information to the MCP client, such as:

Registration endpoint: The route where MCP clients can register themselves with your authorization server.
Authorization endpoint: The MCP client will redirect the user to this route so that the user can manually review the authorization request and approve or reject it.
Token endpoint: After the user approves the authorization request, the MCP client will exchange the authorization code (generated by the server in the previous step) for an access token, this token will be used for authenticated requests from the MCP client to the MCP server.

Step 2: Registration Phase

During the initial connection setup, the MCP client first discovers the authorization server endpoints via the metadata endpoint, then makes a request to the registration endpoint, providing relevant information about itself. The server saves this information in the database and responds with a client ID and client secret for the MCP client.

Step 3: Authorization Phase (User Consent)

The first time an MCP server is added to an MCP client, the server cannot be used until the user authenticates with it, here is an example of how the Notion MCP server looks in Cursor:

When the user clicks on the Login button through their MCP client, the MCP client will redirect the user to the authorization endpoint that was provided using the metadata endpoint.

The user can then authenticate using their existing account and approve the authorization request. After successful authentication, the server redirects the user back to the MCP client with an authorization code in the URL.

Step 4: Token Exchange

After the user approves the authorization request, the MCP client immediately uses the authorization code to make a request to the token endpoint, exchanging the code for an access token and refresh token. The access token authenticates the MCP client to the MCP server, while the refresh token renews the access token when it expires.

The MCP client will now be able to make authenticated requests and ready for use.

Step 5: Authenticated Access

The MCP client with the use of the access token will now be able to connect to the MCP server and the MCP server will have the ability to identify the MCP client and the user that authorized it.

Refreshing the Access Token

The refresh token is used to renew the access token when it expires. The token endpoint must be designed to support both the refresh token grant type and the authorization code grant type, which we'll implement later in the tutorial.

Building and Deploying an SSE MCP Server in Rust

Now that we have a solid understanding of MCP servers and OAuth integration, we'll build a production-ready SSE MCP server that fully complies with both the MCP protocol and OAuth 2 specifications.

After building and testing the MCP server, we'll then deploy it to the cloud using Shuttle with just a single command.

You can find the complete code for this project in the GitHub repository.

Prerequisites

To follow along, you'll need:

Intermediate Rust familiarity (async/await, Axum, traits)
Basic OAuth concepts (auth codes, tokens, etc.)
Experience with PostgreSQL and SQLx

This tutorial focuses on key patterns. For the complete, unabridged code, please refer to the accompanying repository.

Using the MCP Inspector

The MCP inspector is a tool provided by the MCP team to help you test and debug your MCP server. You need Node.js and npm installed on your machine to run it. Execute the following command to install and run the MCP inspector in your terminal:

npx @modelcontextprotocol/inspector

This will automatically open the inspector in your default browser:

We'll use the MCP inspector to test our OAuth flow at each stage of the tutorial

Click the "Open Auth Settings" button which will open the auth settings page that tests the OAuth steps.

First, we'll implement the metadata endpoint. We'll build our server using the official rmcp crate and Axum, which are compatible out of the box.

Add the rmcp crate to your Cargo.toml file:

[dependencies]
rmcp = { version = "0.5", features = ["server", "transport-sse-server", "auth"] }

The feature flags are self-explanatory: we need the server flag to build an MCP server (not a client), transport-sse-server for SSE transport functionality, and auth for OAuth server utilities.

In our main.rs file, we have Shuttle boilerplate code that provisions a PostgreSQL database in production and implements the Shuttle Service Trait to get the socket address and run the MCP server, The Service trait ensures that the code will work in both development and production environments. We'll write the rest of the code in the init.rs file as the entry point for our backend server which will serve the authentication APIs and the MCP server endpoints.

struct McpSseService {
    pool: PgPool,
    secrets: shuttle_runtime::SecretStore,
}

#[shuttle_runtime::async_trait]
impl shuttle_runtime::Service for McpSseService {
    async fn bind(self, addr: SocketAddr) -> Result<(), shuttle_runtime::Error> {
        init::init(addr, self.pool, self.secrets).await
    }
}

#[shuttle_runtime::main]
async fn main(
    #[shuttle_shared_db::Postgres(
        local_uri = "postgres://postgres:password@localhost:5432/mcp-sse-auth"
    )]
    pool: PgPool,
    #[shuttle_runtime::Secrets] secrets: shuttle_runtime::SecretStore,
) -> Result<McpSseService, shuttle_runtime::Error> {
    Ok(McpSseService { pool, secrets })
}

We use the shuttle_shared_db::Postgres macro to provision a PostgreSQL database in production and local_uri to connect to a local database for development purposes only. The shuttle_runtime::Secrets macro is used to access secrets from the Secrets.toml file for development as well as deployment, which we'll create in the next step.

The init() function contains all the rmcp boilerplate required to spin up the SSE transport MCP server. You can view the complete implementation here.

Creating the Secrets File

Shuttle uses Secrets.toml files to store project secrets. We'll create two files: Secrets.toml for production and Secrets.dev.toml for development in the project root. We'll use the openssl command to generate a random JWT secret key. Run the following command to generate a secure key:

Security Note: Never commit your Secrets.toml files to version control. Add them to your .gitignore file to prevent accidental exposure of sensitive information.

openssl rand -base64 32
# Output: sQGnE/aD76G2TAJA6HqJk9shkmYwsmwZ3b+sJlQWBVE=

Update your Secrets.dev.toml file, e.g.

BASE_URL = "http://localhost:8000"
JWT_SECRET = "sQGnE/aD76G2TAJA6HqJk9shkmYwsmwZ3b+sJlQWBVE=" # Replace with your own JWT secret key

You can get your production URL by navigating to the Shuttle Console and bootstrap a new project. The URL will be displayed in the console.

Generate another random JWT secret key and update your Secrets.toml file as well, e.g.

BASE_URL = "https://your-project.shuttle.app" # Add your production URL here
JWT_SECRET = "FgaRCPwUd86iRwQsAm9faAky59ghk0c3bhSijz9wbAM=" # Replace with your own JWT secret key

Running the Development Server

After Shuttle and rmcp boilerplate is set up, we can run the development server:

shuttle run --secrets Secrets.dev.toml

For an auto-reload development server, you can use cargo-watch to run the following command:

cargo watch -x "shuttle run --secrets Secrets.dev.toml"

This automatically restarts the server when you make code changes. You'll need to install cargo-watch first by running cargo install cargo-watch --locked.

Excellent! Our MCP server is now running on http://127.0.0.1:8000 and we can test it using the MCP inspector.

Update your MCP inspector to use the correct MCP server URL, in our case it's http://127.0.0.1:8000/mcp/sse:

The reason our MCP server is running on http://127.0.0.1:8000/mcp/sse is because how we configured the the rmcp boilerplate code:

let sse_config = SseServerConfig {
    bind: addr,
    sse_path: "/mcp/sse".to_string(),
    post_path: "/mcp/message".to_string(),
    ct: CancellationToken::new(),
    sse_keep_alive: Some(Duration::from_secs(15)),
};

Using this configuration, we've specified the MCP server to run on http://127.0.0.1:8000/mcp/sse.

Setting Up the Metadata Endpoint

Clients can connect to the server but can't authenticate yet. To fix this, we'll start with the discovery phase by implementing the /.well-known/oauth-authorization-server route. Clients use this endpoint to fetch auth metadata, and since rmcp is compatible with Axum, we can easily create this route to return a JSON response.

According to the OAuth 2 specification, the metadata is expected to include the following fields:

issuer: The base URL of the authorization server. e.g. https://my-app.shuttle.app.
registration_endpoint: MCP clients can register themselves with the authorization server.
authorization_endpoint: MCP clients will redirect the user to this route so that the user can manually review the authorization request and approve or reject it.
token_endpoint: MCP clients will use this route to exchange the authorization code for an access token and refresh token, this route will be re-used for refreshing the access token when it expires.
scopes_supported: The scopes supported by the authorization server. e.g. profile, email, mcp.
additional_fields: Additional fields that can be used to customize the authorization server (according to the RFC 8414).
jwks_uri: The URL of the JSON Web Key Set (JWKS) endpoint, this is optional and can be omitted if not needed.

Let's implement the metadata endpoint:

pub async fn oauth_authorization_server(State(state): State<Arc<AppState>>) -> impl IntoResponse {
    let base_url = state
        .secrets
        .get("BASE_URL")
        .expect("BASE_URL secret not found");

    let mut additional_fields = HashMap::new();
    additional_fields.insert(
        "response_types_supported".into(),
        Value::Array(vec![Value::String("code".into())]),
    );
    additional_fields.insert(
        "code_challenge_methods_supported".into(),
        Value::Array(vec![Value::String("S256".into())]),
    );

    let metadata = AuthorizationMetadata {
        issuer: Some(base_url.clone()),
        registration_endpoint: format!("{base_url}/oauth/register"),
        authorization_endpoint: format!("{base_url}/oauth/authorize"),
        token_endpoint: format!("{base_url}/oauth/token"),

        scopes_supported: Some(vec!["profile".to_string(), "email".to_string()]),
        jwks_uri: None,
        additional_fields,
    };

    (StatusCode::OK, Json(metadata)).into_response()
}

We've added the following fields to advertise our support for the Authorization Code grant with PKCE (S256), in compliance with RFC 8414.

let mut additional_fields = HashMap::new();
additional_fields.insert(
    "response_types_supported".into(),
    Value::Array(vec![Value::String("code".into())]),
);
additional_fields.insert(
    "code_challenge_methods_supported".into(),
    Value::Array(vec![Value::String("S256".into())]),
);

Let's test it with the MCP inspector:

Excellent! The metadata endpoint is working. Now let's implement the registration endpoint.

Setting Up the Registration Route

After using the metadata endpoint, MCP clients register themselves by sending a request to the Register Route. The server saves the client's information to the database and responds with a client_id and client_secret.

First, we need a helper function to generate secure client secrets:

fn generate_client_secret() -> String {
    use std::fmt::Write;
    let mut secret = String::new();
    for _ in 0..32 {
        let byte: u8 = rand::random();
        write!(&mut secret, "{byte:02x}").unwrap();
    }
    secret
}

Now the registration handler:

#[derive(Debug, Deserialize)]
pub struct ClientRegistrationRequest {
    pub client_name: Option<String>,
    pub redirect_uris: Vec<String>,
    pub scope: Option<String>,
}

pub async fn client_registration(
    State(state): State<Arc<AppState>>,
    Json(request): Json<ClientRegistrationRequest>,
) -> impl IntoResponse {
    // Validate redirect URIs
    if request.redirect_uris.is_empty() {
        return (StatusCode::BAD_REQUEST, Json(serde_json::json!({
            "error": "invalid_request",
            "error_description": "redirect_uris is required and must not be empty"
        }))).into_response();
    }

    // Generate client credentials
    let client_id = Uuid::new_v4().to_string();
    let client_secret = generate_client_secret();
    let client_name = request
        .client_name
        .unwrap_or_else(|| "MCP Client".to_string());
    let issued_at = chrono::Utc::now().timestamp();
    let expires_at = chrono::Utc::now() + chrono::Duration::days(90);

    // Store client in database
    let query_result = sqlx::query!(
        r#"
        INSERT INTO mcp_clients (client_id, client_secret, client_name, redirect_uris, client_secret_expires_at)
        VALUES ($1, $2, $3, $4, $5)
        "#,
        client_id,
        client_secret,
        client_name,
        &request.redirect_uris,
        expires_at
    )
    .execute(&state.pool)
    .await;

    match query_result {
        Ok(_) => {
            let response = ClientRegistrationResponse {
                client_id: client_id.clone(),
                client_secret,
                client_name,
                redirect_uris: request.redirect_uris,
                scope: "mcp".to_string(),
                client_id_issued_at: issued_at,
                client_secret_expires_at: expires_at.timestamp(),
            };
            (StatusCode::CREATED, Json(response)).into_response()
        }
        Err(e) => {
            error!("Failed to register client: {}", e);
            (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(serde_json::json!({
                    "error": "server_error",
                    "error_description": "Failed to register client"
                })),
            )
                .into_response()
        }
    }
}

Let's test our registration endpoint to make sure it's working correctly.

The registration endpoint is working. Now let's implement the authorization endpoint.

Setting Up the Authorization Endpoint

The authorization endpoint shows the user a consent screen with the requested scopes. When the user clicks "Allow," the server does three things:

Generates an authorization code.
Saves the code to the database.
Redirects the user back to the client with the code. Finally, the client exchanges this authorization code for an access token and a refresh token.

Note: In a real-world app, you would require users to be logged in before they see the consent screen, the authorize_get and authorized_post routes must be protected by your applications authentication mechanism i.e. a middleware.

For simplicity in this tutorial, we're skipping that login step. We'll simply use the client_id as the user identifier to keep things simple

For the frontend, we'll use the template engine Askama to render the consent UI. We've already created an HTML template that you can find in the repository. Using the askama crate, we can create a struct for template rendering and then render the template using the render method.

#[derive(Template)]
#[template(path = "authorize.html")]
struct AuthorizeTemplate {
    client_id: String,
    client_name: String,
    redirect_uri: String,
    scope: String,
    scopes: Vec<String>,
    code_challenge: String,
    code_challenge_method: String,
    state: String,
}

We need to use the derive macro #[derive(Template)] to register the template and the #[template(path = "authorize.html")] attribute to specify the template file path.

After that, we can send the rendered template as an HTML response using the axum::response::Html type.

pub async fn authorize_get(
    Query(params): Query<AuthorizeRequest>,
    State(state): State<Arc<AppState>>,
) -> impl IntoResponse {
    // Validate required parameters
    if params.response_type != "code" {
        return (
            StatusCode::BAD_REQUEST,
            Html("Unsupported response type".to_string()),
        )
            .into_response();
    }

    // Look up client in database
    let client_result = sqlx::query!(
        "SELECT client_name FROM mcp_clients WHERE client_id = $1",
        params.client_id
    )
    .fetch_optional(&state.pool)
    .await;

    let client = match client_result {
        Ok(Some(client)) => client,
        Ok(None) => {
            return (StatusCode::BAD_REQUEST, Html("Invalid client".to_string())).into_response()
        }
        Err(e) => {
            error!("Database error: {}", e);
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                Html("Internal server error".to_string()),
            )
                .into_response();
        }
    };

    let scope = params.scope.unwrap_or_else(|| "profile email".to_string());
    let scopes: Vec<String> = scope.split_whitespace().map(|s| s.to_string()).collect();

    let template = AuthorizeTemplate {
        client_id: params.client_id,
        client_name: client.client_name,
        redirect_uri: params.redirect_uri,
        scope: scope.clone(),
        scopes,
        code_challenge: params.code_challenge,
        code_challenge_method: params.code_challenge_method,
        state: params.state.unwrap_or_default(),
    };

    match template.render() {
        Ok(html) => Html(html).into_response(),
        Err(e) => {
            error!("Template render error: {}", e);
            (
                StatusCode::INTERNAL_SERVER_ERROR,
                Html("Template error".to_string()),
            )
                .into_response()
        }
    }
}

Next, let's handle the authorization click. When a user approves the request, our server will:

Generate an authorization code and save it to the database.
Redirect the user back to the client using the provided redirect_uri.

pub async fn authorize_post(
    State(state): State<Arc<AppState>>,
    Form(form): Form<AuthorizeForm>,
) -> impl IntoResponse {
    if form.action == "deny" {
        let mut redirect_url = format!("{}?error=access_denied", form.redirect_uri);
        if let Some(state) = form.state {
            redirect_url.push_str(&format!("&state={state}"));
        }
        return Redirect::to(&redirect_url).into_response();
    }

    // Generate authorization code
    let auth_code = generate_authorization_code();
    let expires_at = Utc::now() + Duration::minutes(10); // 10 minute expiration

    // Store authorization code in database
    let store_result = sqlx::query!(
        r#"
        INSERT INTO authorization_codes (code, client_id, redirect_uri, code_challenge, expires_at)
        VALUES ($1, $2, $3, $4, $5)
        "#,
        auth_code,
        form.client_id,
        form.redirect_uri,
        form.code_challenge,
        expires_at
    )
    .execute(&state.pool)
    .await;

    match store_result {
        Ok(_) => {
            let mut redirect_url = format!("{}?code={}", form.redirect_uri, auth_code);
            if let Some(state) = form.state {
                redirect_url.push_str(&format!("&state={state}"));
            }
            Redirect::to(&redirect_url).into_response()
        }
        Err(e) => {
            error!("Failed to store authorization code: {}", e);
            let mut redirect_url = format!("{}?error=server_error", form.redirect_uri);
            if let Some(state) = form.state {
                redirect_url.push_str(&format!("&state={state}"));
            }
            Redirect::to(&redirect_url).into_response()
        }
    }
}

Let's test our authorization endpoint with the MCP inspector:

The inspector displays the backend authorization URL we just created, which you can open in a browser to see the consent UI.

Click "Authorize"

The inspector now displays the authorization code from the backend, which we'll use in the next step.

All steps done for this phase, let's move on to the next step which is the token endpoint.

Implementing Token Exchange

So far, the user has authorized the client and been redirected back with an authorization code.

Next, the client must exchange that authorization code for an actual access token. It does this by making a POST request to our token endpoint.

To be fully compliant with OAuth 2.0, this single endpoint needs to handle two different grant types:

Exchanging the initial authorization code for tokens.
Exchanging a refresh token for a new access token later on.

To handle this, we'll build two main functions:

handle_authorization_code_grant: This function will validate the incoming authorization code and PKCE verifier from the database. If they are valid, it creates the first access token and refresh token.
handle_refresh_token_grant: This function validates an existing refresh token. If it's valid, it issues a new access token and implements token rotation. This is a security best practice where a new refresh token is also issued, invalidating the old one.

pub async fn token_post(
    State(state): State<Arc<AppState>>,
    Form(request): Form<TokenRequest>,
) -> impl IntoResponse {
    match request.grant_type.as_str() {
        "authorization_code" => handle_authorization_code_grant(state, request)
            .await
            .into_response(),
        "refresh_token" => handle_refresh_token_grant(state, request)
            .await
            .into_response(),
        _ => {
            let error = ErrorResponse {
                error: "unsupported_grant_type".to_string(),
                error_description: Some(
                    "Only authorization_code and refresh_token grant types are supported"
                        .to_string(),
                ),
            };
            (StatusCode::BAD_REQUEST, Json(error)).into_response()
        }
    }
}

See the full implementation here.

Let's test our token endpoint with the MCP inspector:

Perfect! All steps done for the OAuth 2.0 authentication, and we're ready to move on to the next step which is creating a middleware to protect the MCP endpoint.

Implementing JWT Authentication Middleware

To secure our MCP service, we need to validate the JWT on every request made by a client. We'll use a middleware to handle this, ensuring only authenticated clients can access our MCP tools:

JWT Claims Structure

The JWT we generated earlier contains the client_id. By decoding this token on every incoming request, we can extract the client_id to identify which client is making the call.

First, we'll define a struct that mirrors the JWT claims we generated at the token endpoint:

#[derive(Debug, Serialize, Deserialize)]
pub struct Claims {
    pub sub: String,   // client_id
    pub iat: i64,      // issued at
    pub exp: i64,      // expires at
    pub scope: String, // granted scopes
}

Token Validation Middleware

The middleware extracts and validates JWT tokens from the Authorization header:

pub async fn validate_token_middleware(
    State(state): State<Arc<AppState>>,
    mut request: Request<Body>,
    next: Next,
) -> Response {
    // Extract the access token from the Authorization header
    let auth_header = request.headers().get("Authorization");
    let token = match auth_header {
        Some(header) => {
            let header_str = match header.to_str() {
                Ok(s) => s,
                Err(_) => {
                    error!("Invalid Authorization header encoding");
                    return StatusCode::UNAUTHORIZED.into_response();
                }
            };

            if let Some(stripped) = header_str.strip_prefix("Bearer ") {
                stripped.to_string()
            } else {
                error!("Authorization header missing Bearer prefix");
                return StatusCode::UNAUTHORIZED.into_response();
            }
        }
        None => {
            error!("Missing Authorization header");
            return StatusCode::UNAUTHORIZED.into_response();
        }
    };

    // Get JWT secret from configuration
    let jwt_secret = state
        .secrets
        .get("JWT_SECRET")
        .expect("JWT_SECRET secret not found");

    // Validate JWT token
    let key = DecodingKey::from_secret(jwt_secret.as_bytes());
    let validation = Validation::default();

    match decode::<Claims>(&token, &key, &validation) {
        Ok(token_data) => {
            // Check if token is expired (JWT validation already handles this, but being explicit)
            let now = chrono::Utc::now().timestamp();
            if token_data.claims.exp < now {
                error!("Token has expired");
                return StatusCode::UNAUTHORIZED.into_response();
            }

            // Verify the client still exists in database
            let client_exists = sqlx::query!(
                "SELECT client_id FROM mcp_clients WHERE client_id = $1",
                token_data.claims.sub
            )
            .fetch_optional(&state.pool)
            .await;

            match client_exists {
                Ok(Some(_)) => {
                    // Add client_id to request extensions for downstream handlers
                    request.extensions_mut().insert(token_data.claims.sub);
                    next.run(request).await
                }
                Ok(None) => {
                    error!("Client no longer exists: {}", token_data.claims.sub);
                    StatusCode::UNAUTHORIZED.into_response()
                }
                Err(e) => {
                    error!("Database error validating client: {}", e);
                    StatusCode::INTERNAL_SERVER_ERROR.into_response()
                }
            }
        }
        Err(e) => {
            error!("Token validation failed: {}", e);
            StatusCode::UNAUTHORIZED.into_response()
        }
    }
}

In the middleware, we extract the Bearer token and verify it's valid and not expired. Then we extract the client_id from it and verify the client exists in the database.

request.extensions_mut().insert(token_data.claims.sub);

The above code snippet is a crucial part of the middleware, we add the client_id to the request extensions so it can be used by the next handlers and MCP tools.

Defining the service struct

We will define our entire service within a central struct. This approach allows us to implement the necessary rmcp traits and macros, which will contain all of our MCP logic like tools, resources, prompts, etc.

use tokio::sync::Mutex;
use std::sync::Arc;

#[derive(Clone)]
pub struct TodoService {
    db_pool: Arc<PgPool>,
    tool_router: ToolRouter<TodoService>,
    client_id: Arc<Mutex<Option<String>>>,
}

The client_id here is key because it will be used to identify the client that made the request in every tool call.

Server Handler Implementation

Next, we'll implement the ServerHandler trait. This trait handles core protocol logic and ensures our server is compliant without having to manage the low-level details.
It has many methods, but most of them are optional.

To get our server running, we only need to implement the following:

initialize: Handles the initial setup when a client connects.
get_info: Provides essential metadata about our service.

We'll ignore the other optional methods like ping, list_prompts, and list_resources for the time being.

Implementing `get_info`

The get_info method is used to provide metadata about our MCP service, MCP clients will fetch this metadata and the AI model will understand what this MCP server is used for.

#[tool_handler]
impl ServerHandler for TodoService {
    fn get_info(&self) -> ServerInfo {
        ServerInfo {
            protocol_version: ProtocolVersion::V_2024_11_05,
            capabilities: ServerCapabilities::builder()
                .enable_prompts()
                .enable_resources()
                .enable_tools()
                .build(),
            server_info: Implementation::from_build_env(),
            instructions: Some("This server provides todo management tools. You can create, read, update, and delete todos. Each todo has an id, title, and completion status.".to_string()),
        }
    }
}

Implementing `initialize` method

The initialize method executes on initial MCP client-server connection. Running post-JWT middleware, it extracts the client_id from middleware extensions and caches it for subsequent operations.

#[tool_handler]
impl ServerHandler for TodoService {
    ...

    async fn initialize(
        &self,
        _request: InitializeRequestParam,
        context: RequestContext<RoleServer>,
    ) -> Result<InitializeResult, McpError> {
        if let Some(http_request_part) = context.extensions.get::<axum::http::request::Parts>() {
            if let Some(client_id) = http_request_part.extensions.get::<String>() {
                let mut writer = self.client_id.lock().await;
                *writer = Some(client_id.clone());
            } else {
                tracing::warn!("No client_id found in HTTP request extensions");
            }
        }
        Ok(self.get_info())
    }
}

Authentication for persistent SSE connections works differently than for standard HTTP requests. We validate the JWT only once when the connection is first established via the initialize method. All subsequent messages on that same connection are then considered authenticated

The initialize method's signature takes &self (an immutable reference), not &mut self. This presents a challenge: we're not allowed to directly change our service's state (like setting the client_id) from within the method.

To work around this restriction, we use a pattern called interior mutability. We wrap our client_id in two special types that allow for safe modification even from an immutable context:

Arc: Allows the data to be safely owned and shared across multiple asynchronous tasks.
tokio::sync::Mutex: Acts as a lock that ensures only one task can access and change the data at a time.

This combination lets us safely mutate the value from within a method that only has a &self

Building the MCP Todo Service

Let's do a quick recap of how the connection is being handled so far:

The MCP client requests OAuth metadata.
User clicks the login button presented by the MCP client.
User is redirected to the authorization endpoint.
User Authorizes the MCP client.
Server redirects the user back to the MCP client with the authorization code.
MCP client exchanges the authorization code for the access token and refresh token.
MCP client establishes a persistent connection to the MCP endpoint (i.e /mcp/sse) using the access token as a Bearer token in the Authorization header.
The JWT middleware validates the access token and extract the client_id from it.
The TodoService has now access to the client_id and can use it to perform actions on behalf of the user.

Implementing the MCP tools

MCP tools work like regular functions: they have names, input parameters, and outputs. When AI agents call these tools, they pass the required parameters and receive results back through the JSON-RPC 2.0 protocol.
The rmcp crate simplifies schema generation by using schemars to create JSON-RPC 2.0 compatible schemas automatically. With the derive macro, we can implement the JsonSchema trait and generate tool schemas without manual work.
For our todo creation tool, we need just a title field and an optional completed field. The tool returns a success message confirming the operation.

#[derive(Debug, Serialize, Deserialize, rmcp::schemars::JsonSchema)]
pub struct CreateTodoInput {
    pub title: String,
    pub completed: Option<bool>,
}

Implementing MCP Tools

The rmcp library provides powerful macros to automatically generate MCP tools. The #[tool_router] macro creates a router for all our tools, while #[tool] generates individual tool handlers:

#[tool_router]
impl TodoService {
    pub fn new(db_pool: Arc<PgPool>) -> Self {
        Self {
            db_pool,
            tool_router: Self::tool_router(),
            client_id: Arc::new(tokio::sync::Mutex::new(None)),
        }
    }

    #[tool(description = "Create a new todo item")]
    async fn create_todo(
        &self,
        Parameters(input): Parameters<CreateTodoInput>,
    ) -> Result<CallToolResult, McpError> {
        // Extract client_id for user-specific data operations
        let client_id = {
            let reader = self.client_id.lock().await;
            reader.clone().ok_or_else(|| {
                McpError::internal_error("Client not authenticated".to_string(), None)
            })?
        };

        let request = CreateTodoRequest {
            title: input.title,
            completed: input.completed,
        };

        // Pass client_id to database operations for user isolation
        match db::create_todo(&self.db_pool, request, &client_id).await {
            Ok(todo) => {
                let todo_json = serde_json::to_string_pretty(&todo).map_err(|e| {
                    McpError::internal_error(format!("Serialization error: {e}"), None)
                })?;
                Ok(CallToolResult::success(vec![Content::text(format!(
                    "Todo created successfully:\\n{todo_json}"
                ))]))
            }
            Err(e) => Err(McpError::internal_error(
                format!("Failed to create todo: {e}"),
                None,
            )),
        }
    }

    // Other tools: get_todo, list_todos, update_todo, delete_todo...
}

The database query for creating a todo item:

pub async fn create_todo(
    pool: &PgPool,
    request: CreateTodoRequest,
    client_id: &str,
) -> Result<Todo, sqlx::Error> {
    let row = sqlx::query!(
        r#"
        INSERT INTO todos (title, completed, client_id)
        VALUES ($1, COALESCE($2, FALSE), $3)
        RETURNING id, title, completed
        "#,
        request.title,
        request.completed,
        client_id
    )
    .fetch_one(pool)
    .await?;

    Ok(Todo {
        id: row.id,
        title: row.title,
        completed: row.completed,
    })
}

Integrating the SSE Server

So far, we've defined our MCP service struct, implemented the ServerHandler trait, and used the #[tool_router] macro to register our tools. Now, we need to integrate this service into an SSE server so it can be accessed from a URL.

pub async fn init(
    addr: SocketAddr,
    pool: PgPool,
    secrets: shuttle_runtime::SecretStore,
) -> Result<(), shuttle_runtime::Error> {
    // ---- Other boilerplate code ----

    // Create SSE server configuration for MCP
    let sse_config = SseServerConfig {
        bind: addr,
        sse_path: "/mcp/sse".to_string(),
        post_path: "/mcp/message".to_string(),
        ct: CancellationToken::new(),
        sse_keep_alive: Some(Duration::from_secs(15)),
    };

    // Create SSE server
    let (sse_server, sse_router) = SseServer::new(sse_config);

    // Create protected SSE routes (require authorization)
    let protected_sse_router = sse_router.layer(middleware::from_fn_with_state(
        app_state.clone(),
        // Applying the middleware for authentication
        validate_token_middleware,
    ));

    // Create HTTP router with auth routes (non-protected) and protected SSE router
    let app = Router::new()
        .merge(auth_router)
        .with_state(app_state.clone())
        .merge(protected_sse_router)
        .layer(cors_layer);

    // Add the `TodoService` we created to the SSE server
    sse_server.with_service(move || TodoService::new(Arc::new(app_state.pool.clone())));

    // ---- Other boilerplate code to start the server ----

    Ok(())
}

The middleware is applied to make sure only authenticated clients can access the MCP route:

let protected_sse_router = sse_router.layer(middleware::from_fn_with_state(
    app_state.clone(),
    // Applying the middleware for authentication
    validate_token_middleware,
));

We also used Axum's with_service method to attach our TodoService to the route. This makes our service available to any client that connects to the SSE server.

sse_server.with_service(move || TodoService::new(Arc::new(app_state.pool.clone())));

Deployment and Testing

Deploy to Shuttle with a single command:

shuttle deploy

Adding to MCP Clients

Follow the instructions below to connect your specific MCP client to the server:

Cursor Configuration:

{
  "mcpServers": {
    "Todo List": {
      "url": "https://your-server.shuttle.app/mcp/sse"
    }
  }
}

In Cursor, navigate to the Tools page within the Settings menu. Then click the "Login" button to authenticate with the MCP server.

This will redirect you to the authorization page that we created.

After authorizing the client, you'll be redirected to Cursor, which will now have access to the MCP tools on your account.

Perfect! 🎉 Our MCP server is now hosted and ready to use by Cursor. The same process applies to any other MCP client, such as Claude Code or Windsurf.

Conclusion

We've successfully built a production-ready MCP server with the SSE transport type that combines the power of Server-Sent Events with robust OAuth 2 authentication. This project demonstrates how to create secure, real-time AI tool access that goes far beyond a simple local setup.

Our implementation delivers a complete OAuth 2 flow to secure all client interactions. The SSE-based protocol enables instant tool communication, while the authorization layer ensures that actions are performed securely on behalf of specific users. The entire system, backed by PostgreSQL, deploys seamlessly to Shuttle, providing a solid foundation for building any real-world MCP service.

Pushing future updates is as simple as running shuttle deploy, and you can easily integrate this command into a CI/CD pipeline to fully automate the process.

The combination of Rust's performance, Shuttle's deployment simplicity, and MCP's standardized protocol creates a compelling stack for modern AI tooling infrastructure that scales from prototype to production without compromise.

Try it Yourself

Ready to build your own SSE MCP server? Run the following command to clone the complete project and deploy with one command:

# Clone the project
shuttle init --from shuttle-hq/shuttle-examples --subfolder mcp/mcp-sse-oauth

# Navigate to the project directory
cd mcp-sse-oauth

# Deploy the project
shuttle deploy

Read the Shuttle documentation for more information. Happy coding!

Backend Challenge: Learn Rust Microservices for the Cloud

Shuttle — Wed, 27 Aug 2025 14:02:48 +0000

Looking to level up your Rust skills while learning modern cloud deployment? ShellCon offers a unique hands-on learning experience that combines Rust microservices development with Shuttle Cloud deployment. This comprehensive full-stack project will take you from local development to cloud deployment while solving real-world performance optimization problems.

What is ShellCon?

ShellCon is an innovative learning approach that transforms Rust and cloud development education into a practical, project-based experience. Instead of working through abstract tutorials, you'll build and optimize a complete microservices architecture with three interconnected Rust services and a React dashboard.

Development Workflow

Phase 1: Local Development - Set up and run all three services locally, then verify the React dashboard connects properly to each service endpoint.

Phase 2: Performance Optimization - Solve four distinct performance challenges across the microservices, each focusing on different aspects of Rust optimization.

Phase 3: Cloud Deployment - Deploy your optimized services to Shuttle Cloud and validate everything works in a production environment.

What You'll Build

You'll construct a complete microservices ecosystem consisting of three specialized Rust services working together through REST APIs. Your development journey involves three critical phases:

The Microservices Architecture

aqua-monitor: An environmental monitoring service that handles sensor data collection, tank readings, and system status endpoints. You'll work with async I/O patterns and HTTP client optimization.

species-hub: A database service managing species information, feeding schedules, and related data. This service teaches SQL optimization and efficient database interaction patterns.

aqua-brain: An analytics engine that processes data from the other services to generate insights and analysis. You'll focus on memory optimization and efficient string handling.

React Dashboard: A modern frontend that connects to all three services through REST APIs, providing real-time monitoring and control capabilities.

What You'll Learn

ShellCon offers a comprehensive learning experience that combines project-based learning with real-world architecture. You'll build a complete application with production-like microservices while getting immediate feedback on your optimizations.

Through this hands-on approach, you'll learn:

Rust Development: Async/await patterns, non-blocking I/O, SQLx with PostgreSQL, heap allocation optimization, and Axum connection pooling
Cloud Infrastructure: Shuttle Cloud deployment, resilient microservices creation, Docker containers, and multi-stage deployment configuration
Frontend Integration: Connecting React to Rust microservices, designing efficient RESTful endpoints, and implementing cross-service health checks

Challenge Structure

Each challenge focuses on a specific aspect of Rust performance optimization:

Four Key Optimization Challenges

1. Async I/O (aqua-monitor): Fix blocking operations in async code to improve tank readings performance.

2. SQL Queries (species-hub): Optimize database queries to enhance species database efficiency.

3. Memory Management (aqua-brain): Minimize heap allocations in the analytics engine using Rust's ownership system.

4. HTTP Client Pooling (aqua-monitor): Implement connection reuse patterns to boost network performance.

Getting Started is Simple

Ready to begin your Rust and cloud development journey? The setup process is straightforward:

Clone the repository and install prerequisites (Rust, Docker, Node.js, Shuttle CLI)
Launch the three microservices locally using the provided scripts
Start the React dashboard and verify all connections work
Begin solving the four optimization challenges at your own pace
Deploy to Shuttle Cloud and validate your solutions in production

Start Your Rust Development Journey Today

The demand for Rust developers continues to grow as more companies adopt Rust for performance-critical applications. ShellCon provides the perfect combination of hands-on learning and real-world application that will prepare you for professional Rust development. Don't spend months reading documentation without building anything meaningful.

Ready to build production-ready microservices and master Rust optimization?

Clone the repository and start building:

git clone https://github.com/shuttle-hq/shuttle-shellcon.git
cd shuttle-shellcon

Your journey from Rust beginner to confident microservices developer starts with a single git clone. Start building today and master the skills that will define your backend development career!

Join developers worldwide who are mastering Rust and cloud development through ShellCon's practical, project-based approach. Start building today and develop the microservices skills that will advance your backend development career.

How to Build a stdio MCP Server in Rust

Shuttle — Tue, 26 Aug 2025 14:01:33 +0000

Introduction

AI agents are transforming how we work, but they're often limited by their training data. MCP (Model Context Protocol) servers bridge this gap by giving AI agents access to real-time data, external APIs, and custom tools.

Building your own MCP server lets you extend AI capabilities with your specific tools and services. In this guide, we'll create a DNS lookup MCP server in Rust that demonstrates these concepts in action.

Our MCP server will perform DNS lookups and provide real-time internet data to AI agents. Since AI models can't directly access external data sources, the server acts as a bridge, delivering live DNS information that extends the agent's capabilities beyond its training data.

What is MCP?

MCP stands for Model Context Protocol, it's a protocol that allows AI models to securely access external tools and data sources. This is extremely useful, because the AI agents will not be limited to the data they were trained on, in fact they'll be able to access external data and resources plus the ability to use tools and make API calls to external services.

Once you build an MCP server, it can be used by any MCP client, like Cursor and Claude Code, or any other MCP client that supports the MCP protocol like chatbots and conversational agents. The protocol is a standard, so you can use the same MCP server with different clients.

MCP Transport Types

MCP servers use two transport mechanisms: stdio (standard input/output) and SSE (Server-Sent Events). The stdio transport communicates through standard input/output, similar to LSP (Language Server Protocol) servers, making it fast and efficient for local use. These servers are installed locally and have full access to your machine, for example they can interact with the file system, execute shell commands, access databases, or interact with any local services.

SSE servers run externally in the cloud and connect via WebSockets. While they offer more scalability, they require network setup and don't have access to your local machine's resources.

This tutorial focuses on building a stdio MCP server - the simpler approach that's perfect for local development and personal AI workflows.

Building stdio MCP Server in Rust

In this tutorial, we're going to build a simple MCP server using the stdio transport that allows AI agents to perform DNS lookups.

We'll use the HackerTarget API (a public service that provides DNS lookup capabilities) to perform the DNS lookups and return the results back to the AI agent.

The workflow is as follows:

AI agent asks the MCP server to perform a DNS lookup with a parameter: domain
MCP server will use the HackerTarget API to perform the DNS lookup
MCP server will return the results back to the AI agent
The AI agent will read the real-time results, providing important context for the next steps

Setting Up the Project

Now that we have laid out the plan and workflow, let's start building the MCP server.

First, we need to create a new Rust project.

cargo new dns-lookup-mcp-server
cd dns-lookup-mcp-server

Let's install the required dependencies for the project, the Model Context Protocol provides an official SDK for Rust called rmcp. You can find the Rust SDK for MCP here: github.com/modelcontextprotocol/rust-sdk.

Add the following dependencies to your Cargo.toml:

[package]
name = "dns-lookup-mcp-server"
version = "0.1.0"
edition = "2021"

[dependencies]
tokio = { version = "1", features = ["full"] }
rmcp = { version = "0.3", features = ["server", "transport-io"] }
serde = { version = "1", features = ["derive"] }
reqwest = "0.12"
anyhow = "1.0"
schemars = "1.0"

serde crate to serialize and deserialize JSON-RPC (JSON Remote Procedure Call) data for MCP protocol
tokio for async operations
reqwest to make HTTP requests to the DNS lookup API (HackerTarget)
schemars for JSON schema generation
anyhow for error handling

The rmcp crate provides the MCP server implementation.

Building the DNS Service

Let's create the DNS service module. First, create a new file src/dns_mcp.rs and add the following code:

use rmcp::{
    handler::server::{router::tool::ToolRouter, tool::Parameters},
    model::{ErrorData as McpError, *},
    schemars, tool, tool_handler, tool_router, ServerHandler,
};
use serde::Deserialize;
use std::{borrow::Cow, future::Future};

#[derive(Debug, Clone)]
pub struct DnsService {
    tool_router: ToolRouter<DnsService>,
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct DnsLookupRequest {
    #[schemars(description = "The domain name to lookup")]
    pub domain: String,
}

#[tool_router]
impl DnsService {
    pub fn new() -> Self {
        Self {
            tool_router: Self::tool_router(),
        }
    }

    #[tool(description = "Perform DNS lookup for a domain name")]
    async fn dns_lookup(
        &self,
        Parameters(request): Parameters<DnsLookupRequest>,
    ) -> Result<CallToolResult, McpError> {
        let response = reqwest::get(format!(
            "https://api.hackertarget.com/dnslookup/?q={}",
            request.domain
        ))
        .await
        .map_err(|e| McpError {
            code: ErrorCode(-32603),
            message: Cow::from(format!("Request failed: {}", e)),
            data: None,
        })?;

        let text = response.text().await.map_err(|e| McpError {
            code: ErrorCode(-32603),
            message: Cow::from(format!("Failed to read response: {}", e)),
            data: None,
        })?;

        Ok(CallToolResult::success(vec![Content::text(text)]))
    }
}

The code uses several key attributes that handle MCP protocol integration:

#[tool_router] wires up the MCP protocol for any methods marked with #[tool].
#[tool(description = "...")] exposes the function to AI models with a description for tool selection.
Parameters<T> provides type-safe parameter extraction.
#[schemars(description = "...")] adds schema documentation for AI parameter generation.

Server Configuration

To configure your MCP server, implement ServerHandler for metadata and apply #[tool_handler] to auto-generate tool discovery.

Add this to the end of src/dns_mcp.rs:

#[tool_handler]
impl ServerHandler for DnsService {
    fn get_info(&self) -> ServerInfo {
        ServerInfo {
            protocol_version: ProtocolVersion::V_2024_11_05,
            capabilities: ServerCapabilities::builder().enable_tools().build(),
            server_info: Implementation::from_build_env(),
            instructions: Some("A DNS lookup service that queries domain information using the HackerTarget API. Use the dns_lookup tool to perform DNS lookups for any domain name.".to_string()),
        }
    }
}

Running the Server

Then, set up stdio communication in src/main.rs:

use anyhow::Result;
use dns_mcp::DnsService;
use rmcp::{transport::stdio, ServiceExt};

mod dns_mcp;

#[tokio::main]
async fn main() -> Result<()> {
    // Create an instance of our DNS service
    let service = DnsService::new().serve(stdio()).await?;
    service.waiting().await?;
    Ok(())
}

Testing During Development

To speed up your development and testing, you can run the MCP server directly from your project without building a release binary. In Cursor, enable this by creating a .cursor/mcp.json file in your project's root directory:

{
  "mcpServers": {
    "DNS Lookup (Dev)": {
      "command": "cargo",
      "args": ["run"]
    }
  }
}

Note that configuration may vary depending on your MCP client. Check your client's documentation for the specific configuration format.

Building for Production

To build and install the MCP server for production use:

# Build and install the binary to ~/.cargo/bin
cargo install --path .

This installs the dns-lookup-mcp-server binary to your Cargo bin directory (typically ~/.cargo/bin), making it available system-wide if this directory is in your PATH.

Using in Cursor

To configure the MCP server globally for Cursor, edit the main settings file located at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "DNS Lookup": {
      "command": "dns-lookup-mcp-server"
    }
  }
}

This uses the binary name directly, assuming you've installed it with cargo install --path . and ~/.cargo/bin is in your PATH.

MCP Server in Action

Time to put the MCP server to work. Let's have it check the DNS records for three domains and create a table of the results.

In the above screenshot, we asked the AI agent to query the DNS records for three domains and create a markdown table to display the results.

The AI agent was able to use the dns_lookup tool to perform the DNS lookup and return the results back to the user.

Conclusion

While AI can significantly improve your development workflow, LLMs are naturally limited by their training data, knowledge cutoffs, and sandbox environment. MCP servers bridge this gap by giving AI agents access to real-time data and tools they can use when needed.

This feature is essential for data that changes too quickly for static training sets. For instance, to configure an application's networking, your AI agent needs direct access to the very latest DNS records, not outdated information. The same logic applies to other live sources, like querying a real-time database or checking an API's current status.

Rust shines as a great language for building MCP servers. Its type safety and performance characteristics make it ideal for creating reliable tools that AI models can use confidently. The rmcp crate's clean API combined with macros like #[tool] eliminates boilerplate, letting you focus on functionality rather than protocol details.

In just a few dozen lines of code, we built a production-ready DNS lookup service that works with any MCP-compatible AI client. The standardized MCP protocol means your Rust server can integrate seamlessly across different AI platforms and tools.

This is just the beginning - you can extend this pattern to build MCP servers for databases, APIs, file systems, or any external service your AI agents might need to interact with.

Deploy your MCP server to the cloud

Ready to extend AI capabilities beyond their training data? Our SSE MCP server template lets you build production-ready MCP servers with your own custom logic that seamlessly integrate with any AI client:

shuttle init --from shuttle-hq/shuttle-examples --subfolder mcp/mcp-sse

AI Assisted Rust Development Environment Setup: Build Rust APIs in Minutes

Shuttle — Mon, 18 Aug 2025 13:38:28 +0000

Shipping Rust code used to mean wrestling with the borrow-checker, poring over docs, and SSH-ing into servers at 2 a.m. In 2025 that workflow feels prehistoric. With AI-first IDEs such as Cursor, tool-calling standards like Model Context Protocol (MCP), and one-command cloud hosts such as Shuttle, you can spin up, test, and deploy a secure Rust API in 5 minutes before your coffee cools.

This guide shows you how to assemble an AI-assisted development environment tailored for Rust: code completion that understands your entire repo, agents that run migrations and push containers, and MCP plugins that read the latest docs instead of hallucinated snippets. We'll finish by launching a task-management API live to the cloud: hands-off coding, testing, and shipping in under five minutes using a true 10x developer workflow.

While this sounds cool, AI-assisted Rust development doesn't replace human developers. Treat it like a power tool: it boosts speed and efficiency, yet our craft still rests on understanding core programming concepts.

What IDE Should You Use?

Cursor is one of the most popular AI-powered code editors. Forked from VS Code, it keeps everything you love about VS Code while layering in AI-first features.

With Cursor, you tap into today's leading large-language models, and the built-in AI assistant writes code with full, context-aware knowledge of your entire codebase.

Features like Codebase Indexing can help the AI agents to search through your codebase with ease, and Cursor Tab will help you write code much faster and more efficiently by recommending code completions and edits that you can accept with just a tab press. You can think of it as an upgraded successor to what GitHub Copilot once was for AI-assisted development.

Setting Up Your AI-Enhanced Development Environment

In this section, we'll explore how to build an AI-powered Rust development environment that handles everything from coding to cloud deployment. While we'll use Cursor as our main IDE, most techniques work with any AI coding tool, so don't worry if you're using different tools, be it Windsurf, Claude Code, or even a web based AI chatbot for rust api development.

We'll set up MCP (Model Context Protocol) servers that let AI assistants interact with external systems, explore Cursor's advanced features like codebase indexing and tab completion, and cover universal strategies for effective AI-assisted development. By the end, you'll have an environment where AI can autonomously write, test, and deploy your Rust applications with automated deployment rust workflows. (YES! Even deployments!)

MCP Servers: Extending AI Capabilities

What Are MCP Servers?

LLMs excel at generating text, but their fixed knowledge cut-off means they often lack your project's freshest context. To bridge that gap, you need agents that can search databases, run shell commands, and pull live data from APIs. That's where MCP servers come in.

MCP servers are specialized tools that dramatically extend your AI assistant's capabilities beyond simple code generation. Think of MCP servers as powerful plugins that give your AI assistant the ability to interact with external systems, access real-time data, execute commands, and perform complex operations that would otherwise require manual intervention.

What MCP Servers Can Do for You

MCP servers transform your AI assistant from a simple code generator into a comprehensive development partner. Instead of just writing code, your AI can now:

Run database queries: Fetch real time data from databases and use them to generate code or give you answers.
Perform searches using search engines or searching documentations.
Execute system commands
Interact with APIs and external services.
Monitor application logs and debug production issues.
Deploy applications directly to cloud platforms like Shuttle.

MCP servers aren't confined to a single flavor: there's an ecosystem of ready-made options to choose from, and you can even build your own to run fully custom logic.

The screenshot below shows MCP servers in action. Notice how the AI assistant taps the specialized tool to deploy the Rust project to Shuttle.

In this example, you can see the AI assistant using the deploy tool to deploy the application to the cloud, demonstrating how MCP servers extend the AI's capabilities beyond simple code generation.

Later in the article, we'll walk through how to use the Shuttle MCP server.

Recommended MCP Servers for Rust Development

Here are the essential MCP servers that will supercharge your Rust development workflow:

Context7 MCP - Context7 solves one of the biggest problems in AI-assisted development: outdated documentation. Instead of relying on generic or outdated information from LLM training data, Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. This means your AI assistant gets accurate, relevant information about the exact versions of libraries you're using, eliminating hallucinations and providing working code examples.
Shuttle MCP - Shuttle is a cloud platform specifically designed for Rust applications. This MCP server streamlines your entire deployment workflow, enabling seamless project creation, application deployment, environment management, and real-time monitoring directly within your development environment.
Puppeteer MCP - A Model Context Protocol server that provides browser automation capabilities using Puppeteer. This server enables LLMs to interact with web pages, take screenshots, and execute JavaScript in a real browser environment.
GitHub MCP - Integrates version control operations directly into your AI workflow. Manages code repositories, handles pull requests, tracks issues, and coordinates collaborative development without switching contexts.
Playwright MCP - Brings Microsoft's browser automation framework to your AI assistant. Enables cross-platform web testing across Chrome, Firefox, Safari, and Edge with enhanced reliability compared to traditional testing tools.

Cursor Configuration

Enable Memories

Cursor provides a feature called Memories, this feature let's the AI agent to remember specific context about you and your project, using this feature for a while can make your AI agent more personalized and aware of your coding style, preferences and the projects you're working on.

To enable this feature, navigate to Settings > Rules > Memories and tick the Generate memories option.

Add Documentation Context

AI coding assistants are more powerful when they have a good understanding of the libraries and frameworks you're using, the more context, the better results you'll get. However, copy/pasting documentation in every chat is a tedious task and we don't wanna do that by hand.

Thankfully, Cursor provides us with a great developer friendly feature that allows us to add documentation context only once and we'll be able to use it as context in any chat we want.

To add documentation context:

Open the chat panel in Cursor and type @Docs in the chat.

Click "Add new doc".

Paste the URL prefix of the documentation you want to add (e.g., https://docs.shuttle.dev).

Press Enter, this will bring us to the last step, which we can specify a title for our documentation, along with an entrypoint URL and prefix URL for the documentation we want to add.

Cursor will automatically index the page and any sub-pages with that URL prefix. We can then mention it using @Docs and select the specific documentation we want to use. Claude 4.0 is especially good at this due to its large context window.

Cursor will automatically fetch the relevant documents and feed it to the AI assistant, we'll get an answer almost immediately, this saves us a lot of time and effort to search through documentation manually.

Rust-Specific Rules for AI Agents

Rules are yet another AI feature provided by Cursor that allows us to define custom rules that guide how the AI writes code for our specific project.

Most developers skimp on documentation and pay for it later. Cursor's Rules feature flips that script: You drop a markdown file at .cursor/rules/my-rule.mdc into your repo, and the AI treats those notes as living docs. No more "I'll document it later" guilt 🙂 Your guidelines, style tips, and architectural clues are always in context, keeping the assistant (and your teammates) perfectly informed.

For that reason, we have Cursor Rules, Cursor allows us to define a set of custom rules that sets some rules for the AI agent to follow when writing code for a specific project.

Rules can be specified to projects, and they can be specified to be read automatically or manually.

Let's create a .cursor/rules/rust.mdc file in our project root with Rust-specific guidelines:

.
|-- .cursor
|   |-- rules
|       |-- rust.mdc
|       |-- ...
|-- ...

You are an expert Rust developer. Follow these rules when writing Rust code:

## Code Style
- Use idiomatic Rust patterns and conventions
- Prefer explicit error handling with Result<T, E>
- Use ? operator for error propagation
- Implement proper ownership and borrowing
- Use descriptive variable names and function signatures

## Error Handling
- For comprehensive error handling, use libraries like `anyhow` for simple error handling, `thiserror` for custom error types, or `eyre` for enhanced error reporting
- Never use unwrap() or expect() in production code
- Provide meaningful error messages
- Use `anyhow::Result<T>` for functions that can return multiple error types
- Use `thiserror::Error` derive macro for custom error enums

## Testing
- Write unit tests for all public functions
- Use descriptive test names that explain the scenario
- Group related tests in modules

Important Note: These are generic rules for Rust development. You should customize these rules for your specific project. For example, if you're using a validation library like validator, write specific rules about how to handle validations. If you're using specific architectural patterns or frameworks, document them in your rules so the AI can follow your project's conventions consistently.

How Cursor Reads Your Specified Rules

Cursor will read these rules based on a few conditions that we can manually specify:

Always: This will read the rules for every single chat we have with the AI assistant.
Auto Attached: This will read the rules based on a specified glob pattern, for example, if we want the rules to be read for every rust file, we can specify the glob pattern to be */*.rs. Or if we want to add rules for a specific crate, we can specify crates/my_macros/**/*.rs.
Agent Requested: This gives us the option to add a description to the rules file, Cursor will automatically read these rules if it finds a description that matches the current chat.
Manual: This will read the rules only when we manually mention it in the chat by typing @Cursor Rules and selecting the rules that we defined.

Best Practices for AI Prompting

The general principle of garbage in, garbage out applies in prompt engineering as well, the more specific and detailed we are, the better the results we'll get.

Here are some best practices for AI prompting:

Use a Todo-Driven Approach

It's very common for the AI assistant to write some good code for a feature, only to delete, or modify it later and therefore breaking your code.

Instead of manually writing prompts each time, we can create a file for each task that we want to do, this file will contain all the tasks that have been done and that are pending for the specific feature that we want to build.

This way, our AI assistant will have a complete context and understanding of what we're trying to build and what we have done so far.

Create a todo.md file in your project root that explains your application requirements and features, then break them down into smaller, actionable tasks. Next time you want to work on a feature, you can just mention the todo.md file and the relevant file names that need to be changed and the AI assistant will work through the tasks systematically.

Here's an example:

# Project: Task Management API

This API will be a simple task management API, it will have a few endpoints:

- GET /tasks - List all tasks with optional filtering
- POST /tasks - Create a new task
- GET /tasks/{id} - Get a specific task
- PUT /tasks/{id} - Update a task
- DELETE /tasks/{id} - Delete a task

## Requirements

- CRUD operations for tasks
- User authentication
- Database persistence
- REST API endpoints

## Tasks

### Project Setup

- [ ] Initialize Rust project with dependencies
- [ ] Set up database connection and migrations

### Authentication

- [ ] Create User struct and auth endpoints
- [ ] Implement JWT middleware and password hashing

### Task CRUD

- [ ] Create Task model
- [ ] Create the task CRUD endpoints
  - [ ] GET /tasks - List all tasks with optional filtering
  - [ ] POST /tasks - Create a new task
  - [ ] GET /tasks/{id} - Get a specific task
  - [ ] PUT /tasks/{id} - Update a task
  - [ ] DELETE /tasks/{id} - Delete a task
- [ ] Add input validation and error handling for the task CRUD endpoints

### Testing

- [ ] Write unit and integration tests
- [ ] Set up test database

Provide Focused Context

Give the AI only the necessary context for the task at hand. Too much context can cause the AI to lose focus or forget important details. Be selective about which files and information you include.

Know When to Use MCP Servers vs CLIs

MCP servers and CLIs are both great tools that your AI agent can use to interact with systems, both of them have their pros and cons and you should know when to use each of them.

When to use MCP servers:

MCP servers can be superior to CLIs because the AI understands how to use them properly. While the AI might struggle with lesser-known CLI tools, MCP servers provide structured interfaces that the AI can navigate confidently. AI agents might not have the proper context for the CLIs and how to use them, therefore it has a more potential for hallucinations and making errors.

When to use CLIs:

If you're using a popular CLI tool like git, docker, cargo, etc. In that case, you won't need a MCP server for those actions, most LLMs have quite good knowledge on these tools and how they work.

Another reason to choose CLIs over MCP servers is that CLIs can stream their output and you don't need to wait for the processes to finish, you can see the code execution in real time, this streaming capability isn't available in MCP servers, on the contrary, you'll have to wait for the execution to finish before you can see the results.

Build Custom MCP Servers

If you already have an app or API, you can spin up a custom MCP server with the official SDKs, available in Rust and several other languages. A quick look at the docs shows just how straightforward the process is.

Building a Complete Rust CRUD API with AI in 5 Minutes

Now for the exciting part—let's build and deploy a complete CRUD API using nothing but AI assistance. We'll use all the tools and techniques we've learned so far to build a task management API with full database integration using the Axum rust framework.

We'll also deploy the API to the cloud, we'll do all this without writing any code, we'll just let our AI assistant to do all the heavy lifting for us.

Important Note

This approach is not a complete replacement for human developers, AI can make mistakes and write code that is prone to bugs and security vulnerabilities. This demonstration is just a proof of concept and a way to show the power of AI-assisted development.

When building production applications, make sure you review all the AI generated code and make sure it's secure, performant and reliable.

Ready to Build Along?

To follow along with this tutorial, use our pre-configured template that includes all the necessary tools and configurations:

shuttle init --from shuttle-hq/shuttle-examples --subfolder axum/ai-assisted

This template includes pre-configured MCP servers, Cursor rules, and everything you need to follow along with the tutorial.

Prerequisites

Before starting to code, there are a few tools that we need to install and configure.

Shuttle CLI: To interact with shuttle using the CLI.
SQLx CLI: To interact with the database using the CLI.
Shuttle MCP Server: This is a MCP server that allows AI agents to look up the latest Shuttle documentation and gives proper context on how to interact with the Shuttle platform.
Docker: To run a local database in a container.

Install the Shuttle CLI

Install the shuttle CLI, for Linux/macOS:

curl -sSfL https://www.shuttle.dev/install | bash

For Windows:

iwr https://www.shuttle.dev/install-win | iex

Install the SQLx CLI

Install the SQLx CLI, for Postgres only:

# For postgres Only
cargo install sqlx-cli --no-default-features --features native-tls,postgres

Setting Up MCP Servers

Before we start, let's set up a few MCP servers that are going to help us build and deploy our API much easier.

Shuttle MCP Server

The Shuttle MCP server enables AI agents to understand and execute Shuttle commands directly, including deployments, fetching logs, searching through the latest Shuttle documentation and more.

Configure Cursor for Shuttle MCP Server

Add the Shuttle MCP server to your Cursor configuration. On Linux/macOS, edit ~/.cursor/mcp.json. On Windows, edit %APPDATA%\\Cursor\\mcp.json. Add the following to your MCP servers configuration:

{
  "mcpServers": {
    "Shuttle": {
      "command": "shuttle",
      "args": ["mcp", "start"]
    }
  }
}

Implementation Steps

Step 1: Project Initialization

First, we'll need to be logged in to the Shuttle CLI, you can do this by running:

shuttle login

This will redirect you to the Shuttle login page, and redirect you back to the terminal after you've logged in.

Next, let's create a new project for our task management API.

shuttle init

We just created a new project with the following options selected:

Project name: task-management-api
Directory: ~/Desktop/task-management-api
Template and Framework: A hello world template for Axum
Create a project on Shuttle: Yes (this creates a new project on the Shuttle platform)

Step 2: Writing Tasks for AI Agents

For our AI assistant to understand our intention on what we're trying to build, we'll need to write a todo.md file that contains all the necessary tasks and requirements that we want to build.

Now, let's write down the tasks that we want to build:

# Task Management API

This API will be a simple task management API, it will have a few endpoints, we'll use **Axum**, **Shuttle** and **SQLx** to build the API.

- GET /tasks - List all tasks with optional filtering
- POST /tasks - Create a new task
- GET /tasks/{id} - Get a specific task
- PUT /tasks/{id} - Update a task
- DELETE /tasks/{id} - Delete a task

## Tasks

- [ ] Install the dependencies
- [ ] Update the code to use a shared database using shuttle
- [ ] Create a migrations file for the tasks table
- [ ] Run the migrations
- [ ] Create the routes for the tasks endpoints
- [ ] Commit the changes
- [ ] Deploy the application to shuttle
- [ ] Write some tests for the production API
- [ ] Run the tests and fix the errors if any

Step 3: AI-Assisted Development

Let's tell Cursor to read the todo.md file and work through the tasks sequentially.

The todo list system is a great approach to give the AI agent a clear understanding of what we're trying to build, giving the AI agent a clear context of the details about the project.

The AI agent immediately ran the tool search_docs to search through the latest Shuttle documentation and find the relevant information needed for the the tasks.

The required migrations for the tasks have been created.

Once the tasks are complete, the AI agent will commit the changes listed in todo.md and deploy the application to Shuttle.

The AI agent then proceeds to the next step which is writing the tests to make sure the API is working as expected.

When running the tests, we can see that all the tests are failing:

The AI agent begins by debugging, gathering all the details it needs to fix the failing tests. It can also call the deployment_status and logs tools to inspect the latest deployment, scan the logs, and pinpoint the root cause.

These two tool calls provide the AI agent with everything it needs. After reviewing the results, it understands the issue and fixes the failing tests.

The issue was that axum@0.8 changed its path parameter syntax from /:id to /{id} format.

The AI agent then proceeds to fix the tests and run them again:

Running the tests again:

Perfect, the tests are now passing, and the API is working as expected.

The Power of AI Agents

What we just accomplished is remarkable - we built, deployed, and tested a complete API with a single prompt. The AI agent:

Created database migrations
Implemented CRUD endpoints
Deployed to production
Wrote comprehensive tests
Debugged and fixed issues
All autonomously

This represents a fundamental shift in how we approach software development. What traditionally took hours or days of manual work was completed in minutes through intelligent automation.

Before we celebrate, remember: AI-generated code is far from infallible. The automation is impressive, but it introduces real risks that demand our attention.

Precautions and Security Risks

AI-assisted development can supercharge productivity, yet it also opens new security fronts developers can't afford to ignore.

Critical Security Awareness

AI-generated code can contain security vulnerabilities and implementation flaws that may not be immediately obvious. AI can be confidently wrong about security implementations, error handling, business logic, etc.

Never blindly trust AI-generated code. What appears correct at first glance may hide subtle, critical security flaws, or overlook key scalability and performance implications.

Dependency Security Risks

AI may suggest outdated or unmaintained packages
Dependencies with known vulnerabilities
Packages from untrusted sources
Excessive permissions or unnecessary dependencies

Best Practices for AI-Assisted Development

The key to successful AI-assisted development is reviewing every bit of code that the AI agent writes.

Mandatory Code Review Process

ALWAYS review AI-generated code before accepting it. This is non-negotiable for production applications.

Testing AI-Generated Code

Write additional tests beyond what AI generates
Focus on edge cases and error conditions
Test security boundaries with invalid inputs
Perform integration testing with real data
Load test critical endpoints

Remember: AI may speed up development, but it doesn't guarantee secure or reliable code. It's up to you to review each change and ensure everything is secure, performant, and dependable.

Conclusion

Just a few years ago, Rust was notorious for its steep learning curve. The borrow-checker barked at nearly every line. Today, AI-powered editors like Cursor, paired with deploy-anywhere platforms such as Shuttle, make writing and shipping a Rust API almost effortless.

This is what a ridiculously productive workflow looks like. We spun up a complete Rust CRUD API from scratch, shipped it, debugged it, and even hammered the production deployment with tests. And it only took us a few minutes! This isn't a dream, it's just the reality of building with AI agents on Shuttle.

It's also important to note that while AI can be extremely helpful in accelerating development time, it's still subject to making mistakes and leaving security vulnerabilities in your code. It is always best practice to review the code and ensure you are only committing high-quality, secure, and performant code.

Develop the mentality of treating AI as a tool, not a replacement for human developers, this way you'll get work done much faster and much more efficiently without exposing your code to security vulnerabilities.

Don't just build. Create at the speed of thought

Ready to experience a true 10x developer workflow? Our AI-assisted Rust template is your launchpad into the future of software development. See what you can create when AI is your copilot:

shuttle init --from shuttle-hq/shuttle-examples --subfolder axum/ai-assisted

The Hidden Costs of Deploying Rust Microservices

Shuttle — Tue, 29 Jul 2025 12:14:42 +0000

Microservices promise speed, scale, and team autonomy. But once you deploy more than a handful, the complexity creeps in. Teams suddenly face config sprawl, CI duplication, secret management, and fractured environments.

In this article, we’ll explore the hidden operational costs of microservices, especially for Rust developers. You’ll see how Shuttle’s dev-first approach simplifies the provisioning and deployment journey, and we’ll even give you a real microservices challenge to try yourself.

Want to try it yourself?

We've built ShellCon, a real-world Rust microservices onboarding challenge where you:

Debug and deploy 3 broken services (Axum + SQLx + async Rust)

Connect them to a frontend that only works when everything is fixed

Use Shuttle to provision, deploy, and manage the full stack: no YAML or Kubernetes needed

🎯 Perfect for Rust devs who want to learn by doing.

👉 Start the ShellCon Challenge

We'll end the blog post with a special challenge for Rust developers for building Rust microservices at scale with ease. The challenge is designed to be fun and at the same time demonstrate microservice provisioning and deploying multiple microservices while using best practices.

Monolith vs Microservices

What is a monolith?

Modern applications often evolve from monoliths to microservices, and for good reason.
A monolith is a single, tightly coupled codebase running as one process. It’s simple to start but becomes harder to scale as teams and features grow. Every small change risks affecting the entire system.

Microservices, by contrast, are small, independently deployable services. They offer:

Faster development: Teams can ship features without waiting on others.
Scalable infrastructure: Only the services that need more resources get scaled.
Tech flexibility: Use Rust for performance-critical services, and Python or Go where it fits.
Resilience: One service can fail without taking the whole app down.
Team autonomy: Squads own, deploy, and monitor their own services.
Cost-effective scaling: Scale only the services that need resources, not the entire application stack.

Example: A Netflix clone might break into services like Recommendations, Streaming, Billing, and Users. With a monolith, they share the same release cycle. With microservices, each evolves and scales independently.

Microservices give you the ability to scale only the services that need the additional resources.

But while microservices sound ideal, they introduce operational complexity, especially as your system grows.

Hidden Costs of Deploying Rust Microservices

While these benefits are compelling, microservices aren't without challenges. Behind these benefits are unexpected problems that can slow you down, add extra work, and confuse your team. Managing and deploying many small services often gets messy, takes more time, and brings surprises you did not plan for.

Infrastructure management quickly becomes complex with configuration files, CI/CD pipelines, and service dependencies. The theoretical advantages of independent deployments and technology flexibility become overshadowed by infrastructure demands.

Common pitfalls of microservices

Let's dive into some of the common pitfalls of microservices. By the end of this blog post, we'll have a good understanding of the challenges and we'll talk about tools that can help us overcome these challenges.

Infrastructure as Code Complexity

Managing infrastructure with tools like Terraform becomes challenging when scaling to dozens of configuration files across multiple environments. Each service requires its own configuration files for networking, security, compute resources, and storage.

CI/CD Pipeline Proliferation

Each microservice typically requires its own CI/CD pipeline, leading to increased maintenance overhead. Teams must dedicate resources to maintaining build configurations across numerous services.

Observability Challenges

Implementing a well set up monitoring system requires integrating logging, metrics, and tracing across all services. Organizations frequently end up with disconnected monitoring tools, making incident investigation difficult when problems occur.

Domains and Certificate Management

Managing domains and SSL certificates across multiple microservices creates significant operational overhead. Each service and environment typically requires its own subdomain (api.company.com, auth.company.com, payments.company.com), and each subdomain needs SSL certificates for secure communication. They also need to be renewed periodically. Without proper tooling, this becomes extremely difficult to manage, with surprises of expired certificates.

Environment Management Complexity

Microservices multiply environment management challenges. Where a monolith might have three environments (development, staging, production), microservices often require environment parity across dozens of services.

Each service needs its own environment-specific configurations, database connections, and service discovery settings. Maintaining consistency across environments becomes extremely difficult when services have different deployment schedules and dependency requirements.

Database Proliferation and Management

Each microservice typically requires its own database to maintain data isolation and independence. This database-per-service pattern creates operational complexity that teams often underestimate.

Database provisioning, backup strategies, monitoring, and maintenance must be replicated across dozens of database instances. Each database needs its own connection pooling, and performance tuning.

Secrets and Configuration

The more services you have, the more secrets and configurations you need to manage. Without proper tooling for managing secrets and configurations, this becomes extremely difficult to manage.

Ready to experience these challenges for yourself?

We’ve built an interactive onboarding challenge using Rust and Shuttle called ShellCon. You’ll debug and optimize 3 microservices to make the frontend app work, including async Rust code, Axum HTTP routes, and SQL queries.

👉 Start the ShellCon Challenge

How Microservices Are Typically Deployed

In conventional microservices architectures, each service typically requires its own microservice deployment pipeline and infrastructure configuration. Let's examine what this traditionally looks like and understand the complexity involved.

Docker and Container Management

Most microservice deployments start with Docker. Each service needs its own Dockerfile and typically a docker-compose.yml file for local development. Here's an example of what a traditional setup might look like:

# docker-compose.yml
version: "3.8"
services:
  blog-api:
    build: ./blog-service
    ports:
      - "3001:3000"
    environment:
      - DATABASE_URL=postgresql://user:password@postgres:5432/blog_db
      - ANALYTICS_SERVICE_URL=http://analytics-service:3000
      - ANALYTICS_API_KEY=your-super-secret-api-key-here
    depends_on:
      - postgres
      - analytics-service

  analytics-service:
    build: ./analytics-service
    ports:
      - "3002:3000"
    environment:
      - DATABASE_URL=postgresql://user:password@postgres:5432/analytics_db
      - ANALYTICS_API_KEY=your-super-secret-api-key-here
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=blog_db
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres_data:

Each service will have its own Dockerfile as well. Managing these needs careful attention - you'll need to make sure that the services are compatible with each other, and that the services are compatible with the infrastructure you're using.

This is for a simple setup, however, when it comes to production environments with high traffic, you'll need multi node deployments and things get complex quickly, and you'll need to manage a lot of additional complexity:

Kubernetes manifests
Load balancer configurations with SSL termination
Service meshes like Istio
Auto-scaling groups
Network security
Database clusters

The list goes on, and the complexity increases.

Secret management also becomes extremely complex with rotation strategies, encrypted storage systems like Vault, access control policies, and certificate management across all environments.

You'll also need comprehensive monitoring and observability, once you have multiple containers across multiple nodes, this becomes extremely difficult to manage.

This traditional approach, while powerful and battle-tested, creates significant operational overhead where teams often spend most of their time managing infrastructure, Kubernetes configurations, and deployment pipelines instead of building features.

Simplify Rust Microservice Deployment with Shuttle

Luckily, we're not going to have to do all of that. With Shuttle, we can focus on building our application logic instead of wrestling with infrastructure complexity. Shuttle handles microservice provisioning, secret management, and deployment orchestration automatically, letting us deploy production-ready Rust microservices with just a few commands.

Introducing a Developer-First Approach to Infrastructure

Instead of managing infrastructure separately, we can manage it directly in our application code, using the same tools and languages we already know.

Shuttle embodies this approach by removing the complexity of managing infrastructure and deployment. Rather than dealing with Terraform or cloud consoles, you define resources like databases and secrets using straightforward Rust attributes.

In this tutorial, we'll build multiple interconnected Rust microservices with Axum and then deploy them to the cloud with Shuttle. We'll create a Blog API service and an Analytics service that communicate with each other, demonstrating true microservices architecture with service-to-service communication.

Building Multiple Microservices with Shuttle

For this example, we'll build two interconnected services:

Analytics Service - Tracks and processes blog post views and interactions
Blog API Service - Manages blog posts and sends analytics events

Let's start by installing the Shuttle CLI:

Linux and macOS

curl -sSfL https://www.shuttle.dev/install | bash

Windows (PowerShell)

iwr https://www.shuttle.dev/install-win | iex

shuttle login

Install the sqlx-cli

To be able to use sqlx and interact with the database, we'll need to install the sqlx-cli tool. This particular command sets it up for postgres only.

# Install sqlx-cli (if not already installed)
cargo install sqlx-cli --no-default-features --features native-tls,postgres

Source Code

The complete source code for the microservices we'll build is available on GitHub: Shuttle Microservices Demo You can clone the repository to follow along or reference the final implementation.

Creating the Analytics Service

Create the first project for our analytics service:

shuttle init --template axum

Add dependencies for the analytics service:

cargo add shuttle-shared-db serde sqlx serde_json \
    --features shuttle-shared-db/postgres,shuttle-shared-db/sqlx \
    --features serde/derive

To use sqlx properly to interact with the database, we'll need to set up a local database and set the DATABASE_URL environment variable in the .env file.

To create a database, the easiest way to do it is by using Docker, you'll need to have docker installed on your machine, if you haven't already, make sure you install it here for your specific operating system.

Once you have docker installed, you can run the following command to create a database:

docker run -d --name postgres --restart=always -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password -p 5432:5432 postgres

Once your database is ready to accept connections, you can set up the analytics database:

Make sure you add .env to your .gitignore file.

echo ".env" >> .gitignore

Update the migration file:

-- migrations/<timestamp>_create_events.sql
CREATE TABLE events (
    id SERIAL PRIMARY KEY,
    event_type VARCHAR NOT NULL,
    post_id INTEGER,
    data JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

Run the migration:

cargo sqlx migrate run

Securing service communication

In order to secure the communication between the analytics service and the blog service, we'll need a way to verify the identity of the requester. To do that, we'll have a secret key that only the two services know about. If the requester has the correct secret key, the request will be allowed to proceed, otherwise it will be rejected.

Secret management with Shuttle

The secret key must be kept secret, therefore it must not be committed to version control and must be handled securely using proper tooling. For that, Shuttle provides us a way to define secrets in a secure manner, by giving us a macro that we can use directly in our application code. To define the secrets, Shuttle expects a Secrets.toml file in the root of the project.

The Secrets.toml file is a simple configuration file that contains the secrets for the project. It's a TOML file, which is a simple configuration file format that is easy to read and write.

Create the Secrets.toml file:

# Secrets.toml
ANALYTICS_API_KEY = "your-super-secret-api-key-here"

We can use the ANALYTICS_API_KEY secret in the code with the #[shuttle_runtime::Secrets] macro:

#[shuttle_runtime::main]
async fn main( #[shuttle_runtime::Secrets] secrets: SecretStore) -> shuttle_axum::ShuttleAxum {
    let api_key = secrets.get("ANALYTICS_API_KEY").expect("ANALYTICS_API_KEY must be set");

    // Use the api_key anywhere in your code...

    Ok(router.into())
}

Database provisioning with Shuttle

Shuttle provides an easy way to provision databases, just by adding a macro to your main.rs file, you'll have a database set up and connected to after you deploy to Shuttle.

#[shuttle_runtime::main]
async fn main(
    #[shuttle_shared_db::Postgres] pool: PgPool,
) -> shuttle_axum::ShuttleAxum {
    ...
}

To make development easier, you can set your own local_uri to connect to your local database.

#[shuttle_runtime::main]
async fn main(
    #[shuttle_shared_db::Postgres(
        local_uri = "postgres://postgres:password@localhost:5432/analytics_db"
    )] pool: PgPool,
) -> shuttle_axum::ShuttleAxum {
    ...
}

Now, let's implement the routes for the service, we'll have two routes, one for receiving events and one for getting statistics.

For the full version of the code, see the GitHub repository here.

async fn receive_event(
    State(state): State<AppState>,
    Json(event): Json<AnalyticsEvent>,
) -> StatusCode {
    let result = sqlx::query!(
        "INSERT INTO events (event_type, post_id, data) VALUES ($1, $2, $3)",
        event.event_type,
        event.post_id,
        event.data
    )
    .execute(&state.db)
    .await;

    match result {
        Ok(_) => StatusCode::CREATED,
        Err(_) => StatusCode::INTERNAL_SERVER_ERROR,
    }
}

async fn get_stats(State(state): State<AppState>) -> Json<Vec<EventStats>> {
    let stats = sqlx::query_as!(
        EventStats,
        "SELECT event_type, COUNT(*) as count FROM events GROUP BY event_type"
    )
    .fetch_all(&state.db)
    .await
    .unwrap_or_default();

    Json(stats)
}

Having a look at this snippet in the code:

#[shuttle_runtime::main]
async fn main(
    #[shuttle_shared_db::Postgres(
        local_uri = "postgres://postgres:password@localhost:5432/analytics_db"
    )] pool: PgPool,
    #[shuttle_runtime::Secrets] secrets: SecretStore,
) -> shuttle_axum::ShuttleAxum {
    ...
}

Connecting to a database using Shuttle is as simple as adding a macro to your main.rs file. This macro will automatically provision a database for you. The local_uri is used to connect to your local database for development purposes.

For managing secrets, we have used the #[shuttle_runtime::Secrets] attribute provided by Shuttle that will automatically load the secrets from the Secrets.toml. Shuttle will automatically push the secrets to the cloud in a secure manner when running shuttle deploy.

Let’s build a middleware function to authenticate requests using the ANALYTICS_API_KEY from the Secrets.toml file. This way, only our blog service can send analytics events to the analytics service.

async fn auth_middleware(
    headers: HeaderMap,
    State(state): State<AppState>,
    request: axum::extract::Request,
    next: axum::middleware::Next,
) -> Result<axum::response::Response, StatusCode> {
    let auth_header = headers
        .get("Authorization")
        .and_then(|header| header.to_str().ok())
        .and_then(|header| header.strip_prefix("Bearer "));

    match auth_header {
        Some(token) if token == state.api_key => Ok(next.run(request).await),
        _ => Err(StatusCode::UNAUTHORIZED),
    }
}

Deploying the Analytics Service

Before we deploy the service, we'll need to follow another step that is specific to sqlx, we'll need to prepare the SQL queries for production so that the code can compile without the need for an active database connection, you can read more about how sqlx works here.

Prepare the SQL queries for production

cargo sqlx prepare

Make sure you commit the generated metadata by SQLx.

# Commit the generated metadata by SQLx
git add .
git commit -m "Prepare SQL queries for production"

Deploy the service

Deploying services with Shuttle is as simple as running shuttle deploy in the root of the project.

shuttle deploy

This will deploy the service to the cloud, you'll see the deployed URL in the console, we'll use this URL in our blog service to send analytics events to the analytics service.

Creating the Blog API Service

Now let's create our blog service that will depend on the analytics service:

shuttle init --template axum

Add the required dependencies for our blog service:

cargo add shuttle-shared-db serde reqwest tokio sqlx serde_json \
    --features shuttle-shared-db/postgres,shuttle-shared-db/sqlx \
    --features serde/derive \
    --features reqwest/json \
    --features tokio/full

Set up the database environment:

# Create .env file for local development
echo "DATABASE_URL=postgres://postgres:password@localhost:5432/blog_db" > .env

# Create the database
cargo sqlx database create

# Create migration
cargo sqlx migrate add create_posts

Add .env to your .gitignore file.

echo ".env" >> .gitignore

Update the migration file:

-- migrations/<timestamp>_create_posts.sql
CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    title VARCHAR NOT NULL,
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

Run the migration:

cargo sqlx migrate run

Create a Secrets.toml file for configuration:

# Secrets.toml
ANALYTICS_SERVICE_URL = "https://analytics-service-m7iz.shuttle.app" # Replace with your analytics service URL
ANALYTICS_API_KEY = "your-super-secret-api-key-here"

Now let's implement our blog service with analytics tracking. We’re going to implement a few routes: Create a post, get a post and get a list of all posts. See the source code here.

async fn create_post(
    State(state): State<AppState>,
    Json(payload): Json<CreatePost>,
) -> Result<Json<Post>, StatusCode> {
        ...
}

async fn get_posts(State(state): State<AppState>) -> Json<Vec<Post>> {
        ...
}

async fn get_post(
    Path(id): Path<i32>,
    State(state): State<AppState>,
) -> Result<Json<Post>, StatusCode> {
    ...
}

Service to service secure communication

To send events to the analytics services, we’ll need to create a new function to send analytics events to the analytics service, this function is used to communicate with the analytics service using secure HTTP requests.

async fn send_analytics_event(state: &AppState, event: AnalyticsEvent) -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let _response = client
        .post(&format!("{}/events", state.analytics_url))
        .header("Authorization", format!("Bearer {}", state.analytics_api_key))
        .json(&event)
        .send()
        .await?;

    Ok(())
}

We have used the ANALYTICS_SERVICE_URL and ANALYTICS_API_KEY from the Secrets.toml file to send the analytics event to the analytics service. This way both services are independent of each other, they have their own databases and can be deployed independently.

To make this communication secure, we have used the ANALYTICS_API_KEY to authenticate the request to the analytics service.

Deploy the blog service

The process is similar to the analytics service, we'll need to prepare the SQL queries for production and deploy the service.

cargo sqlx prepare

Commit the generated metadata by SQLx.

git add .
git commit -m "Prepare SQL queries for production"

Deploy the service using Shuttle:

shuttle deploy

🎉 Great! Now both of our services are deployed and ready to use.

Testing the services

Let's test the services and make sure they're working as expected:

# Create a blog post (this will trigger an analytics event)
curl -X POST https://blog-service-3hhs.shuttle.app/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "My First Post", "content": "Hello microservices!"}'

# Response
{"id":1,"title":"My First Post","content":"Hello microservices!"}

# View the post (this will trigger another analytics event)
curl https://blog-service-3hhs.shuttle.app/posts/1

# Response
{"id":1,"title":"My First Post","content":"Hello microservices!"}

# Check analytics stats
curl -s https://analytics-service-m7iz.shuttle.app/stats | jq
[
  {
    "event_type": "post_viewed",
    "count": 2
  },
  {
    "event_type": "post_created",
    "count": 1
  }
]

Great! Our services are working as expected, we have a blog service that can create and view posts, and an analytics service that can track analytics events.

Traditional vs Shuttle: Microservice Deployment Complexity Comparison

Comparing this approach with the traditional approach, we can see that we no longer need to manage multiple configuration files and orchestration tools - we can focus on building our application logic instead. With this approach, teams can focus on building smaller Rust microservices without worrying about the infrastructure, secrets management, and observability tools. This makes microservice deployment much faster and easier.

Aspect	Traditional Setup (Docker/Kubernetes/Terraform)	Shuttle Setup
Infrastructure Management	Manual configuration of Dockerfiles, docker-compose.yml, Kubernetes manifests, and Terraform files	Automated infrastructure provisioning through Shuttle
Database Provisioning	Manual setup of PostgreSQL containers, volumes, and Terraform database resources	Automatic database provisioning with Shuttle's shared database feature
Secret Management	Environment variables in docker-compose.yml, Kubernetes secrets, or external tools like Vault	Integrated secret management using Shuttle's Secrets.toml
Deployment Complexity	Requires manual deployment steps, CI/CD pipeline configuration, and Kubernetes/Terraform orchestration	Simple deployment with `shuttle deploy` command
Scalability	Manual configuration of Kubernetes HPA, scaling policies, and load balancers	Built-in scalability features with Shuttle
Monitoring	Requires additional monitoring tools, Prometheus setup, and configuration	Integrated monitoring capabilities with Shuttle
Development Experience	Complex setup for local development with Docker, minikube, or kind clusters	Simplified development experience with Shuttle's local development features

Ready to Try It Yourself? Build Microservices with Rust & Shuttle

Now that you have everything you need to build Rust microservices with Shuttle, we have a challenge for you, in this challenge we put everything we learned together to build a simple microservices architecture application.

The challenge is designed to be fun and at the same time improve your skills and knowledge of building Rust microservices.

The challenge is available on GitHub, you can clone the repository and follow the instructions to complete the challenge.

Conclusion

Microservices provide a variety of benefits - isolating different parts of your application makes deployment easier, enhances security and scalability. This way you can scale only the services that need the additional resources.

However, this doesn't come without a cost. Adding more microservices means more complexity and infrastructure management, which makes development slower and more difficult.

Using Shuttle can make microservice deployment easier. Without having to deal with the complexity of managing infrastructure, you can focus on building your application. You no longer have to worry about microservice provisioning, managing secrets, or managing your CI/CD pipeline. Learn more about building Rust web applications with Shuttle.

This makes development easier and much faster, putting you ahead of the curve. You can focus on shipping rather than managing infrastructure.

Choosing the Right Rust Web Framework: An Overview

Shuttle — Wed, 23 Aug 2023 13:44:22 +0000

Author: Stefan Baumgartner; Owner at Oida.dev; Rust Linz Organizer

In the dynamic landscape of web development, Rust has emerged as a language of choice for building safe and performant applications. As Rust's popularity grows, so does the array of web frameworks designed to harness its strengths. This article compares some of the best Rust frameworks highlighting their respective advantages and drawbacks to help you make informed decisions for your projects. It also takes a lookout on frameworks to look out for, as they might change how we build web applications in Rust.

Since most of the web frameworks feel very similar in use at a first glance, the differences are much more nuanced and in detail. I hope to highlight the most important differences in text, but to give you a better idea, I also show example code with every framework that does more than a simple hello world. All the examples are taken from the respective GitHub repos.

Also note that this list is by no means exhaustive, and I definitely missed some of the frameworks that are out there. If you want to have your favourite framework included, please reach out to me on Twitter or Mastodon.

The Popular Rust Frameworks

Axum

Axum is a web application framework with a special standing in the Rust ecosystem. It is part of the Tokio project, which the runtime for writing asynchronous network applications with Rust. Not only does Axum use Tokio as its asynchronous runtime, but it also integrates with other libraries from the Tokio ecosystem, making use of Hyper as its HTTP server and Tower for middleware. In doing so, developers are able to reuse existing libraries and tools from the Tokio ecosystem.

Axum also strives to deliver a best in class developer experience without relying on macros, but rather leveraging Rust's type system to provide a safe and ergonomic API. This is achieved by using traits to define the core abstractions of the framework, such as the Handler trait, which is used to define the core logic of an application. This approach allows developers to easily compose applications from smaller components, which can be reused across multiple applications.

A handler in Axum is a function that takes a request and returns a response. This is similar to other backend frameworks, but with Axum's FromRequest trait, developers can specify the types of data that should be extracted from the request. The return type needs to implement the IntoResponse trait, and there are already a number of types that implement this trait, including tuple types that allow to easily change e.g. the status code of a response.

Whenever you work with Rust's type system, generics and especially async methods in traits (or more concretely: a returned Future), you know how complex Rust's error messages can get when you don't satisfy a trait bound. Especially when you try to match abstract trait bounds, it happens ever so often that you get a wall of text that is hard to decipher. Change the order of a few lines, and nothing works anymore! Axum provides a library with helper macros that put the error to where it actually happens, making it easier to understand what went wrong.

Axum does a lot of things right, and it's very easy to get applications started that do a lot. However, there are some things that you need to look out for. The version is still below 1.0, and the Axum team takes the liberty to change APIs fundamentally between versions, which can cause your apps to break big time. That's the deal with 0.x versions, we know, but some changes appear to be so subtle, yet require you to develop a different mental model of how things work underneath. If you included a Timeout layer (built-in in Tower, yay!), it worked easily in one version, needed a catch-all error handler in another, and an tied error handler in the next. This is not a big deal, but it can be frustrating when you're trying to get things done or you start a project with the latest version and things suddenly work differently. Also while you are able to leverage the entire Tokio ecosystem, you sometimes need to deal with glue types and traits, rather then going to the Tokio functions directly. One example is the use of anything stream and (web) socket related.

The good examples help, but you need to keep track.

Nonetheless, Axum is my personal favourite, and also the framework I use for Shuttle Launchpad. I love the expressiveness and the concepts underneath, and there hasn't been a thing that I wanted to solve that I couldn't do inutitively by understanding the right concepts. If you want to get to know the Axum concepts, check out my slides from my Tokio + Microservices workshop.

Axum Example

An abbreviated example from the Axum repo showing a WebSocket handler that echos any message it receives.

#[tokio::main]
async fn main() {
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();
    println!("listening on {}", listener.local_addr().unwrap());
    axum::serve(listener, app()).await.unwrap();
}

fn app() -> Router {
    // WebSocket routes can generally be tested in two ways:
    //
    // - Integration tests where you run the server and connect with a real WebSocket client.
    // - Unit tests where you mock the socket as some generic send/receive type
    //
    // Which version you pick is up to you. Generally we recommend the integration test version
    // unless your app has a lot of setup that makes it hard to run in a test.
    Router::new()
        .route("/integration-testable", get(integration_testable_handler))
        .route("/unit-testable", get(unit_testable_handler))
}

// A WebSocket handler that echos any message it receives.
//
// This one we'll be integration testing so it can be written in the regular way.
async fn integration_testable_handler(ws: WebSocketUpgrade) -> Response {
    ws.on_upgrade(integration_testable_handle_socket)
}

async fn integration_testable_handle_socket(mut socket: WebSocket) {
    while let Some(Ok(msg)) = socket.recv().await {
        if let Message::Text(msg) = msg {
            if socket
                .send(Message::Text(format!("You said: {msg}")))
                .await
                .is_err()
            {
                break;
            }
        }
    }
}

Axum in a Nutshell

Macro-free API.
Strong ecosystem by leveraging Tokio, Tower, and Hyper.
Great developer experience.
Still in 0.x, so breaking changes can happen.

Actix

Actix is one of Rust's web frameworks that has been around for a while, and thus is very popular. Like any good open source project it has seen many iterations, but it has reached major versions other than 0 and keeps its stability guarantees: Within a major version, you can be sure that there are no breaking changes.

When we talk Actix, we specifically talk about Actix Web, which is the web framework part of the Actix project. Actix itself is a project that provides a number of libraries for building concurrent applications, and is based on the actor model. The "Web" part of Actix abstracts lot of the actor model away, and provides a more traditional web framework API.

At a first glance, Actix looks very familiar to other web frameworks in Rust. You use macros to define HTTP methods and routes (like Rocket), and you use extractors to get data from the request (like Axum). The similarities with Axum are striking, also in how they name concepts and traits. The biggest difference is that Actix does not tie itself to strong to the Tokio ecosystem. While Tokio is still the runtime underneath Actix, the framework comes with its own abstractions and traits, and also with its own ecosystem of crates. This has pros and cons. On one hand, you can be sure that things usually work well together, on the other hand you might miss out on a lot of things that are already available in the Tokio ecosystem.

One thing that strikes me odd is that Actix implements its own Service trait, which is basically the same as Tower's, but still incompatible. Which means that most of the available Middleware in the Tower ecosystem is not available for Actix.

What's also interesting is that if you need some special tasks in Actix that you need to implement on your own, you might get confronted with the Actor model that runs everything in the framework. This might add some layers of complexity that you might not want to deal with.

But the community around Actix delivers. The framework supports HTTP/2 and Websocket upgrades, it has crates and guides for the most common tasks in a web framework, excellent (and I mean excellent) documentation, and it's fast. Actix is popular for a reason, and if you need to keep version guarantees, it might be your best choice right now.

Actix Example

A simple websocket echo server in Actix looks like this:

use actix::{Actor, StreamHandler};
use actix_web::{web, App, Error, HttpRequest, HttpResponse, HttpServer};
use actix_web_actors::ws;

/// Define HTTP actor
struct MyWs;

impl Actor for MyWs {
    type Context = ws::WebsocketContext<Self>;
}

/// Handler for ws::Message message
impl StreamHandler<Result<ws::Message, ws::ProtocolError>> for MyWs {
    fn handle(&mut self, msg: Result<ws::Message, ws::ProtocolError>, ctx: &mut Self::Context) {
        match msg {
            Ok(ws::Message::Ping(msg)) => ctx.pong(&msg),
            Ok(ws::Message::Text(text)) => ctx.text(text),
            Ok(ws::Message::Binary(bin)) => ctx.binary(bin),
            _ => (),
        }
    }
}

async fn index(req: HttpRequest, stream: web::Payload) -> Result<HttpResponse, Error> {
    let resp = ws::start(MyWs {}, &req, stream);
    println!("{:?}", resp);
    resp
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| App::new().route("/ws/", web::get().to(index)))
        .bind(("127.0.0.1", 8080))?
        .run()
        .await
}

Actix in a Nutshell

Strong, self-contained ecosystem.
Actor model based.
Stable API via major version guarantees.
Fantastic documentation.

Rocket

Rocket has been the star in the Rust web framework ecosystem for quite a while, with it's unapologetic approach to developer experience, the reliance on familar and existing concepts, and its ambitious goal to provide a batteries-included experience.

You can see its ambitions when you enter their beautiful website: Macro-based routing, built-in form handling, support for databases and state management, and its own veersion of templating! Rocket really tries to get everything done that you need to build a web application.

However, Rocket's ambitions take their toll. While still being actively developed, the releases are not as frequent as they used to be. Which means that users of the framework miss out on a lot of important stuff.

Also, with it's batteries-included approach, you also need to learn how Rocket does things. Rocket apps have a lifecycle, the building blocks are connected in a particular way, and if something goes wrong, you need to understand what goes wrong.

Rocket is a great framework, and if you want to get started with Rust web development, it's a great choice. Personally, I have a soft spot for Rocket and I hope that development picks up. For many of us, Rocket was the first segue into Rust, and it's still fun to develop with it. Nonetheless, I usually rely on features that are not available in Rocket, and thus I don't use it in production.

Rocket Example

An abbreviated example of a Rocket application that deals with forms from their example repo:

#[derive(Debug, FromForm)]
struct Password<'v> {
    #[field(validate = len(6..))]
    #[field(validate = eq(self.second))]
    first: &'v str,
    #[field(validate = eq(self.first))]
    second: &'v str,
}

#[derive(Debug, FromForm)]
#[allow(dead_code)]
struct Submission<'v> {
    #[field(validate = len(1..))]
    title: &'v str,
    date: Date,
    #[field(validate = len(1..=250))]
    r#abstract: &'v str,
    #[field(validate = ext(ContentType::PDF))]
    file: TempFile<'v>,
    ready: bool,
}

#[derive(Debug, FromForm)]
#[allow(dead_code)]
struct Account<'v> {
    #[field(validate = len(1..))]
    name: &'v str,
    password: Password<'v>,
    #[field(validate = contains('@').or_else(msg!("invalid email address")))]
    email: &'v str,
}

#[derive(Debug, FromForm)]
#[allow(dead_code)]
struct Submit<'v> {
    account: Account<'v>,
    submission: Submission<'v>,
}

#[get("/")]
fn index() -> Template {
    Template::render("index", &Context::default())
}

// NOTE: We use `Contextual` here because we want to collect all submitted form
// fields to re-render forms with submitted values on error. If you have no such
// need, do not use `Contextual`. Use the equivalent of `Form<Submit<'_>>`.
#[post("/", data = "<form>")]
fn submit<'r>(form: Form<Contextual<'r, Submit<'r>>>) -> (Status, Template) {
    let template = match form.value {
        Some(ref submission) => {
            println!("submission: {:#?}", submission);
            Template::render("success", &form.context)
        }
        None => Template::render("index", &form.context),
    };

    (form.context.status(), template)
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .mount("/", routes![index, submit])
        .attach(Template::fairing())
        .mount("/", FileServer::from(relative!("/static")))
}

Rocket in a Nutshell

Batteries-included approach.
Great developer experience.
Not as actively developed as it used to be.
Still a great choice for beginners.

The Experimental Rust Frameworks

Warp

Oh, Warp! You are a beautiful, strange, and powerful beast. Warp is a web framework that is built on top of Tokio, and it's a very good one. It's also very different from the other frameworks that we have seen so far.

Warp shares a few common traits (haha!) with Axum: It's built on Tokio and Hyper, and makes use of Tower middleware. However, it's very different in its approach. Warp is built on top of the Filter trait.

In Warp, you build a pipeline of filters that are applied to the incoming request, and the request is passed through the pipeline until it reaches the end. Filters can be chained, and they can be composed. This allows you to build very complex pipelines that are still easy to understand.

Warp is also a bit closer to the Tokio ecosystem than Axum, which means that you might deal with more Tokio structs and concepts without any glue traits.

Warp takes a very functional approach and if that's your style of programming you are going to love the expressiveness and composability of Warp. When you look at a piece of Warp code, it often reads like a story of what's happening, and it's fun and amazing that this works in Rust.

You might want to turn off inlay hints in your Rust Analyzer setting, though. With all those different functions and filters being chained, the types in Warp get very long and very complex, and also hard to decipher. Same goes for error messages, which can be pages of text that are hard to understand.

Also, while the filter concept is great once you get through, sometimes you want to have the declarative router, handler and extractor style that you get with, well, all the other frameworks.

Warp is a great framework, and I love it. However, it's not the most beginner-friendly framework, and it's also not the most popular one. Which means that you might have a harder time finding help and resources. But it's fun for quick and little apps, and it's experimental style might give you new ideas!

Warp Example

An abbreviated example of a websocket chat from their example repo:

static NEXT_USER_ID: AtomicUsize = AtomicUsize::new(1);

/// Our state of currently connected users.
///
/// - Key is their id
/// - Value is a sender of `warp::ws::Message`
type Users = Arc<RwLock<HashMap<usize, mpsc::UnboundedSender<Message>>>>;

#[tokio::main]
async fn main() {
    let users = Users::default();
    // Turn our "state" into a new Filter...
    let users = warp::any().map(move || users.clone());

    // GET /chat -> websocket upgrade
    let chat = warp::path("chat")
        // The `ws()` filter will prepare Websocket handshake...
        .and(warp::ws())
        .and(users)
        .map(|ws: warp::ws::Ws, users| {
            // This will call our function if the handshake succeeds.
            ws.on_upgrade(move |socket| user_connected(socket, users))
        });

    // GET / -> index html
    let index = warp::path::end().map(|| warp::reply::html(INDEX_HTML));

    let routes = index.or(chat);

    warp::serve(routes).run(([127, 0, 0, 1], 3030)).await;
}

async fn user_connected(ws: WebSocket, users: Users) {
    // Use a counter to assign a new unique ID for this user.
    let my_id = NEXT_USER_ID.fetch_add(1, Ordering::Relaxed);

    eprintln!("new chat user: {}", my_id);

    // Split the socket into a sender and receive of messages.
    let (mut user_ws_tx, mut user_ws_rx) = ws.split();

    let (tx, rx) = mpsc::unbounded_channel();
    let mut rx = UnboundedReceiverStream::new(rx);

    tokio::task::spawn(async move {
        while let Some(message) = rx.next().await {
            user_ws_tx
                .send(message)
                .unwrap_or_else(|e| {
                    eprintln!("websocket send error: {}", e);
                })
                .await;
        }
    });

    // Save the sender in our list of connected users.
    users.write().await.insert(my_id, tx);

    // Return a `Future` that is basically a state machine managing
    // this specific user's connection.

    // Every time the user sends a message, broadcast it to
    // all other users...
    while let Some(result) = user_ws_rx.next().await {
        let msg = match result {
            Ok(msg) => msg,
            Err(e) => {
                eprintln!("websocket error(uid={}): {}", my_id, e);
                break;
            }
        };
        user_message(my_id, msg, &users).await;
    }

    // user_ws_rx stream will keep processing as long as the user stays
    // connected. Once they disconnect, then...
    user_disconnected(my_id, &users).await;
}

async fn user_message(my_id: usize, msg: Message, users: &Users) {
    // Skip any non-Text messages...
    let msg = if let Ok(s) = msg.to_str() {
        s
    } else {
        return;
    };

    let new_msg = format!("<User#{}>: {}", my_id, msg);

    // New message from this user, send it to everyone else (except same uid)...
    for (&uid, tx) in users.read().await.iter() {
        if my_id != uid {
            if let Err(_disconnected) = tx.send(Message::text(new_msg.clone())) {
                // The tx is disconnected, our `user_disconnected` code
                // should be happening in another task, nothing more to
                // do here.
            }
        }
    }
}

async fn user_disconnected(my_id: usize, users: &Users) {
    eprintln!("good bye user: {}", my_id);

    // Stream closed up, so remove from the user list
    users.write().await.remove(&my_id);
}

Warp in a Nutshell

Functional approach.
Very expressive.
Strong ecosystem by being close to Tokio, Tower, and Hyper.
Not the most beginner-friendly framework.

Tide

Tide is a very minimalistic web framework that is built on top of the async-std runtime. The minimalistic approach means that you get a very small API surface. Handler functions in Tide are async fns that take a Request and return a tide::Result of a Response. Extracting data or sending the right response format is up to you.

While this is arguably more work for you, it's also a lot more direct, meaning that you have full control over what's happening. For some cases, being able to be so close to HTTP request and response is a delight and makes things easier.

Its middleware approach is similar to what you know from Tower, but Tide exposes the async trait crate to make implementation a lot easier. Since Tide is implement by folks who are also involved in the Rust async ecosystem, you can expect things like proper async methods in traits which recently landed in Nightly, to be adopted quickly.

Tide Example

User sessions example from their example repo.

#[async_std::main]
async fn main() -> Result<(), std::io::Error> {
    femme::start();
    let mut app = tide::new();
    app.with(tide::log::LogMiddleware::new());

    app.with(tide::sessions::SessionMiddleware::new(
        tide::sessions::MemoryStore::new(),
        std::env::var("TIDE_SECRET")
            .expect(
                "Please provide a TIDE_SECRET value of at \
                      least 32 bytes in order to run this example",
            )
            .as_bytes(),
    ));

    app.with(tide::utils::Before(
        |mut request: tide::Request<()>| async move {
            let session = request.session_mut();
            let visits: usize = session.get("visits").unwrap_or_default();
            session.insert("visits", visits + 1).unwrap();
            request
        },
    ));

    app.at("/").get(|req: tide::Request<()>| async move {
        let visits: usize = req.session().get("visits").unwrap();
        Ok(format!("you have visited this website {} times", visits))
    });

    app.at("/reset")
        .get(|mut req: tide::Request<()>| async move {
            req.session_mut().destroy();
            Ok(tide::Redirect::new("/"))
        });

    app.listen("127.0.0.1:8080").await?;

    Ok(())
}

Tide in a Nutshell

Minimalistic approach.
Uses async-std runtime.
Simple handler functions.
Playground of async features.

Poem

A program is like a poem, you cannot write a poem without writing it. --- Dijkstra

Poem's Readme file greets you with these words. Poem claims to be a fully featured yet easy to use web framework. Bold claims, but Poem seems to deliver. At a first glance, it's usage is very similar to Axum, with the only difference that you need to mark handler functions with the respective macro. It also builds on Tokio and Hyper, and is fully compatible with Tower middleware, while still exposing its own middleware trait.

Poem's middleware trait is also dead-simple to use. You can either implement the trait directly for all or specific Endpoints (Poem's way of expressing everything that can handle HTTP requests), or you just write an async function that accepts an Endpoint as parameter. After dealing and sometimes struggling with Tower and the Service Trait for such a long time, this is a breath of fresh air.

Not only is Poem compatible with a lot of features from the broader ecosystem, it's also jam-packed with features itself, including full support for OpenAPI and Swagger docs. And it's not limited to HTTP based web services, it can also be used for gRPC services based on Tonic, or even in Lambda functions, without the need to switch frameworks. Add support for OpenTelemetry, Redis, Prometheus, and a lot more, and you check off all the boxes of a modern web framework for enterprise grade applications.

Poem is still in a 0.x version, but if it keeps momentum and delivers a solid 1.0, this is a framework to look out for!

Poem Example

An abbreviated version of the websocket chat from their example repo:

#[handler]
fn ws(
    Path(name): Path<String>,
    ws: WebSocket,
    sender: Data<&tokio::sync::broadcast::Sender<String>>,
) -> impl IntoResponse {
    let sender = sender.clone();
    let mut receiver = sender.subscribe();
    ws.on_upgrade(move |socket| async move {
        let (mut sink, mut stream) = socket.split();

        tokio::spawn(async move {
            while let Some(Ok(msg)) = stream.next().await {
                if let Message::Text(text) = msg {
                    if sender.send(format!("{name}: {text}")).is_err() {
                        break;
                    }
                }
            }
        });

        tokio::spawn(async move {
            while let Ok(msg) = receiver.recv().await {
                if sink.send(Message::Text(msg)).await.is_err() {
                    break;
                }
            }
        });
    })
}

#[tokio::main]
async fn main() -> Result<(), std::io::Error> {
    let app = Route::new().at("/", get(index)).at(
        "/ws/:name",
        get(ws.data(tokio::sync::broadcast::channel::<String>(32).0)),
    );

    Server::new(TcpListener::bind("127.0.0.1:3000"))
        .run(app)
        .await
}

Poem in a Nutshell

Vast feature set.
Compatible with the Tokio ecosystem.
Easy to use.
Adaptable for gRPC and Lambda.

On the Lookout

Pavex

Initially I said that all Rust web frameworks look very similar at first glance. They are different in nuances, and sometimes do things better than others.

Pavex is the exception to that rule. Pavex is currently being implemented by no other than Luca Palmieri, the author of the popular Zero To Production book. You can say without a doubt that Luca knows what he is doing, and all his ideas and experience are going into Pavex.

Pavex is significantly different as it sees itself as a specialized compiler for building Rust APIs. It takes a high-level description of what your application should do, and the compiler a standalone API Server SDK crate, ready to be configured and launched.

Pavex is still in its early stages, but it's definitely a project to keep an eye on. Check out Luca's blog post for more information.

Conclusion

As you can see, the world of Rust web frameworks is very diverse. There is no one-size-fits-all solution, and you need to pick the framework that fits your needs best. If you are just starting out, I recommend you to go with Actix or Axum, as they are the most beginner-friendly frameworks and they have gread documentation. Personally, I'm interested on what Pavex will bring to the table, and to be honest, after being a long time Axum user, I'm really interested in checking out Poem.

And obviously, all of the major Rust web frameworks work with Shuttle, so try them out and see what works best for you!