Expand description
A batteries-included base for Model Context Protocol servers served over Streamable HTTP.
You write the tools, as an rmcp ServerHandler. This crate puts them on the network the way
hosted MCP clients such as claude.ai expect:
- OAuth 2.1 sign-in with dynamic client registration, PKCE (S256), resource indicators (RFC 8707) and protected-resource metadata (RFC 9728). It is stateless: every token is a signed JWT, so nothing needs storing and restarts sign nobody out.
- Two ways for people to sign in, chosen with
app::SignIn: the owner’s password (one person, with the server’s own upstream access) or each person’s own credential for the upstream service, such as an API key, which is checked upstream, sealed into their tokens and handed to your tools. You can also supply your own check. - Several services on one server, each at
/<name>and its own OAuth protected resource, plus every service’s tools together at/mcp. - Hardening for servers shared by many people: sign-in limits per address, per network and overall, capped and shared upstream credential checks, MCP sessions bound to each person’s credential, host and origin checks, body limits and constant-time comparisons.
- Read-only mode and a write audit log for every service, driven by each tool’s
read_only_hintannotation. - TLS from certificate files (hot reloaded) or a self-signed certificate, or plain HTTP behind a proxy, a container healthcheck, graceful shutdown, JSON logs, Prometheus metrics and OpenTelemetry traces.
- Configuration from environment variables, with
<NAME>_FILEvariants for secrets and every error reported at once.
§Quick start
A service is a name and an MCP handler. The app::Server builder does the rest:
use mcp_server_core::app::{Server, SignIn};
use mcp_server_core::combined::DynHandler;
use mcp_server_core::rmcp::ServerHandler;
use mcp_server_core::service::{Service, ServiceEnv};
use std::sync::Arc;
// Your MCP server: in practice a `#[tool_router]` with your tools.
#[derive(Clone)]
struct Hello;
impl ServerHandler for Hello {}
struct HelloService;
impl Service for HelloService {
fn name(&self) -> &'static str {
"hello"
}
fn handler(&self) -> DynHandler {
DynHandler::new(Hello)
}
}
fn hello(_env: &mut ServiceEnv) -> Option<Arc<dyn Service>> {
Some(Arc::new(HelloService))
}
#[tokio::main]
async fn main() -> std::process::ExitCode {
Server::new("mcp-hello", env!("CARGO_PKG_VERSION"))
.env_prefix("HELLO")
.service("hello", hello)
.sign_in(SignIn::OwnerPassword)
.main()
.await
}Run it with PUBLIC_URL, OAUTH_SIGNING_KEY and OAUTH_ADMIN_PASSWORD set and the service is
at https://<host>/hello. See the repository’s examples/ for a complete tool server and for
signing people in with their own API keys.
§Lower-level pieces
app::Server is a thin layer over the modules below; use them directly when you need a
different shape: server::build_app mounts services behind the OAuth routes,
service::mcp_service wraps any rmcp handler in the hardened Streamable HTTP transport and
tls::serve serves the result.
§Feature flags
otel(default): export traces over OTLP/HTTP whenOTEL_EXPORTER_OTLP_ENDPOINTis set.prometheus(default): serve Prometheus metrics onMETRICS_ADDR.
Re-exports§
Modules§
- app
Server: a whole MCP server binary from a list of services.- caller
- Who made a request. The bearer guard adds a
Callerto every request it lets through. - combined
- Several services’ MCP handlers served as one MCP server: the combined
/mcpendpoint. - config
- Configuration from environment variables.
- credential
- Who may sign in, and the credentials people bring with them.
- guards
- Abuse limits: failed sign-in attempts per address, per wider block and overall, and one-time codes.
- jwt
- The server’s own tokens: HS256 JWTs signed with
OAUTH_SIGNING_KEY. - oauth
- The OAuth 2.1 authorization server and the bearer guard in front of every service.
- observability
- Logs, metrics and traces.
- pkce
- PKCE (RFC 7636) and constant-time comparison.
- policy
- Read-only services and the write audit log, applied once around every service’s MCP handler.
- prompt
- Helpers for services’ MCP prompts: the tool-name prefix a prompt’s text should use, argument parsing and the shape of a rendered prompt.
- server
- The HTTP application: health, the OAuth routes and every service behind its bearer guard.
- service
- Services: the MCP servers this crate hosts, each mounted at
/<name>. - tls
- Serving HTTP or HTTPS, and the container healthcheck.
- upstream
- Signing in through the upstream service’s own OAuth: the person approves access at the provider (FreeAgent, GitHub, Google and the like) instead of pasting a key, and the credential the provider grants is sealed into their tokens like any other carried credential.
Functions§
- install_
crypto_ provider - Installs rustls’
ringcrypto provider as the process default. Call it once before serving TLS or making TLS requests; later calls do nothing.app::Server::maincalls it for you. - shutdown_
signal - A token cancelled on Ctrl-C, or on SIGTERM on Unix, for graceful shutdown. Must be called inside a Tokio runtime.