AgentCast

AgentCast is a Rust workspace for an MCP-first agent launcher, runtime, registry, marketplace, and gateway for ACP/MCP-compatible coding agents and tool systems.

The current implementation slice is intentionally narrower than the end-state architecture: AgentCast v0 discovers configured MCP servers, normalizes their tools into launcher actions, searches and lists those actions, invokes selected tools deterministically without an LLM, reads resources/prompts, and previews or applies MCP server configuration from registry metadata.

30-second path: cargo run -p agent-server -- gateway actions -> inspect configured MCP actions -> call a safe action through agentcast_gateway_status or agentcast_gateway_search_actions.

Status: early v0 runtime, not a docs skeleton. Local MCP launcher, gateway, registry, marketplace, HTTP API, OAuth helper, and MCP stdio server paths exist; some end-state docs still describe planned parser and product contracts.

Not for: full ACP session hosting, multi-agent orchestration, remote device deployment, generic service SDKs, homelab media workflows, or arbitrary extension-provided UI/runtime code.

Contents

• Naming
• Capabilities And Boundaries
• Install
• Quickstart
• Client Configuration
• Runtime Surfaces
• MCP Tool Reference
• CLI Reference
• Configuration
• Authentication
• Safety And Trust Model
• Architecture
• Distribution Contract
• Development
• Verification
• Deployment
• Troubleshooting
• Related Servers
• Documentation
• License

Naming

Surface	This repo
Repository	agentcast
Workspace package version	0.1.0
CLI / binary	agentcast
Main HTTP port	127.0.0.1:8787 by default
MCP server mode	agentcast --mcp-stdio
Env/config prefix	AgentCast config files plus process env from configured upstream MCP servers

AgentCast is a guide exception: the repository and binary stay agentcast because the product is broader than an RMCP wrapper. The v0 runtime is still MCP-first, so the README keeps the same operator invariants as the RMCP family.

Capabilities And Boundaries

• Loads AgentCast config and imported MCP JSON config.
• Discovers configured local MCP clients where supported.
• Starts local stdio MCP servers and talks to Streamable HTTP upstreams.
• Discovers tools, resources, resource templates, and prompts.
• Normalizes tools into launcher actions and invokes those actions through one shared gateway/runtime path.
• Exposes HTTP gateway routes and an AgentCast MCP stdio server.
• Supports protected public MCP route metadata and upstream OAuth helper flows.
• Searches official MCP Registry metadata and previews/applies MCP install plans.

This repo owns	Upstream owns	Explicitly out of scope
Runtime orchestration, gateway catalog merge/routing, config import/discovery, registry normalization, install-plan policy, HTTP/MCP/CLI projections, OAuth helper state.	Upstream MCP tool behavior, tool schemas/descriptions, external service state, registry uptime/data durability, OAuth issuer behavior.	Sandboxing untrusted local servers, media-service workflows, generic SDK ownership, ACP session hosting in v0, arbitrary extension UI/runtime APIs.

Install

AgentCast is currently built from source:

git clone https://github.com/jmagar/agentcast
cd agentcast
cargo xtask setup
cargo run -p agent-server -- --help

For a quick local MCP config example, AgentCast can import standard command entries such as npx -y @modelcontextprotocol/server-filesystem /tmp:

[mcp.servers.filesystem]
transport = "local-stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
env = {}
enabled = true

Quickstart

List configured gateway actions:

cargo run -p agent-server -- --enable-imported gateway actions

Search gateway actions:

cargo run -p agent-server -- --enable-imported gateway search files --limit 10

Run AgentCast as an MCP stdio server:

cargo run -p agent-server -- --mcp-stdio

Raw MCP clients can call the AgentCast status tool with JSON-RPC tools/call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "agentcast_gateway_status",
    "arguments": {}
  }
}

Client Configuration

AgentCast reads explicit AgentCast config and can discover supported local MCP client configs when --discover-mcp is used:

