Adding `rust_mcp_core` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add rust-mcp-core

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

rust-mcp-core = "0.1.0"

The rust_mcp_core library will be automatically available globally.

Back to the crate overview.

Readme

rust-mcp-core

A config-driven MCP server core built on the official Rust SDK (rmcp). Define tools, auth, prompts, resources, and HTTP behavior in YAML or JSON configuration -- the library handles execution, validation, and protocol compliance with minimal Rust code.

Fully implements the Model Context Protocol specification (2025-11-25).

Tested AI CLI compatibility

This library has been tested and verified with:

Claude Code
Codex CLI
Gemini CLI

What this is for

Reduced boilerplate. Stand up a spec-compliant MCP server by writing configuration instead of protocol plumbing. A working server with HTTP tools needs only a YAML file and a few lines of Rust.
Built-in HTTP API tooling. Define outbound HTTP tool calls entirely in config with URL templating, header injection, query parameters, and structured response mapping.
Authentication out of the box. Supports inbound bearer token, JWT/JWKS validation, and OAuth token introspection with scope enforcement and WWW-Authenticate challenges. Also supports outbound upstream auth for HTTP tools (none, bearer, basic, oauth2) including OAuth2 client-credentials/refresh-token grants with optional mTLS at the token endpoint.
Extensible plugin system. When config-driven behavior is not enough, register plugins for custom tool logic, auth validation, prompt/resource providers, completion providers, and HTTP router extensions.
Both transports. Works with stdio and streamable HTTP transports.
Works with the official SDK. This library builds on rmcp and uses its transport runtime, ServerHandler trait, and MCP type definitions directly -- no reimplementation.

What this is not

Not a toolbox. This library does not include built-in tools like file servers, database connectors, or shell executors. The only built-in execution type is outbound HTTP calls. Any other tool behavior must be provided through a tool plugin.

How this complements the rmcp SDK

The rmcp SDK provides low-level MCP protocol primitives: transport, message framing, the ServerHandler trait, and type definitions. rust-mcp-core builds on top of that to provide a config-driven server framework.

What the SDK provides (used directly, not reimplemented):

Transport runtime (stdio + streamable HTTP)
ServerHandler trait and JSON-RPC dispatch
All MCP model types (Tool, Prompt, Resource, Task, etc.)
Default handler implementations (e.g., ping)

What rust-mcp-core adds:

Config loading with ${env:ENV} expansion and JSON schema validation
Tool execution engine (HTTP tools with templating + plugin tools)
Output schema validation and structured content rendering
Plugin registries (tool, auth, prompt, resource, completion, HTTP router)
Config-driven prompts, resources, and completion providers
Auth middleware (bearer, JWT/JWKS, introspection, scope enforcement)
Task store with peer isolation, TTL, cooperative cancellation, and status notifications

The complementary relationship is clearest with auth. The SDK provides client-side OAuth (PKCE flows, token acquisition, credential storage, automatic refresh). rust-mcp-core provides server-side auth (token validation, scope enforcement, WWW-Authenticate challenges, and the protected resource metadata endpoint). An rmcp client obtains a token and sends it; a rust-mcp-core server receives and validates it.

MCP specification compliance

This library implements the following capabilities from the MCP 2025-11-25 specification:

Server capabilities

Capability	Description
Tools	Config-driven and plugin-driven tool definitions. Supports input/output schema validation, list-changed notifications, and pagination.
Prompts	Inline (config-driven) and plugin-driven prompt providers with argument validation, template rendering, and list-changed notifications.
Resources	Inline and plugin-driven resource providers with subscribe/unsubscribe support and list-changed notifications.
Completion	Autocompletion for prompt and resource template arguments from inline value lists or plugin sources.
Logging	Structured log messages via `notifications/message` with syslog severity levels. Clients control notification threshold via `logging/setLevel`.
Progress	Long-running operation tracking via `notifications/progress` with rate limiting and monotonic progress enforcement.
Cancellation	In-progress request termination. Cancellable tools are aborted automatically; non-cancellable tools receive a fresh token and run to completion.
Tasks	Experimental task utility for long-running operations. Supports task-augmented tool calls, polling, deferred result retrieval, cooperative cancellation, TTL, peer isolation, and status notifications.
Pagination	Cursor-based pagination for `tools/list` and other list operations.

