Boilerplate Rust
MCP (Model Context Protocol) boilerplate template in Rust - A comprehensive framework for building MCP servers with multiple transport layers and example implementations
Ask AI about Boilerplate Rust
Powered by Claude Β· Grounded in docs
I know everything about Boilerplate Rust. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Boilerplate Rust
Version 0.6.3 | Production-Ready Multi-Transport MCP Server | PostgreSQL via PostgREST
A production-ready Rust implementation of the Model Context Protocol (MCP) 2025-11-25 specification featuring 6 transport modes, comprehensive observability, and enterprise-grade tooling.
Features
- MCP 2025-11-25 Compliant - Full spec implementation
- 6 Transport Modes - Stdio, SSE, WebSocket, HTTP, HTTP Streaming, gRPC
- Elicitation - Form and URL modes for user input collection
- Sampling with Tools - LLM completion with tool calling
- Structured Content - Output schema validation
- Task Management - Long-running async operations
- OAuth 2.1 - RFC 8414, RFC 9728 compliant
- JWT Authentication - Complete auth system
- 4 Auto-Generated SDKs - TypeScript, Python, Go, Rust
- Load Balancing - 5 strategies, health checks, auto-failover
- Observability - OpenTelemetry + Prometheus
Quick Start
Prerequisites
# Rust 1.75+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Install & Run
# Clone
git clone https://github.com/netadx/mcp-boilerplate-rust
cd mcp-boilerplate-rust
# Build
cargo build --release --features "http,auth"
# Run stdio server
./target/release/mcp-boilerplate-rust
# Run HTTP server
./target/release/mcp-boilerplate-rust --mode http
# Run tests
cargo test --features "http,auth"
Test with MCP Inspector
npx @modelcontextprotocol/inspector ./target/release/mcp-boilerplate-rust
MCP 2025-11-25 Features
Elicitation
Collect user input via forms or external URLs.
// Form mode
let request = ElicitationRequest::form("Enter your details")
.with_string_field("name", "Your name", true)
.with_email_field("email", "Contact email", true)
.with_enum_field("plan", vec!["free", "pro", "enterprise"], true)
.build();
// URL mode (OAuth, payments)
let request = ElicitationRequest::url_with_callback(
"Authenticate with GitHub",
"https://github.com/login/oauth/authorize",
"https://api.example.com/callback"
);
Sampling with Tools
Request LLM completions with tool calling support.
let request = SamplingRequest::new("You are a helpful assistant")
.add_user_message("What's the weather in Tokyo?")
.with_tools(vec![weather_tool])
.with_tool_choice(ToolChoice::Auto)
.with_max_tokens(1000)
.build();
Structured Content
Validate tool outputs against JSON Schema.
let validator = OutputValidator::new(schema);
let result = StructuredOutput::new()
.text("Temperature is 22.5Β°C")
.structured(json!({"temperature": 22.5, "unit": "celsius"}))
.build_validated(&validator)?;
Task Management
Handle long-running operations asynchronously.
let task = manager.create_task(CreateTaskRequest {
tool_name: "process_file".to_string(),
arguments: json!({"file": "large.csv"}),
}).await?;
// Track progress
manager.update_progress(&task.id, 50).await?;
// Complete
manager.complete_task(&task.id, result).await?;
Transport Modes
| Mode | Use Case | Command |
|---|---|---|
| Stdio | Desktop apps, Claude Desktop | cargo run --release |
| HTTP | REST APIs | cargo run --release --features http -- -m http |
| SSE | Browser push, live updates | cargo run --release --features sse -- -m sse |
| WebSocket | Real-time bidirectional | cargo run --release --features websocket -- -m websocket |
| HTTP Streaming | Large file transfers | cargo run --release --features http-stream -- -m http-stream |
| gRPC | Microservices | cargo run --release --features grpc -- -m grpc |
Tools
| Tool | Description |
|---|---|
ping | Health check |
echo | Message validation |
info | Server metadata |
calculate | Math operations |
evaluate | Expression evaluation |
process_with_progress | Data processing with progress |
batch_process | Batch operations |
transform_data | Array transformations |
simulate_upload | File upload simulation |
health_check | System health status |
long_task | Long operation simulation |
db | PostgreSQL via PostgREST (feature: postgres) |
PostgreSQL Database Tool (via PostgREST)
The db tool provides full CRUD operations on PostgreSQL through a PostgREST proxy. Requires the postgres feature flag and a running PostgREST instance.
Actions: query, insert, update, delete, upsert, rpc, list_tables, describe
Quick Start
# Start PostgreSQL + PostgREST
docker compose -f docker-compose.postgrest.yml up -d
# Seed the database
docker compose -f docker-compose.postgrest.yml exec -T postgres \
psql -U postgres -d myapp < scripts/postgrest-setup.sql
# Build and run
POSTGREST_URL=http://localhost:3000 cargo run --features postgres -- --mode stdio
Environment Variables
| Variable | Default | Description |
|---|---|---|
POSTGREST_URL | http://localhost:3000 | PostgREST base URL |
POSTGREST_ANON_KEY | (none) | Bearer token for anonymous access |
POSTGREST_TIMEOUT | 30 | Request timeout in seconds |
DB_ALLOWED_TABLES | (none) | Comma-separated whitelist |
DB_TABLE_PREFIX | (none) | Only allow tables with this prefix |
Example Tool Calls
// Query with filters
{ "action": "query", "table": "users", "filters": { "is_active": { "eq": true } }, "order": [{ "column": "created_at", "ascending": false }], "limit": 10 }
// Insert
{ "action": "insert", "table": "users", "data": { "name": "Alice", "email": "alice@example.com" } }
// Update (filters required)
{ "action": "update", "table": "users", "filters": { "id": { "eq": 42 } }, "data": { "name": "Bob" } }
// Delete (filters required)
{ "action": "delete", "table": "users", "filters": { "id": { "eq": 42 } } }
// Upsert
{ "action": "upsert", "table": "users", "data": { "id": 42, "name": "Bob" }, "conflict": "id" }
// RPC (call a PostgreSQL function)
{ "action": "rpc", "function_name": "calculate_total", "params": { "order_id": 123 } }
// List tables / Describe schema
{ "action": "list_tables" }
{ "action": "describe", "table": "users" }
Supports 14 Supabase-compatible filter operators: eq, neq, gt, gte, lt, lte, like, ilike, is, in, not, contains, containedBy, overlaps.
OAuth 2.1 & Security
# OAuth endpoints
GET /.well-known/oauth-authorization-server
GET /.well-known/openid-configuration
GET /.well-known/oauth-protected-resource
POST /oauth/authorize
POST /oauth/token
POST /oauth/register
POST /oauth/introspect
POST /oauth/revoke
Client SDKs
Auto-generate type-safe client libraries:
cd sdk-generators
cargo run --release
# Generates:
# - TypeScript: output/typescript/mcp-client.ts
# - Python: output/python/mcp_client.py
# - Go: output/go/mcpclient/client.go
# - Rust: output/rust/mcp_client.rs
Build Options
| Feature | Command | Size |
|---|---|---|
| Minimal (Stdio) | cargo build --release | ~2.4 MB |
| HTTP + Auth | cargo build --release --features "http,auth" | ~3.0 MB |
| Web (SSE/WS) | cargo build --release --features "sse,websocket" | ~3.3 MB |
| PostgreSQL DB | cargo build --release --features postgres | ~2.5 MB |
| gRPC | cargo build --release --features grpc | ~3.9 MB |
| Full | cargo build --release --features full | ~4.2 MB |
Testing
# Run all tests (208 passing)
cargo test --features "http,auth"
# Run specific module tests
cargo test --features "http,auth" elicitation::tests
cargo test --features "http,auth" sampling::tests
cargo test --features "http,auth" structured_content::tests
cargo test --features "http,auth" integration_tests
# PostgreSQL db tool tests (56 unit tests)
cargo test --features postgres -- db::
# PostgREST integration tests (requires docker)
./scripts/test-db-integration.sh # 23 tests
./scripts/test-db-mcp-smoke.sh # 34 MCP stdio e2e tests
Documentation
| Document | Description |
|---|---|
| docs/README.md | Documentation index |
| docs/features/ELICITATION.md | User input collection |
| docs/features/SAMPLING.md | LLM sampling with tools |
| docs/features/STRUCTURED_CONTENT.md | Output validation |
| docs/features/TASKS.md | Task management |
| docs/features/OAUTH.md | OAuth 2.1 |
| CHANGELOG.md | Version history |
| NEXT_SESSION.md | Implementation status |
Project Statistics
| Metric | Value |
|---|---|
| MCP Spec Version | 2025-11-25 |
| Transport Modes | 6 |
| Production Tools | 12 (11 built-in + 1 db via PostgREST) |
| Client SDKs | 4 |
| Tests | 208 passing (151 unit + 23 integration + 34 smoke) |
| Code | ~20,000 lines |
| Binary Size | 2.4MB - 4.2MB |
Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Server v0.6.3 β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β ProtocolHandler β
β βββ TaskManager β
β βββ ToolMetadataRegistry β
β βββ ElicitationManager β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Core Modules β
β βββ tasks.rs - Long-running task management β
β βββ elicitation.rs - User input collection β
β βββ sampling.rs - LLM completion with tools β
β βββ structured_content.rs - Output validation β
β βββ db.rs - PostgreSQL via PostgREST [postgres] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Transport Layer β
β βββ stdio (default) β
β βββ HTTP/SSE (optional) β
β βββ WebSocket (optional) β
β βββ gRPC (optional) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Security β
β βββ OAuth 2.1 (RFC 8414, RFC 9728) β
β βββ JWT Authentication β
β βββ Well-known metadata endpoints β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
License
MIT License - see LICENSE file.
Support
- GitHub: https://github.com/netadx/mcp-boilerplate-rust
- MCP Spec: https://modelcontextprotocol.io/specification/2025-11-25
- Website: https://netadx.ai
Version: 0.6.3
Status: Production Ready
MCP Spec: 2025-11-25
Maintained by: NetADX Team
