feat: add experimental Rust MCP runtime and session core

[crivetimihai]

🔗 Related Issue

N/A

---

📝 Summary

This PR adds an experimental Rust MCP runtime and incrementally moves the MCP transport, high-volume JSON-RPC routing, and the first session/event-store slices into Rust while keeping the Python implementation available behind feature flags.

Key changes:

• add tools_rust/mcp_runtime and integrate it into Containerfile.lite, docker-compose.yml, and the managed entrypoint flow
• route public /mcp traffic through Rust with explicit runtime visibility in /health, /ready, startup logs, and MCP response headers
• narrow initialize, notifications/initialized, tools/list, tools/call, resources/*, prompts/*, and several other MCP methods off the generic Python dispatcher
• wire the official modelcontextprotocol/rust-sdk behind a feature flag for the upstream tools/call client path
• add feature-flagged Rust session metadata and Redis-backed event-store/session sharing, including dedicated session cleanup for server-scoped DELETE
• extend the load-test harness and document the runtime boundary, configuration, and migration status in tools_rust/mcp_runtime/README.md and tools_rust/mcp_runtime/STATUS.md

This remains intentionally reversible:

• full Python fallback: EXPERIMENTAL_RUST_MCP_RUNTIME_ENABLED=false
• Rust transport/runtime only: disable EXPERIMENTAL_RUST_MCP_SESSION_CORE_ENABLED and EXPERIMENTAL_RUST_MCP_EVENT_STORE_ENABLED

---

🏷️ Type of Change

• Bug fix
• Feature / Enhancement
• Documentation
• Refactor
• Chore (deps, CI, tooling)
• Other (describe below)

---

🧪 Verification

Check	Command	Status
Rust runtime crate tests	cargo test --release --manifest-path tools_rust/mcp_runtime/Cargo.toml	✅
MCP CLI parity	make test-mcp-cli	✅
MCP RBAC parity	make test-mcp-rbac	✅
Redis stream integration	uv run pytest -q --with-integration tests/integration/test_streamable_http_redis.py	✅
Compose-built Rust image	docker compose build gateway with Rust enabled	✅
Load benchmarks	Mixed MCP and tools-only Locust runs on the compose-built stack	✅

Performance highlights on the compose-built Rust stack:

• mixed MCP workload: 1007.35 RPS at 120 users, 1033.01 RPS at 150 users, 0% failures
• tools-only hot path: 1126.96 RPS overall and 1068.5 RPS on MCP tools/call [rapid] at 125 users, 0% failures

---

✅ Checklist

• Code formatted (make black isort pre-commit)
• Tests added/updated for changes
• Documentation updated (if applicable)
• No secrets or credentials committed

---

📓 Notes

Current boundary:

• public MCP transport now flows through Rust
• Python still remains the control plane for auth/RBAC and some session/transport internals
• the runtime is intentionally feature-flagged so deployments can fall back to the Python path at any time

Follow-on work after this PR is the remaining transport/session ownership: replay/resume behavior, session existence/owner checks on the public path, and multi-worker session-affinity forwarding.

[lucarlig]

Interesting PR, i love the general idea of rust components being fully independent. However I have been working on the a2a_service in #3250, and one of the main challenges in fully replacing the Python service in this case is how the database layer is handled. The current Python implementation already contains assumptions around schema management, migrations, connection handling, and ORM/query behavior. Re-implementing or partially replacing that logic can easily introduce inconsistencies (e.g., differences in transaction handling, migration state, connection pooling, or query semantics), which makes the database layer particularly tricky to replicate safely.

Using a Python fallback may not provide the same feature set, safety guarantees, or performance characteristics. It could also behave differently under load, which makes this approach quite risky for production use.

if this PR were merged and then integrated with the changes introduced in #3161, it would benefit from an existing and more robust CI setup. For that reason, I would recommend working toward merging #3161 first and placing this implementation within the crates folder so it can leverage that infrastructure.

[lucarlig]

I’m a bit concerned about the long-term architecture here. The Rust runtime is no longer just a transport edge; it now depends on an implicit contract with the Python backend across internal headers, internal endpoints, duplicated auth/session semantics, and direct DB knowledge. That works for a staged migration, but it also means changes to Python routing, token-scope behavior, or payload/header shapes can silently break Rust unless both sides evolve in lockstep.

The DB path has a similar issue. Right now migrations and schema ownership still live in the Python ORM/Alembic layer, while Rust is starting to read the same schema directly and reimplement some of the filtering/visibility logic itself. That creates two sources of truth for data access semantics. Every schema change or business-rule change now has to be maintained in both languages, which is going to get harder over time.

I think it would be healthier to converge on one shared boundary instead of growing both layers independently: either keep Python as the single DB/business-logic layer and expose a narrower internal API to Rust, or move the DB/data layer into Rust and have Python consume that same layer as well. The second option is more work, but it avoids permanent duplication and gives us a cleaner path to Rust-side performance gains.

[sco3]

I tried to use cloudflare pingora crate as mcp proxy to fast-time-server:
After some optimizations:

Starting benchmark: Direct (8111) (10 clients × 10000 requests = 100000 total)

Direct (8111) Results:
   Total: 100000 requests (100000 success, 0 failed)
   Elapsed: 2.13s
   Avg latency: 0.21ms
   Throughput: 47020.85 req/s

Starting benchmark: Gateway (3000) (10 clients × 10000 requests = 100000 total)

Gateway (3000) Results:
   Total: 100000 requests (100000 success, 0 failed)
   Elapsed: 4.22s
   Avg latency: 0.42ms
   Throughput: 23701.87 req/s

[gcgoncalves]

Tested the functionalities with both the rust mode disabled and with full rust mode, both worked well for all basic functions. For the load tests, I've faced a slightily higher response time and lower rps against the python version for 800 users. Really odd.

[crivetimihai]

@Lang-Akshay # PR findings Summary (Ignore low )

Thanks, I went through this list and split it into "addressed in this PR" vs "tracked follow-up".

Addressed in this PR

• Add postgresql to container build #5 / Use async context manager for initializing gateway #7: fixed in d6c2335 (fix: harden internal MCP trust boundaries)
  • trusted /_internal/mcp/* requests no longer rely on loopback + header alone
  • they now require:
    • loopback peer
    • x-contextforge-mcp-runtime: rust
    • a shared-secret-derived x-contextforge-mcp-runtime-auth
  • Rust injects that header on internal hops and strips any client-supplied copy on public ingress
  • I also revalidated the original spoof case directly against Uvicorn; it now returns 403

No longer a merge blocker after the above fix

• Configure Renovate #1 / gateway registration fix #9: still worth doing as defense in depth, but not a direct bypass anymore
  • nginx should still strip internal x-contextforge-* headers from public requests
  • however, Python no longer trusts those headers by themselves, so this is now follow-up hardening rather than an active trust-boundary hole
• Update testing docs, copilot docs and minor fix to servers/ also offering a servers (no /) endpoint #6: materially downgraded by the same trust-boundary fix
  • forwarded auth context is now accepted only on the authenticated local Rust->Python internal channel
  • query validation may still be worth tightening later, but I don’t think this is a merge blocker for this PR

So the main immediate trust-boundary issues from this list were #5 / #7, and those are now fixed. The rest are either follow-up hardening or no longer blockers after the
internal-channel change.

[cafalchio]

I really like the idea of running rust on the core and slowly implement new modules in rust as we need it.

I am still testing and reading the docs. But I ran docker with full rust and manually tested from the UI. It is all running as expected, including adding an external MCP provider (Claudflare) and running its tools.

Suggestions.

• cargo clippy is not passing for mpc_runtime
• Not for now, but the lib.rs in mcp_runtime could be broken in modules.

AI catches.

• Running wrapper can show the entire config with debug on.

LOG_LEVEL=debug MCP_AUTH="Bearer my-secret-token" MCP_SERVER_URL=http://localhost:4444/mcp cargo run --

• wrapper/src/json_rpc_id_fast.rs:70 -> reading id as u64 can truncate values.

[gcgoncalves]

Can confirm the app is still functional.

[sco3]

works and looks good

[crivetimihai]

I really like the idea of running rust on the core and slowly implement new modules in rust as we need it.

I am still testing and reading the docs. But I ran docker with full rust and manually tested from the UI. It is all running as expected, including adding an external MCP provider (Claudflare) and running its tools.

Suggestions.

• cargo clippy is not passing for mpc_runtime

I tested it directly, and clippy is passing for tools_rust/mcp_runtime.

Ran:

• make -C tools_rust/mcp_runtime clippy
• make -C tools_rust/mcp_runtime clippy-all

• Not for now, but the lib.rs in mcp_runtime could be broken in modules.
  Yes, this is a follow-up tracked in tools_rust/mcp_runtime/FOLLOWUPS.md

AI catches.

• Running wrapper can show the entire config with debug on.

LOG_LEVEL=debug MCP_AUTH="Bearer my-secret-token" MCP_SERVER_URL=http://localhost:4444/mcp cargo run --

• wrapper/src/json_rpc_id_fast.rs:70 -> reading id as u64 can truncate values.

Thanks. I checked both points.

• The tools_rust/wrapper debug logging issue is real: with LOG_LEVEL=debug, the wrapper currently logs Config via debug!("{config:?}"), and that includes mcp_auth. That’s
  actionable, but it’s in the separate wrapper crate, not the Rust MCP runtime path in this PR.
• The json_rpc_id_fast.rs comment is directionally valid but technically overstated: it does not truncate numeric IDs, it falls back to Id::Null when the value cannot be parsed
  as u64.

So I'm not treating either as a blocker for this PR, but the wrapper secret-logging issue is worth tracking/fixing separately. @dima-zakharov please investigate.

[lucarlig]

make -C tools_rust/mcp_runtime clippy
Running cargo clippy --all-targets...
warning: this creates an owned instance just for comparison
   --> src/config.rs:314:48
    |
314 |             ListenTarget::Uds(path) if path == PathBuf::from("/tmp/contextforge.sock")
    |                                        --------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |                                        |
    |                                        help: try: `path == "/tmp/contextforge.sock"`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.94.0/index.html#cmp_owned
    = note: `#[warn(clippy::cmp_owned)]` on by default

warning: `contextforge_mcp_runtime` (lib test) generated 1 warning (run `cargo clippy --fix --lib -p contextforge_mcp_runtime --tests` to apply 1 suggestion)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.35s
    ```

[crivetimihai]

make -C tools_rust/mcp_runtime clippy
Running cargo clippy --all-targets...
warning: this creates an owned instance just for comparison
   --> src/config.rs:314:48
    |
314 |             ListenTarget::Uds(path) if path == PathBuf::from("/tmp/contextforge.sock")
    |                                        --------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |                                        |
    |                                        help: try: `path == "/tmp/contextforge.sock"`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.94.0/index.html#cmp_owned
    = note: `#[warn(clippy::cmp_owned)]` on by default

warning: `contextforge_mcp_runtime` (lib test) generated 1 warning (run `cargo clippy --fix --lib -p contextforge_mcp_runtime --tests` to apply 1 suggestion)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.35s
    ```

I reproduced the code state, but not the warning output on this machine.

What I verified:

• the exact pattern is still present in config.rs:
  • path == PathBuf::from("/tmp/contextforge.sock")
• so the warning report is believable

What happened locally:

• make -C tools_rust/mcp_runtime clippy
• it passed cleanly here without printing the cmp_owned warning

make -C tools_rust/mcp_runtime clippy
make: Entering directory '/home/cmihai/agents2/pr/mcp-context-forge/tools_rust/mcp_runtime'
Running cargo clippy --all-targets...
    Checking contextforge_mcp_runtime v0.1.0 (/home/cmihai/agents2/pr/mcp-context-forge/tools_rust/mcp_runtime)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.55s
make: Leaving directory '/tools_rust/mcp_runtime'

I did not get the warning locally in this run, likely due to toolchain/clippy-version differences or lint configuration differences. Either case, it is a minor warning-cleanup item, not a failing clippy error on my current environment.

[gandhipratik203]

Test Setup

• Machine: MacBook with Colima (8 CPU / 16GB RAM)
• Stack: Docker Compose — 3 gateway instances behind nginx
• Tool: Locust — 125 concurrent users, 30/s ramp-up, 60s duration
• Target: MCP tools/call via http://localhost:8080
• Upstream: fast_test_server (purpose-built MCP benchmark target)

Steps

1. Built Docker image with Rust binary compiled in (make testing-rebuild-rust-full)
2. Started stack in Rust full mode (RUST_MCP_MODE=full make testing-up)
3. Ran benchmark (make benchmark-mcp-tools) — captured Rust results
4. Restarted stack in Python mode (make testing-down && make testing-up)
5. Ran benchmark again — captured Python results

---

Results — 125 users / 60s

Metric	Python	Rust Full	Improvement
Total Requests	30,677	114,015	3.7x more
Failures	24 (0.08%)	0 (0.00%)	Rust cleaner ✅
RPS	512	1,930	3.8x faster
Avg Latency	167 ms	2.84 ms	59x faster
p50	110 ms	2 ms	55x faster
p90	280 ms	5 ms	56x faster
p95	360 ms	6 ms	60x faster
p99	610 ms	11 ms	55x faster
Max	30,001 ms	397 ms	Rust far more stable

---

On failures

All 24 failures were on tools/call in Python mode — none in Rust.

The 30,001 ms max is a Locust timeout (30s hard limit), meaning some requests sat in the queue long enough to be abandoned.

At 125 concurrent users the Python path was already saturated — requests were arriving faster than workers could drain them.

Rust processes the same requests ~60x faster so the queue never builds up. Python is showing stress at 125 users; Rust has not reached its saturation point.

[araujof]

Nice work @crivetimihai ! This review focuses on any potential regressions or interactions with the Plugin Framework.

Summary

No plugin framework regressions identified. The Rust runtime integration is cleanly separated from plugin execution via the has_hooks_for guard. The only semantic change affecting plugins is the prompt_id UUID→name switch in post-hook payloads, which aligns with the pre-hook behavior and is unlikely to affect any plugin in practice.

Test Results

Suite	Result
Plugin framework unit tests	All passed
Service unit tests (tool/prompt/resource)	All passed
New sentinel plugin tests	All passed
Plugin performance profiling (31 plugins)	All profiled, 0 errors

Performance numbers are consistent with baseline. No degradation detected.

Findings

1. Plugins bypass in Rust path

tool_service.py — prepare_rust_mcp_tool_execution correctly falls back to Python when any tool plugin hooks are configured:

if self._plugin_manager and (self._plugin_manager.has_hooks_for(ToolHookType.TOOL_PRE_INVOKE)
    or self._plugin_manager.has_hooks_for(ToolHookType.TOOL_POST_INVOKE)):
    return {"eligible": False, "fallbackReason": "plugin-hooks-configured"}

The Rust hot path is only taken when no tool hooks are registered.

2. prompt_id UUID→name switch

In prompt_service.py, PromptPosthookPayload.prompt_id changed from prompt.id (UUID) to prompt.name (string)

Before: PromptPosthookPayload(prompt_id=str(prompt.id), result=result)
After: PromptPosthookPayload(prompt_id=prompt.name, result=result)

All plugins use prompt_id for logging, passthrough in modified payloads, or as a Cedar/OPA policy resource identifier. No plugin parses it as a UUID. The pre-hook already uses the caller-supplied prompt_id (name or ID string), so this change actually improves consistency between pre-hook and post-hook — both now carry the human-readable prompt name.

3. New internal MCP handlers correctly propagate plugin context

The new handle_internal_mcp_* functions in main.py all extract plugin_context_table and plugin_global_context from request.state and pass them through to service methods. This matches the existing pattern in handle_rpc.

4. resource_service.py server-scoping and MultipleResultsFound handling

The resource service changes add server-scoped queries and handle MultipleResultsFound gracefully. These changes are upstream of plugin hooks (the plugin hooks fire after resource resolution). No interaction with plugin execution.

5. _load_invocable_tools refactoring

The extraction of tool lookup logic into _load_invocable_tools is purely structural. The existing invoke_tool now calls this helper, and the new prepare_rust_mcp_tool_execution also calls it. Plugin invocation in invoke_tool is untouched.

[crivetimihai]

Thanks, this matches my read. I don’t see any plugin-framework regression or new blocker here. The only semantic change worth tracking is the PromptPosthookPayload.prompt_id UUID→name behavior, and that is already captured in tools_rust/mcp_runtime/FOLLOWUPS.md as a contract/schema follow-up.