Server-initiated client features

These require a registered plugin to invoke. The framework handles config validation and client capability negotiation; plugin code calls helpers via params.ctx (params: PluginCallParams).

Feature	Description
Sampling	Request LLM text/image/audio generation from the client, optionally with tool use.
Roots	Query the client for filesystem root boundaries.
Elicitation	Request structured user input (form mode) or trigger out-of-band interactions like OAuth flows (URL mode).

Protocol fundamentals

Capability negotiation during initialize handshake
Ping/pong for connection health
Feature-gate enforcement: disabled features return method-not-found and are omitted from capability advertisement

Compile-time features

All features are enabled by default. Disable with default-features = false and enable selectively.

Feature	Description	Implies
`streamable_http`	HTTP transport (`server.transport.mode=streamable_http`) and HTTP router plugin surface	--
`http_hardening`	Streamable HTTP hardening middleware (`max_request_bytes`, inbound rate limits, session abuse controls, panic/sensitive-header guards)	`streamable_http`
`auth`	Auth middleware: bearer, JWT/JWKS, OAuth introspection, scope enforcement	`streamable_http`
`http_tools`	Built-in outbound HTTP tool execution (`tools.items[].execute.type=http`) plus upstream auth (`none`, `bearer`, `basic`, `oauth2`)	--
`prompts`	`prompts/list` + `prompts/get` capability	--
`resources`	`resources/list`, `resources/read`, `resources/templates/list`, subscribe/unsubscribe	--
`completion`	`completion/complete` for prompt/resource argument autocompletion	--
`client_logging`	`logging/setLevel` + `notifications/message`	--
`progress_utility`	`notifications/progress` via `params.ctx.notify_progress(...)`	--
`tasks_utility`	Experimental: task-augmented `tools/call`, `tasks/get`, `tasks/list`, `tasks/cancel`	--
`client_features`	Server-initiated client helpers via `params.ctx`: `request_roots()`, `request_sampling()`, `request_elicitation()`	--

Minimal build (stdio + plugin tools only):

cargo build --no-default-features

If config references a disabled feature, startup fails with a clear error message.

Installation

From crates.io:

[dependencies]
rust-mcp-core = "0.1"

From GitHub:

[dependencies]
rust-mcp-core = { git = "https://github.com/nullablevariant/rust-mcp-core" }

Quick start

Configuration

Create a YAML config file. This example defines one HTTP tool and one inline prompt over streamable HTTP transport. Stdio transport is also supported by setting transport.mode: stdio. If you want a full copy/paste starter with every supported field, use mcp_config.template.yml.

version: 1
server:
  host: 0.0.0.0
  port: 3000
  endpoint_path: /mcp
  logging:
    level: info
  transport:
    mode: streamable_http  # also supports: stdio
  auth:
    enabled: false

client_logging:
  level: info

upstreams:
  api:
    base_url: ${env:API_BASE_URL}

tools:
  items:
    - name: api.list_items
      description: List items from the API
      input_schema:
        type: object
        properties:
          query:
            type: string
      execute:
        type: http
        upstream: api
        method: GET
        path: /items
        query:
          q: "${query}"
      response:
        type: structured
        template:
          items: "${$.items}"
        fallback: text

Usage

use std::path::PathBuf;
use rust_mcp_core::{load_mcp_config_from_path, runtime, PluginRegistry};
use rust_mcp_core::McpError;

#[tokio::main]
async fn main() -> Result<(), McpError> {
    let config = load_mcp_config_from_path(PathBuf::from("config/mcp_config.yml"))?;
    let plugins = PluginRegistry::new();
    runtime::run_from_config(config, plugins).await
}

With a custom tool plugin:

