Sage MCP Server

<div align="center">

Sage — RSI Agent Harness

</div>

Sage is an RSI Agent Harness for improving agents through task feedback. RSI (Recursive Self-Improvement) starts from a goal or curated usage history, retains each version and its evidence, and leaves adoption in your hands.

<picture> <source media="(prefers-color-scheme: dark)" srcset="assets/features-en-dark.png"> <source media="(prefers-color-scheme: light)" srcset="assets/features-en-light.png"> <img alt="Run · Evaluate · Evolve; Models and Context, Skills and MCP, Stateful Execution, Multi-agent, Sandbox and Approvals, Multiple Hosts" src="assets/features-en-light.png" width="1200"> </picture>

Try RSI · Download Desktop · Python SDK · Docs

🔄 How RSI works

Workflow guide · Evaluation and selection rules · Editable diagram (SVG)

What's new in Sage 2.2.0

• Desktop plugins. Open Desktop Plugins in the sidebar to upload a ZIP, launch an installed plugin, or pin it. An Agent can build a plugin and open it in the workspace.
• Sage Voice. Talk to an Agent with live captions and interruption. Enable tools individually and customize spoken progress updates. Voice runs separately from source on Apple Silicon Macs.
• Run-scoped Skills. Agents can discover authorized Skills and load the version referenced by a search result.

Full release notes

🚀 Get Started

Sage, Desktop, Server, and SAgents refer to the current v2 implementation by default. For the legacy version, use the separate Sage v1 guide.

Choose your path	Start here
🧬 First RSI run — Inspect a scripted loop without an API key	Offline walkthrough
💻 Desktop — Configure agents, run RSI, and choose versions	Desktop guide
🎙️ Sage Voice — Talk with an agent, interrupt replies, and configure spoken tool updates. Run from source on Apple Silicon (macOS 15+).	Sage Voice setup (中文)
🌐 Server — Multi-user web access and Agent Studio	Server guide
🧠 SAgents — Build and optimize agents through Python	Runtime quick start
📦 Desktop installers — Available release builds	Downloads & release instructions

<details> <summary>📦 Install Desktop</summary>

1. Download Sage 2.2.0 for macOS (arm64/x86_64), Windows (x86_64), or Linux (arm64/x86_64).
2. Install and open Sage. Python and the backend are bundled; no repository checkout, system Python, or Flutter is needed. Linux still requires GTK and bubblewrap.
3. Add your model in Settings → Configure an Agent → Start a conversation. Your model service may charge usage fees. See the Desktop guide.
4. macOS packages are not notarized; Windows installers are not code-signed. See the release notes for package details.

</details> <details> <summary>💻 Run Desktop from source</summary>

Requires Python 3.12+ and Flutter with Dart ^3.12.2 and desktop support. On macOS:

git clone https://github.com/ZHangZHengEric/Sage.git
cd Sage
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[desktop]'
cd app/v2/desktop
flutter pub get
flutter run -d macos

Add a model → Configure an Agent → Start a conversation or open a project.

The app starts its local backend automatically. Settings and session data live in ~/sage/runtime; the default workspace is ~/sage/agent_workspace.

For Windows and Linux setup, see the Desktop guide. Sage 2.2 packages and the release boundary are documented in v2.2.0 release notes. GitHub Actions builds Flutter v2 installers with an embedded Python runtime; the legacy Tauri installers belong to v1.

</details> <details> <summary>🌐 Run Server from source</summary>

Requires Python 3.12+, MySQL, and Node.js 22.12+. From the checkout root, with the Python environment active:

python -m pip install -e '.[server]'
cp .env.example app/v2/server/.env

Set the MySQL connection, JWT secret, and initial administrator credentials in .env, then run:

cd app/v2/server/web
npm install
npm run build
cd ../../..
python -m app.v2.server

Open localhost:8090. Add a model and an Agent to start chatting, or open /studio to manage Agent packages.

