System on an Agent
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
System on an Agent: plugin edition
Published by Earthenware Computer. This is the plugin / MCP-server edition of System on an Agent. It carries the full history of that repository plus a stdio MCP server, a Cursor plugin manifest, and MCP Registry metadata, so it can be submitted to the xAI plugin marketplace.
A system on a chip puts a CPU, memory, I/O, and a bus on one piece of silicon. A system on an agent puts the same parts into one agent:
System on a Chip | System on an Agent |
CPU | Planner (the processor) |
Memory | Memory and skills (storage) |
I/O | Connectors (input and output) |
On-chip bus | Bus / router |
The core is only those four parts. Optional add-ons plug in later through a manifest and hook interface, without changing the core.
flowchart TB
subgraph chip["System on a Chip"]
direction LR
c_cpu["CPU"]
c_mem["Memory"]
c_io["I/O"]
c_bus["On-chip bus"]
end
subgraph agent["System on an Agent"]
direction LR
a_cpu["Planner<br/>processor"]
a_mem["Memory + Skills<br/>storage"]
a_io["Connectors<br/>input / output"]
a_bus["Bus / Router"]
end
c_cpu -.-> a_cpu
c_mem -.-> a_mem
c_io -.-> a_io
c_bus -.-> a_busCore
Planner. Takes a goal, builds a plan, and runs it step by step. The default planner is deterministic and rule-based; no language model is required. An optional
LLMProviderinterface can be attached later. If the model fails to return a valid plan, the rule-based planner is the fallback.Memory and skills. Working memory holds short-lived values for the current run. Long-term memory stores facts (optionally persisted as JSON). The skill library is a set of reusable named procedures the planner can run.
Connectors. A pluggable I/O surface. This repository ships a local file connector and an echo (mock) connector.
Bus / router. Routes messages between the planner, memory, skills, and connectors, and fires add-on hooks around each step.
Related MCP server: mcp-context-card
Quickstart
Requires Python 3.10 or newer.
python -m pip install -e ".[dev]"
soa skills list
soa connectors list
soa run "echo hello from system on an agent"
pytestsoa run prints the goal, the plan, and the output. Add --json for a machine-readable report. Built-in goal forms include:
echo hello/say hello— send text through the echo connectorremember the sky is blue— store a factrecall sky— look up factsread path/to/fileandwrite hello to path/to/file— file connectorlist skills/list connectorsJoin steps with
then:echo hi then remember hi was said
Use as an MCP server
soa mcp (or system-on-an-agent mcp) serves the system over the Model Context Protocol on stdio. The server is built into the package: it needs no extra dependencies and opens no network sockets.
Tool | What it does |
| Plan a goal with the rule-based planner and return the steps without running them. |
| Plan and run a goal on the bus; returns the plan, each step result, and the output. |
| Store a fact (with optional tags) in long-term memory. |
| Look up facts by substring; an empty query returns all facts. |
| List the skill library with descriptions and parameters. |
| Run one named skill through the bus, e.g. |
| List the registered connectors ( |
Options go before mcp:
--file-root DIRconfines the file connector toDIR(default: the working directory). Paths that escape it fail.--memory-file PATHpersists long-term memory as JSON atPATH(default: in memory for the session).--addon PATHloads an optional add-on, as withsoa run.
Connect it to an MCP client
Run it straight from GitHub with uv:
{
"mcpServers": {
"system-on-an-agent": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Earthenware-Computer/system-on-an-agent-plugin",
"system-on-an-agent",
"mcp"
]
}
}
}Or install it into a Python 3.10+ environment and point the client at the script:
python -m pip install "git+https://github.com/Earthenware-Computer/system-on-an-agent-plugin"{
"mcpServers": {
"system-on-an-agent": {
"command": "system-on-an-agent",
"args": ["--file-root", "/path/to/workdir", "--memory-file", "/path/to/memory.json", "mcp"]
}
}
}This repository is also a Cursor plugin: .cursor-plugin/plugin.json points at mcp.json, the skill, and the logo. server.json describes the server in the MCP Registry format.
Test it locally
python -m pip install -e ".[dev]" # adds pytest, ruff, and the official MCP Python SDK
ruff check src tests
pytest # tests/test_mcp_client.py starts the server and calls every toolSubmitting to the xAI marketplace
The Submit a plugin form lists plugins for Grok Bot, Cursor, and Grok (coming soon). It takes an MCP server URL or a public GitHub repository, which this repository is (submit this plugin repository, not the upstream one). The form does not publish a manifest spec, so this repo follows the Cursor plugin format (.cursor-plugin/plugin.json + mcp.json) and MCP Registry server.json conventions. That is an assumption to confirm during review.
Done in the repo:
Working stdio MCP server with seven tools, tested through the official MCP client
Cursor plugin manifest,
mcp.json, skill, and a square logo (assets/logo.svg,assets/logo.png)server.jsonfor the MCP RegistryMIT license, no secrets or required environment variables
Needs a person:
First and last name of the submitter
Work email. The form asks for a work email, so a personal Gmail may not pass review.
Organization name (Earthenware Computer) and a unique lowercase organization handle (no spaces), e.g.
earthenware-computerWebsite URL (optional), e.g.
https://fitzyracing1.github.io/system-on-an-agent/Logotype URL: a 1:1 SVG or PNG with a background plate.
https://raw.githubusercontent.com/Earthenware-Computer/system-on-an-agent-plugin/main/assets/logo.pngPick where to be listed: Grok Bot, Cursor, and/or Grok (coming soon)
MCP Server URL or Public GitHub Repository:
https://github.com/Earthenware-Computer/system-on-an-agent-pluginBrief description and testing instructions (for example: add the
mcp.jsonentry above, calllist_skills, thenrun_goalwithecho hello then remember hello was said)Test the plugin locally and in-app, then tick the box confirming it works
Read and accept the Publisher Terms
Optional: publish
system-on-an-agentto PyPI and thenserver.jsonto the MCP Registry (mcp-publisher), which needs PyPI and GitHub sign-in
Optional add-ons
Add-ons are not part of the core. They load from a Python file or a directory (containing soa_addon.py or addon.py) and declare a manifest plus the hooks they implement:
before_plan(plan, context)after_plan(plan, report, context)before_step(step, context)after_step(step, result, context)on_error(step, error, context)
soa --addon path/to/addon.py run "echo hello"The module must expose an Addon class, a create_addon() factory, or an addon instance. See docs/addons.md for the interface and for reserved future add-ons (heatgate and the Lex loop), which are documented only as placeholders and are not implemented here.
License
MIT. Copyright (c) 2026 Joshua Almeida.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Skills, agents and memory in the cloud, plus a gateway to your other MCP servers.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn agent-capable MCP server with terminal access, filesystem control, and persistent memory. It includes sandboxing, access control, activity logging, and a file-backed memory store for context across conversations.32 PyPIMIT
- AlicenseAqualityBmaintenancePersistent project context (AGENTS.md), cross-session memory, and identity — discoverable by any MCP client.10481 npm3MIT
- AlicenseBqualityDmaintenanceAn all-in-one MCP server that enables AI agents with local system capabilities like filesystem navigation, command execution, desktop automation, and a continuity memory suite for persistent cross-session project context.37MIT
- AlicenseNot gradedqualityAmaintenanceProvides a drop-in MCP memory server over stdio using a local SQLite store, enabling agents to store, search, and audit memory with provenance, scoped access, and contradiction tracking without requiring API keys, LLMs, or embedding providers.1,147 npm17Apache 2.0