cargo run -p agent-server -- \
  --discover-mcp \
  --enable-imported \
  gateway actions

Configured imported MCP servers default to disabled; pass --enable-imported when you want them to run. Standard config locations are:

./agentcast.toml
~/.agentcast/config.toml
~/.config/agentcast/config.toml

Runtime Surfaces

Surface	Command or route	Notes
CLI	agentcast gateway ..., agentcast registry ..., agentcast marketplace ...	Current implemented command families.
HTTP gateway	GET /v1/gateway/status, /v1/gateway/*	Mounted when serving the HTTP gateway.
OAuth helpers	/v1/oauth/*	Probe, authorize, callback, status, refresh, register, and clear helper routes.
MCP stdio server	agentcast --mcp-stdio	Exposes AgentCast gateway tools to an MCP client.
Protected MCP routes	configured route path plus /.well-known/oauth-protected-resource/{*route}	Mounted only when protected-route flags are provided.
Docs/contracts	docs/	Active product and runtime contracts.

MCP Tool Reference

agentcast --mcp-stdio exposes these AgentCast gateway tools:

Tool	Purpose
agentcast_gateway_list_servers	List configured upstream MCP servers and catalog counts.
agentcast_gateway_list_actions	List normalized gateway actions.
agentcast_gateway_search_actions	Search actions by name, description, server, and tool metadata.
agentcast_gateway_call_action	Invoke an action by action id with JSON arguments.
agentcast_gateway_list_resources	List resources exposed by upstream MCP servers.
agentcast_gateway_read_resource	Read a resource through the gateway runtime.
agentcast_gateway_list_prompts	List prompts exposed by upstream MCP servers.
agentcast_gateway_get_prompt	Get a prompt through the gateway runtime.
agentcast_gateway_status	Return gateway server/action counts.

Protected public MCP dispatch currently supports initialize, tools/list, tools/call, resources/list, resources/templates/list, resources/read, prompts/list, and prompts/get.

CLI Reference

Implemented command families:

agentcast gateway actions
agentcast gateway search <query> --limit 20
agentcast gateway call <action-id> --arguments '{"path":"/tmp"}'
agentcast gateway read-resource <server-id> <uri>
agentcast gateway get-prompt <server-id> <name> --arguments '{}'
agentcast registry search <query> --limit 20
agentcast marketplace plan-mcp --server-json '<json>'
agentcast marketplace apply-mcp --server-json '<json>' --config ./agentcast.toml

The documented future top-level commands such as agentcast actions list, agentcast call, and the short ac alias are target v0 contract shapes; the current parser uses the gateway/registry/marketplace families above.

Configuration

Target config precedence:

1. CLI flags.
2. process environment.
3. project config.
4. user config.
5. defaults.

agent-config is the only crate that should discover config files. Runtime crates receive resolved config structs.

Authentication

AgentCast does not turn registry metadata or MCP tool descriptions into trusted credentials. OAuth helper flows store credential state through agent-store primitives; local stdio server auth is whatever the launched process and local environment provide.

MCP callers never provide upstream OAuth client secrets, registry trust decisions, shell command strings, or local server credentials in AgentCast tool arguments. Tool arguments identify gateway actions, resources, prompts, and JSON payloads that the runtime validates before routing.

Safety And Trust Model

AgentCast v0 runs local MCP servers as user-selected executable code. It does not claim to sandbox local MCP servers.

Rules for contributors and operators:

• Treat registry metadata, tool schemas, descriptions, and tool results as untrusted input.
• Store commands and args as structured fields; never turn registry command strings into shell execution.
• Require preview/confirmation before applying install plans or writing config.
• Do not write secrets to ordinary config by default.
• Redact common secret fields in CLI/API output.
• Do not log full tool arguments or results by default when they may contain secrets.

Out of scope for v0: filesystem sandboxing, container isolation, network egress controls, per-tool jails, malware scanning, and registry trust scores.

Architecture

All surfaces should call the same runtime path:

surface -> runtime/gateway -> agent-mcp -> configured MCP server

No CLI, API, MCP, web, or desktop surface should implement its own MCP discovery, action routing, install policy, or result normalization.

The workspace is split into focused crates under crates/; see docs/CRATE_BOUNDARIES.md for the source-of-truth ownership map.

Distribution Contract

Current distribution is source-first:

• Rust workspace version is 0.1.0.
• The binary is agentcast from crates/agent-server.
• Release metadata is managed by release-please files in the repo.
• No npm launcher, Docker image, or plugin bundle is currently the authoritative install path.
• Future packaging must preserve the same runtime path and config safety rules rather than adding surface-specific behavior.

Development

The workspace uses Rust 2024 and requires Rust 1.90.

Expected local setup:

cargo xtask setup
cargo xtask doctor

Useful focused commands:

cargo xtask fmt-check
cargo xtask check
cargo xtask clippy
cargo xtask nextest
cargo xtask test

Verification

Before declaring substantial work complete:

cargo xtask verify

cargo xtask verify runs the CI-sized suite plus cargo test --workspace for doctest and compatibility coverage. For README-only changes, also run:

python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md
cargo xtask audit-docs
git diff --check

Deployment

For local development, run the binary directly:

cargo run -p agent-server --

Serve AgentCast as a local gateway on 127.0.0.1:8787 by default. Use --mcp-stdio for local MCP clients and protected-route flags only when you are intentionally exposing an MCP route with the documented OAuth protected-resource metadata.

Troubleshooting

• No actions appear: confirm MCP configs are present, pass --discover-mcp for supported local client configs, and pass --enable-imported when using imported MCP JSON config.
• A registry install plan looks unsafe: stop at preview; do not pass --write until command, args, cwd, env, and config mutation are reviewed.
• OAuth status is missing: verify issuer metadata, subject/upstream ids, and the configured store path.
• A command documented in docs/CLI.md is unavailable: check docs/MVP.md for whether it is target contract language or already implemented parser surface.

Related Servers

• unifi-rmcp / rustifi - UniFi controller REST API bridge.
• tailscale-rmcp / rustscale - Tailscale API bridge for devices, users, and tailnet operations.
• unraid-rmcp / unrust - Unraid GraphQL bridge for NAS and server management.
• apprise-rmcp - Apprise notification fan-out bridge for many delivery backends.
• gotify-rmcp - Gotify push notification bridge for sends, messages, apps, and clients.
• arcane-rmcp - Arcane Docker management bridge for containers and related resources.
• yarr-rmcp - Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.
• ytdl-mcp - Media download and metadata workflow server.
• synapse - Local Synapse workflow server for scout and flux actions.
• cortex - Syslog and homelab log aggregation MCP server.
• axon - RAG, crawl, scrape, extract, and semantic search project.
• lab - Homelab control plane and Labby gateway project.
• lumen - Local semantic code search MCP server.
• nugs - Project/package management helper for local agent workflows.
• soma - RMCP scaffold/runtime template for new provider-backed servers.

Documentation

This README is the curated operator entry point. The source of truth for v0 scope is docs/MVP.md; the broader docs tree contains generated, contracted, and future-shape design material that should be refined rather than silently flattened into the README.

Start with:

• docs/MVP.md - v0 MCP launcher scope and build order.
• docs/README.md - docs index.
• docs/ARCH.md - target architecture.
• docs/CLI.md - target and current CLI contract.
• docs/API.md - HTTP API contract.
• docs/MCP_RUNTIME.md - MCP lifecycle/runtime behavior.
• docs/INSTALL_PLANS.md - registry-to-install-plan flow.
• docs/SECURITY.md - local execution trust model.
• docs/TESTING.md - verification gates and expectations.

License

Workspace crates declare MIT OR Apache-2.0 in Cargo.toml. No standalone license file is present in this checkout.