See the Server guide for configuration. Server currently supports one worker; MySQL persistence does not enable horizontal scaling.

</details> <details> <summary>🐍 Complete Python SDK example</summary>

One Python file; no sage.yaml required. After the Python setup above, save as quickstart.py and replace your-model with an available model:

"""Set MODEL_API_KEY and replace your-model below; no sage.yaml file is needed."""

from typing import cast

from sagents.v2.composition.loaded_agents import ApplicationEntrypoint

import asyncio
from uuid import uuid4

from sagents.v2 import ActorRef, RequestContext, SAgentBuilder, StartRun
from sagents.v2.contracts.commands import InputItem
from sagents.v2.contracts.items import TextBlock
from sagents.v2.contracts.principals import PrincipalType
from sagents.v2.package.manifest import SageManifestLoader

AGENT_YAML = """
schema_version: sage/v2
kind: application
metadata: {id: example.assistant, version: 1.0.0, name: Assistant}
agents:
  main:
    name: Assistant
    instructions: {inline: "Be helpful and concise."}
    models: {primary: primary}
entrypoint: {agent: main}
"""

MODELS_YAML = """
credentials:
  api-key: {source: env, key: MODEL_API_KEY}
models:
  primary:
    provider: openai-responses
    base_url: https://api.openai.com/v1
    credential: api-key
    model: your-model
"""


async def main(*, runtime=None, registrations=()):
    from sagents.v2.composition.defaults import default_runtime
    manifest = SageManifestLoader().loads(AGENT_YAML)
    builder = SAgentBuilder()
    for registration in registrations:
        builder.register(registration)
    app = await builder.build(runtime=runtime or default_runtime("runtime"), models_config_text=MODELS_YAML)
    try:
        agent = await app.load_agent(manifest)
        context = RequestContext(actor=ActorRef(
            principal_id="user-1", principal_type=PrincipalType.USER,
        ))
        stream = await cast(ApplicationEntrypoint, app.entrypoint()).run_stream(StartRun(
            agent_id=agent.id,
            input=(InputItem(role="user", content=(TextBlock(text="Say hello!"),)),),
            resolved_spec_hash=agent.composition_hash,
            idempotency_key=str(uuid4()),
        ), context, agent=agent)
        async for event in stream.events:
            print(event.model_dump_json())
        print((await stream.wait()).state)
    finally:
        await app.close()


if __name__ == "__main__":
    asyncio.run(main())

export MODEL_API_KEY="your-api-key"
python quickstart.py

loads() parses YAML text; build() accepts the manifest object directly. This prints events and the final state, without file or shell tools. More configuration options →

</details>

🛠️ Harness capabilities

Capability	What you can do
📦 Packages and versions	Define instructions, Skills, tools, and resources in sage.yaml; retain candidates, diffs, and evaluation records.
🧠 Models and context	Connect model providers and configure routes, memory, and context budgets.
🔌 Tools, Skills, and MCP	Compose native tools, reusable Skills, and MCP services with host-managed authorization.
💾 Stateful execution	Persist Sessions, stream output, and pause/resume for human input and approvals.
🛡️ Sandbox and resources	Bind execution resources, sandbox providers, tool policies, and runtime budgets through the host.
🤝 Multi-agent workflows and extensions	Orchestrate workflows and member messages; replace model, memory, storage, tool, and scheduling providers.
🪟 Native interactive UI	Stream light/dark Glass interfaces, charts, inputs, and slides, with local calculations and editable PPTX export. Explore OpenUI.
🖥️ Multiple hosts	Use Desktop, Server/Studio, or embed SAgents in your Python application.

<details> <summary>📐 Support and runtime boundaries</summary>

• Desktop RSI currently supports simple types and native tools; general MCP integration does not imply support in RSI bindings.
• Built-in configurations target one process or host; Server supports one worker. Local execution is not container isolation.
• Callers curate history into goals or suites. The default workflow uses fixed dev and expanding train; dev guides development and independent test measurements are observation-only.
• RSI produces candidates without activating them. Persistent state does not provide distributed job takeover or automatic checkpoint resume.

