MCP Agent Toolkit

A local Rust MCP server for expression evaluation, file and document operations, workflow automation, and runtime diagnostics. MCP runs through the connector's direct-stdio boundary. The companion daemon exposes only a loopback product API for lifecycle, status, usage, and observability.

Features

• Type-safe MCP protocol handling through rust-mcp-schema.
• MiniJinja expressions for workspace paths, mappings, rendering, and state.
• File, document, search, logging, and workflow operations.
• Workspace and access-root policy enforcement.
• Direct-stdio connector with workspace-roots negotiation and bounded retries.
• MCP-free product daemon with health, status, lifecycle, and operator UI.

Installation

Download a prebuilt binary

Precompiled release binaries are published at:

• https://forgejo.jrtv.dk/johnny/mcp-agent-utils/releases

Build from source

git clone https://forgejo.jrtv.dk/johnny/mcp-agent-utils.git mcp-agent-toolkit
cd mcp-agent-toolkit
cargo build --release   # builds the embedded observability UI automatically

The compiled binary is at target/release/mcp-agent-toolkit: one executable that serves as CLI connector and, via the hidden daemon serve subcommand, as the daemon (started automatically by connect, or run directly). Windows executables carry .exe.

Build ordering: cargo build builds the UI automatically — a build script in crates/browser runs ui/build.sh (npm/npx and trunk on PATH, plus the wasm32-unknown-unknown target) whenever UI inputs change, so no manual step is needed from a source checkout. For an offline build that embeds the current crates/browser/ui/dist as-is, set MCP_AGENT_TOOLKIT_SKIP_UI_BUILD=1. If ui/dist is missing when the browser crate compiles, the build succeeds with an empty asset image and the UI routes (/ plus the fingerprinted CSS/JS/WASM assets) answer 404 while the v1 API keeps working — rebuild the UI and the daemon to restore them. A built binary is unaffected by moving or deleting dist/ afterwards; the bytes are compiled in. See crates/browser/ui/README.md for the full pipeline.

Configure an MCP client

Configure the client to launch the connector directly over stdio:

{
  "servers": {
    "mcp-agent-toolkit": {
      "type": "stdio",
      "command": "mcp-agent-toolkit",
      "args": ["connect"]
    }
  }
}

Use the absolute binary path when it is not on the client's PATH. For a source checkout, use target/release/mcp-agent-toolkit after building.

The connector owns MCP initialization, roots negotiation, tool dispatch, and newline-delimited JSON-RPC. The product daemon is started or reused behind the connector; its HTTP API is not an MCP transport.

Workspace roots

Workspace roots use the standard MCP roots flow. After initialization the connector requests roots/list from the client and registers each root with the daemon; it re-syncs on notifications/roots/list_changed, and a reported list replaces the connector's default root. As a fallback for clients that do not implement the roots capability, the connector registers its own workspace root (connect --root, cwd fallback) on connect so workspace-bound calls can bind from the first call.

Settings files

The toolkit merges these settings layers in ascending priority order; later layers override earlier layers, and missing files are skipped:

1. Built-in defaults
2. User/global: ~/.config/mcp-agent-toolkit/settings.yml ($XDG_CONFIG_HOME is honored when set; on Windows the per-user AppData/Roaming location). The environment variable MCP_AGENT_TOOLKIT_CONFIG_DIR redirects this root and is used by tests.
3. Project: <workspace>/.mcp-agent-toolkit/settings.yml (version control)
4. Project-local: <workspace>/.mcp-agent-toolkit/settings.local.yml (ignored by version control)

The workspace paths use each client's resolved workspace root. Maps merge deeply; lists are replaced whole; value_mappings merge by name. Project layers cannot set daemon.*, access_roots, or logging; those keys are ignored with a warning and must live in the user/global layer.

Product daemon controls

Run the daemon directly when inspecting product state:

mcp-agent-toolkit daemon serve    # start the daemon (adopts a running one)
mcp-agent-toolkit status          # print status and usage counters
mcp-agent-toolkit log --tail 50   # show recent daemon log lines
mcp-agent-toolkit exit            # force the daemon to exit

status and log read the daemon's observability endpoints over loopback, and exit is always understood regardless of versions running. The daemon serves /api/v1/health, /api/v1/status, /api/v1/clients, /api/v1/queues, /api/v1/usage, /api/v1/logs, /api/v1/events (WebSocket), and /api/v1/log, plus the embedded operator UI at /. It does not accept MCP protocol messages; connector traffic uses /ws.

Development

cargo build
cargo test
cargo doc --no-deps

Tool contracts are available at runtime through the instructions and help MCP tools; see Configure an MCP client for setup.

License

Licensed under either Apache License, Version 2.0 or the MIT license, at your option.