sebetc4/rust_mcp_server_template

MCP Server Template

A scalable Rust MCP (Model Context Protocol) server template built with rmcp.

Features

• Domain-Driven Architecture: Organized by functional domains (tools, resources, prompts)
• Multiple Transports: STDIO (standard MCP), TCP, and HTTP support
• Decoupled Design: Tools are self-contained with no server context dependencies
• Type-Safe: Compile-time checks with custom error types (thiserror)
• Async Runtime: Built on Tokio for high-performance async I/O
• Feature Flags: Build only what you need (stdio, tcp, http)

Quick Start

# Build and run (STDIO mode - default)
cargo build --release
cargo run

# Run with HTTP transport
MCP_TRANSPORT=http MCP_HTTP_PORT=9090 cargo run --features http

# Run all tests
cargo test --features all

Documentation

Detailed documentation is available in the folder:

• - System architecture and design principles
• - Step-by-step guide for adding tools, resources, prompts
• - Feature flags and transport configuration

Project Structure

src/
├── lib.rs                    # Library crate root
├── main.rs                   # Application entry point
├── core/                     # Core server components
│   ├── config.rs            # Server configuration
│   ├── error.rs             # Unified error types
│   ├── server.rs            # MCP ServerHandler implementation
│   └── transport/           # Transport implementations
│       ├── stdio.rs         # STDIO transport (standard MCP)
│       ├── tcp.rs           # TCP transport (JSON-RPC)
│       └── http.rs          # HTTP transport (JSON-RPC over HTTP)
└── domains/                  # Domain-specific modules
    ├── tools/               # Tools domain
    │   ├── definitions/     # Tool implementations (one file per tool)
    │   │   ├── echo.rs      # Echo tool
    │   │   └── add.rs       # Add tool
    │   ├── router.rs        # STDIO/TCP ToolRouter builder
    │   └── registry.rs      # HTTP dispatch + tool metadata
    ├── resources/           # Resources domain
    │   ├── definitions/     # Resource implementations
    │   └── registry.rs      # Resource registration
    └── prompts/             # Prompts domain
        ├── definitions/     # Prompt implementations
        └── registry.rs      # Prompt registration

Available Components

Tools

Resources

Prompts

Transport Modes

STDIO (Default)

Standard MCP transport for Claude Desktop and other MCP clients.

cargo run

TCP

JSON-RPC over raw TCP for development and debugging.

MCP_TRANSPORT=tcp MCP_TCP_PORT=4000 cargo run --features tcp

HTTP

JSON-RPC over HTTP with REST-like endpoints.

MCP_TRANSPORT=http MCP_HTTP_PORT=9090 cargo run --features http

Adding New Components

Adding a Tool

1. Create src/domains/tools/definitions/my_tool.rs with:

   • execute() - core logic
   • http_handler() - HTTP transport
   • to_tool() - metadata
   • create_route() - STDIO/TCP route

2. Export in definitions/mod.rs

3. Register in registry.rs (4 places)

4. Register in router.rs

See for complete examples.

Configuration

Environment Variables

# Transport selection
MCP_TRANSPORT=stdio|tcp|http

# TCP configuration
MCP_TCP_PORT=3000
MCP_TCP_HOST=127.0.0.1

# HTTP configuration
MCP_HTTP_PORT=8080
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PATH=/mcp

# Server identification
MCP_SERVER_NAME="My MCP Server"

# Logging
RUST_LOG=debug

Testing

# Run all tests
cargo test --features all

# Test HTTP transport
MCP_TRANSPORT=http MCP_HTTP_PORT=9090 cargo run --features http &
python3 scripts/test_http_client.py

# Test TCP transport
MCP_TRANSPORT=tcp MCP_TCP_PORT=4000 cargo run --features tcp &
python3 scripts/test_tcp_client.py 4000

Integration with MCP Clients

{
  "mcpServers": {
    "template": {
      "command": "path/to/mcp_server",
      "args": []
    }
  }
}

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.