RSI support boundaries · Runtime architecture

</details> <details> <summary>📊 Experiment snapshot</summary>

τ²-bench v1.0.1 retail with gpt-5.6-luna as the target model. The baseline and frozen RSI candidate each completed 40 test tasks with four trials per task, for 320 measurements.

Metric	Baseline	After RSI	Gain
Task success pass¹	75.000%	83.125%	+8.125 percentage points
All-four success pass⁴	57.50%	65.00%	+7.50 percentage points

gpt-6.1-sol served as tuner, user simulator, and natural-language judge. Train/dev selected the candidate; test did not influence selection. Results retain 28 paired improvements and 15 regressions. This exploratory local measurement is not an official leaderboard result.

Experiment protocol · Per-trial measurements and statistics

</details> <details> <summary>🧠 SAgents runtime architecture</summary>

flowchart TB
    desktop["Desktop<br/>Flutter workspace"]
    server["Server<br/>Web & Agent Studio"]
    custom["Your application<br/>Python integration"]

    runtime["SAgents<br/>Agent packages · Sessions · Runs"]

    desktop --> runtime
    server --> runtime
    custom --> runtime

    runtime --> intelligence["Models & context<br/>Providers · Memory"]
    runtime --> capabilities["Tools & workflows<br/>Skills · MCP"]
    runtime --> execution["Execution & state<br/>Storage · Sandbox · Events"]

• 📦 Agent package — Define what an agent can do.
• 💬 Session — Keep its conversation history across Runs.
• ⚡ Run — Execute a task with live progress and interaction.

Your application owns the UI, authentication, and credentials. Built-in runtime configurations target a single process or host; local process execution is not container isolation.

Explore the runtime → · Read the architecture →

</details> <details> <summary>📰 Latest updates</summary>

• 2026-10-13 — Streaming UI: from an answer to a native interactive interface — Live generation, local calculations, Process Panel revisions, and editable PPTX export in Desktop 2.1.
• 2026-10-12 — MCP tools are visible, but calls fail: a five-step diagnostic
• 2026-10-12 — RSI: multi-round Agent package optimization, suite audits, semantic review, Desktop progress, and Agent-level version history. See the workflow guide for the current evaluation protocol. Python API · Desktop guide
• 2026-10-11 — OpenRouter free models: selection and limits
• 2026-10-11 — MCP engineering resources: protocols, SDKs, testing, and security
• 2026-10-11 — A read-only MCP smoke test through Sage

More agent resources and tutorials →

</details>

📚 Documentation

Learn	Build
Documentation index	Runtime integration manual
Desktop	Server Agent platform
Server	Deployment
Versioned source layout	v1 directories and import migration
Release notes	Development changelog

Model inference provider resources

Some component guides are currently in Chinese. Use the guide for your chosen entry point.

🛠️ Contributing

Your first PR is welcome! Documentation, translations, examples, tests, bug fixes, and model/tool integrations all help Sage grow. We welcome small, focused improvements and are happy to work with you to get useful, well-tested contributions merged.

Start with the contribution guide for setup, component checks, and a PR checklist. Browse open issues, or open an issue to discuss a larger change before building it. A small documentation fix can go straight to a PR.

Explore sagents/v2/ for the runtime, app/v2/desktop/ for the desktop app, and app/v2/server/ for the web platform.

💬 Community

<div align="center">

</div>

💖 Sponsors

<p align="center"> <a href="https://movoai.pro/"><img src="assets/sponsors/movo_mark.png" height="64" align="middle" alt="Movo" /></a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <img src="assets/sponsors/xunhuanzhineng_logo.svg" height="40" align="middle" alt="RcrAI" /> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <img src="assets/sponsors/idata_mark.png" height="64" align="middle" alt="Data" /> </p>

---

<div align="center">

MIT License · Built with ❤️ by the Sage Team 🦌

</div>