Pmcp

PMCP - Pragmatic Model Context Protocol

Production-grade Rust implementation of the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) - 16x faster than TypeScript, built with Toyota Way quality principles

Overview

PMCP is a complete MCP ecosystem for Rust, providing everything you need to build, test, and deploy production-grade MCP servers — in Rust, or from configuration alone:

• 🧩 Config-Driven Servers - Build SQL & OpenAPI/HTTP MCP servers from a config.toml, or serve a governed Excel workbook from a compiled bundle — all no Rust required (pmcp-server-toolkit, pmcp-sql-server, pmcp-openapi-server, pmcp-workbook-server)
• 🤝 Agents & Teams - Build deploy-anywhere agents and small teams: the agent loop (pmcp-agent), four reference team servers (pmcp-team-servers), and a portable AI-Package format (pmcp-package) — driven from the cargo pmcp agent/team/package verbs
• 🦀 pmcp SDK - High-performance Rust crate with full MCP protocol support
• ⚡ cargo-pmcp - CLI toolkit for scaffolding, testing, and development
• 📚 pmcp-book - Comprehensive reference guide with 27 chapters
• 🎓 pmcp-course - Hands-on course with quizzes and exercises
• 🤖 AI Agents - Kiro and Claude Code configurations for AI-assisted development

Why PMCP?

• Performance: 16x faster than TypeScript SDK, 50x lower memory
• Safety: Rust's type system + zero unwrap() in production code
• Quality: Toyota Way principles - zero technical debt tolerance
• Complete: SDK, tooling, documentation, and AI assistance in one ecosystem

Quick Start

Choose your path based on experience and preference:

🧩 Path 1: Config-Only Servers — No Rust Required (SQL & OpenAPI)

New in v2.9 — this removes the biggest blocker to putting organizational data behind MCP: you no longer need a Rust programmer. Describe a production MCP server over a SQL database or any OpenAPI / HTTP backend in a config.toml — declare the backend, a handful of curated tools, and a Code Mode policy — and a prebuilt binary serves it. No Rust, no recompiling. Curated tools cover the common ~20%; Code Mode handles the long-tail ~80% by generating queries against your schema/spec under a static, default-deny policy. A business analyst curates the API slice in config; the toolkit does the rest.

SQL — SQLite / Postgres / MySQL / Athena (runnable from a checkout of this repo):

cargo install pmcp-sql-server

Seed a tiny demo DB, then serve it from config alone — two curated tools

(list_books, books_by_author) + Code Mode for the long tail.

sqlite3 /tmp/pmcp-sqlite-explorer.db < crates/pmcp-sql-server/examples/sqlite-explorer.sql pmcp-sql-server \ --config crates/pmcp-sql-server/examples/sqlite-explorer.toml \ --schema crates/pmcp-sql-server/examples/sqlite-explorer.sql

