Skip to main content

Crate mcp_server_core

Crate mcp_server_core 

Source
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_hint annotation.
  • 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>_FILE variants 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 when OTEL_EXPORTER_OTLP_ENDPOINT is set.
  • prometheus (default): serve Prometheus metrics on METRICS_ADDR.

Re-exports§

pub use axum;
pub use rmcp;

Modules§

app
Server: a whole MCP server binary from a list of services.
caller
Who made a request. The bearer guard adds a Caller to every request it lets through.
combined
Several services’ MCP handlers served as one MCP server: the combined /mcp endpoint.
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’ ring crypto provider as the process default. Call it once before serving TLS or making TLS requests; later calls do nothing. app::Server::main calls 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.