use rust_mcp_core::{load_mcp_config_from_path, runtime, McpError, PluginRegistry};

#[tokio::main]
async fn main() -> Result<(), McpError> {
    let config = load_mcp_config_from_path("config/mcp_config.yml".into())?;
    let plugins = PluginRegistry::new()
        .register_tool(MyToolPlugin)?;
    runtime::run_from_config(config, plugins).await
}

Any plugin referenced by config (for example via tools.items[].execute.plugin or provider plugin fields) must be both declared in config plugins[] and registered in PluginRegistry. Extra registered plugins that are not declared are ignored with a warning. See Plugin Guide for the full plugin contract.

Config reload (consumer-managed)

runtime::run_from_config(...) is a convenience entrypoint and does not expose reload control.

If you need config reload:

use runtime::build_runtime(...),
keep the returned runtime handle,
load updated config input yourself,
call runtime.reload_config(new_config).await.

rust-mcp-core does not automatically watch config files or trigger reloads.

use std::path::PathBuf;
use rust_mcp_core::{load_mcp_config_from_path, runtime, McpError, PluginRegistry};

#[tokio::main]
async fn main() -> Result<(), McpError> {
    let initial = load_mcp_config_from_path(PathBuf::from("config/mcp_config.yml"))?;
    let runtime = runtime::build_runtime(initial, PluginRegistry::new()).await?;

    // Consumer-owned trigger (file watcher, signal, admin endpoint, etc.)
    let updated = load_mcp_config_from_path(PathBuf::from("config/mcp_config.reload.yml"))?;
    runtime.reload_config(updated).await?;

    runtime.run().await
}

Upstream auth for HTTP tools

upstreams.<name>.auth controls outbound auth for tools.items[].execute.type=http:

type: none -> no auth header injected.
type: bearer -> injects Authorization: Bearer <token>.
type: basic -> injects HTTP Basic auth.
type: oauth2 -> acquires/caches access tokens via client_credentials or refresh_token grant, injects bearer token, and can retry once on 401 after forced refresh.

Token-endpoint secrets support inline, env, and path sources. Optional token-endpoint mTLS is configured via auth.mtls (client_cert, client_key, optional ca_cert). See Auth and Config Schema for full field-level details.

Streamable HTTP request flow (manual clients)

When server.transport.mode=streamable_http, manual clients (for example curl) should follow this flow:

Send initialize first, capture MCP-Session-Id from response headers when sessions are enabled.
Send notifications/initialized on the same endpoint with the same session header.
Include Accept: application/json, text/event-stream on POST requests.
If a client sends MCP-Protocol-Version on HTTP requests:
- default server.transport.streamable_http.protocol_version_negotiation.mode: strict keeps the header; unsupported values return HTTP 400.
- mode: negotiate keeps known RMCP versions and drops unknown versions before rmcp validation.
Reuse the MCP-Session-Id header on subsequent requests in session modes that require it.
Expect streamable HTTP responses to be SSE-framed.

Why this exists:

rust-mcp-core is coupled to RMCP's known protocol version set.
Some AI clients send a newer date-stamped MCP-Protocol-Version header than the bundled RMCP supports.
In strict mode this fails fast with 400 (explicit mismatch).
In negotiate mode unknown header values are removed so requests can continue without forcing a reverse proxy/header rewrite layer.
This is a compatibility layer for HTTP headers only; MCP capability/version negotiation still happens in normal initialize flow.

For client-specific interoperability constraints (for example schema subset limits, structuredContent shape expectations, protocol-header normalization, and Accept requirements), see AI Client Compatibility.

Streamable HTTP hardening (`http_hardening`)

With http_hardening enabled, core can enforce:

inbound request body cap (max_request_bytes, HTTP 413 on exceed),
general inbound rate limiting (rate_limit, HTTP 429 on exceed),
session abuse controls (max_sessions, idle_ttl_secs, max_lifetime_secs, creation_rate),
panic-to-500 and sensitive-header transport guards.