OpenAPI / HTTP — any REST backend, with six outgoing-auth models including OAuth passthrough (the server holds no standing credential and forwards the caller's own token, so it can only act as the signed-in user):

cargo install pmcp-openapi-server

Curated configs ship with the crate — e.g. a London Tube (api_key) showcase and

a Microsoft-Graph / Excel "Contoso" (oauth_passthrough) example. These talk to a

live backend, so supply any required credential per the example's comments.

#

base_url is a SLOT, not a baked literal, so the endpoint comes from the

environment too — the same package moves between environments unchanged.

TFL_BASE_URL=https://api.tfl.gov.uk TFL_APP_KEY= \ pmcp-openapi-server --config crates/pmcp-openapi-server/examples/london-tube.toml

Excel workbook — a governed spreadsheet, served as one MCP tool per output table (no config.toml, no schema; the single input is a compiled bundle@version directory). Author inputs and outputs as named Excel Tables and each output table becomes its own well-named, well-typed MCP tool with a DAG-derived input schema:

cargo install pmcp-workbook-server

Preview the exact tool surface an AI will see — BEFORE you compile or deploy:

cargo pmcp workbook explain pricing.xlsx # e.g. calculate_tax, estimate_refund

Compile a governed workbook to a deterministic bundle (ingest → lint → compile →

reconcile → fail-closed gate → write), then serve one calculation tool per output

table — plus explain / get_manifest / diff_version / render_workbook — from the bundle alone.

cargo pmcp workbook compile pricing.xlsx --workflow quote --approver alice pmcp-workbook-server --bundle-dir bundles/quote@1.0.0

Want to extend and deploy it? cargo pmcp new my-server --kind sql-server (or --kind openapi-server / --kind workbook-server) scaffolds the same config-driven server as a small crate, ready for cargo pmcp deploy to AWS Lambda / Google Cloud Run / Cloudflare / pmcp.run.

Learn more: the *Config-Driven SQL Servers*, *OpenAPI*, and *Config-Driven Workbook Servers* chapters in the pmcp-book · pmcp-sql-server · pmcp-openapi-server · pmcp-workbook-server · pmcp-server-toolkit

---

🚀 Path 2: AI-Assisted (Recommended for Rapid Prototyping)

Build production-ready MCP servers with AI assistance in minutes:

Prerequisites:

# Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup update

Install cargo-pmcp

cargo install cargo-pmcp

Install Claude Code AI Agent:

# Install the mcp-developer subagent (user-level - works across all projects)

curl -fsSL https://raw.githubusercontent.com/paiml/rust-mcp-sdk/main/ai-agents/claude-code/mcp-developer.md \ -o ~/.claude/agents/mcp-developer.md

Restart Claude Code

Build your server:

You: "Create a weather forecast MCP server with tools for getting current conditions and 5-day forecasts"

Claude Code: [Invokes mcp-developer subagent]

I'll create a production-ready weather MCP server using cargo-pmcp.

$ cargo pmcp new weather-mcp-workspace $ cd weather-mcp-workspace $ cargo pmcp add server weather --template minimal

[Implements type-safe tools with validation] [Adds comprehensive tests and observability] [Validates quality gates]

✅ Production-ready server complete with 85% test coverage!

What you get: Production-ready code following Toyota Way principles, with comprehensive tests, structured logging, metrics collection, and zero clippy warnings.

Learn more: AI-Assisted Development Course | AI Agents README

---

⚡ Path 3: cargo-pmcp Toolkit (Recommended for Manual Development)

Scaffold and build servers using the cargo-pmcp CLI:

Installation:

# Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup update

Install cargo-pmcp

cargo install cargo-pmcp

Create a server:

# Create workspace

cargo pmcp new my-mcp-workspace cd my-mcp-workspace

Add a server using a template

cargo pmcp add server myserver --template minimal

Start development server with hot-reload

cargo pmcp dev --server myserver

Generate and run tests

cargo pmcp test --server myserver --generate-scenarios cargo pmcp test --server myserver

Build for production

cargo build --release

Available templates (cargo pmcp add server --template ):

• minimal - Empty structure for custom servers
• calculator - Arithmetic operations (learning)
• complete_calculator - Full-featured reference implementation
• sqlite_explorer - Hand-coded Rust database browser (escape hatch)

Config-driven kinds (cargo pmcp new --kind — TOML-driven, no per-tool Rust):

• sql-server - SQL MCP server over SQLite / Postgres / MySQL / Athena from config.toml
• openapi-server - MCP server over any OpenAPI / HTTP backend from config.toml
• workbook-server - MCP server over a governed Excel workbook, served from a compiled bundle@version directory

Learn more: cargo-pmcp Guide

---

🦀 Path 4: pmcp SDK Directly (For Fine-Grained Control)

Use the pmcp crate directly for maximum control:

Installation:

[dependencies]

pmcp = "2.0" tokio = { version = "1", features = ["full"] } serde = { version = "1", features = ["derive"] } schemars = "0.8" # For type-safe tools

Type-safe server example:

use pmcp::{ServerBuilder, TypedTool, RequestHandlerExtra, Error};

use schemars::JsonSchema; use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize, JsonSchema)] #[schemars(deny_unknown_fields)] struct WeatherArgs { #[schemars(description = "City name")] city: String,

#[schemars(description = "Number of days (1-5)")] days: Option , }

#[derive(Debug, Serialize, JsonSchema)] struct WeatherOutput { temperature: f64, conditions: String, }

async fn get_weather(args: WeatherArgs, _extra: RequestHandlerExtra) -> pmcp::Result { // Validate if args.city.is_empty() { return Err(Error::validation("City cannot be empty")); }

let days = args.days.unwrap_or(1); if !(1..=5).contains(&days) { return Err(Error::validation("Days must be 1-5")); }

// Call weather API... Ok(WeatherOutput { temperature: 72.0, conditions: "Sunny".to_string(), }) }

#[tokio::main] async fn main() -> pmcp::Result<()> { let server = ServerBuilder::new() .name("weather-server") .version("1.0.0") .tool("get-weather", TypedTool::new("get-weather", |args, extra| { Box::pin(get_weather(args, extra)) }).with_description("Get weather forecast for a city")) .build()?;

server.run_stdio().await?; Ok(()) }

Learn more: pmcp-book | pmcp-course | API Documentation

---

PMCP Ecosystem Components

🦀 pmcp SDK (The Crate)

High-performance Rust implementation of the MCP protocol.

Key Features:

• Type-Safe Tools: Automatic JSON schema generation from Rust types
• Multiple Transports: stdio, HTTP/SSE, WebSocket, WASM
• OAuth Support: Full auth context pass-through
• Workflows: Multi-step orchestration with array indexing