See Transport and Config Schema for field-level behavior and validation rules.

Plugin logging helper

Tool plugins can emit server logs and/or MCP client notifications:

let ctx = params.ctx;
ctx.log_event(rust_mcp_core::LogEventParams {
    level: rust_mcp_core::mcp::LoggingLevel::Info,
    message: "synced records".to_owned(),
    data: Some(serde_json::json!({"count": 42})),
    channels: &[rust_mcp_core::LogChannel::Server, rust_mcp_core::LogChannel::Client],
}).await?;

LogChannel::Server writes to the server's tracing output (controlled by server.logging.level).
LogChannel::Client sends an MCP notifications/message to the client (controlled by client_logging.level and logging/setLevel).
logging/setLevel does not change server tracing verbosity. It only updates client notification filtering.
On config reload, server.logging.level updates are applied when rust-mcp-core owns the global tracing subscriber. If a host app already set the global subscriber, rust-mcp-core logs a warning and cannot override it.

Plugin outbound OAuth2 helper (`http_tools`)

When http_tools is enabled and an upstream uses auth.type: oauth2, plugins can reuse native token acquisition via PluginContext:

let token = params.ctx.upstream_access_token("partner_api", false).await?;
let (name, value) = params
    .ctx
    .upstream_bearer_header("partner_api", false)
    .await?;

upstream_bearer_header returns ("Authorization", "Bearer <token>"). force_refresh=true forces one refresh attempt through the same outbound OAuth2 token manager used by HTTP tools.

For outbound requests to configured upstreams, plugins can use the built-in helper path:

let response = params.ctx.send(
    "partner_api",
    rust_mcp_core::OutboundHttpRequest {
        method: "GET".to_owned(),
        url: "/partners".to_owned(),
        ..rust_mcp_core::OutboundHttpRequest::default()
    },
).await?;

This path applies the same outbound default-resolution behavior as built-in HTTP tools. Use send_with(...) for per-call auth overrides and send_raw(...) when you intentionally want to bypass upstream/default/retry policy. send_with(...) supports PluginSendAuthMode::{Inherit, None, Explicit}.

See examples/plugins-tool-oauth-helper/README.md for a complete runnable flow.

Documentation

Document	Description
Plugin Guide	Plugin trait signatures/imports, `PluginContext` behavior (including `request_list_refresh`), and MCP model cheat sheet
Auth	Auth modes, token validation, OAuth metadata, TLS deployment
Tasks	Task utility behavior, `task_support` modes, SDK comparison
Transport	Streamable HTTP options, session modes, protocol negotiation, and hardening controls
Config Schema	Full field reference, defaults, validation rules, env expansion
Config Reload	Consumer-managed reload flow, trigger patterns, and failure semantics
AI Client Compatibility	Practical MCP client constraints and compatibility patterns
Troubleshooting	Common runtime/client errors and concrete fixes

Examples

Runnable examples live under examples/ with per-example configs in examples/<name>/config/mcp_config.yml.

Browse all examples: examples/README.md
Minimal core: examples/core-minimal/README.md
Auth flows: auth-bearer, auth-oauth-jwt, auth-oauth-introspection, auth-all-mode
HTTP tools: tools-web-search, tools-crud-http, tools-http-post, tools-templating, tools-output-modes, tools-upstream-auth, tools-rich-content
Plugin wiring: plugins-tool-custom, plugins-tool-filesystem, plugins-auth-custom, plugins-router-http, plugins-simple-outbound-http
Prompts/resources/tasks/client features: prompts-inline-plugin, resources-inline-plugin, resources-subscribe-updated, utility-tasks, utility-tasks-advanced, plugins-tool-client-features, plugins-tool-client-features-advanced
Utility behavior: utility-logging, utility-progress, utility-cancellation, utility-completion, utility-pagination, utility-list-changed

Config schema

See the full schema and validation rules in CONFIG_SCHEMA.md.

Adding rust_mcp_core library as a dependency

Adding `rust_mcp_core` library as a dependency