AgenticNetOS Now Speaks MCP: Working Memory That Runs

AgenticNetOS Now Speaks MCP

The new AgenticNetOS MCP server lets Claude Code, Claude Desktop, Cursor, and any other MCP client connect to an Agentic-Net as persistent memory, a net builder, a tool-net workbench, and an operating cockpit. It is not just a memory plugin. It is a way for an AI assistant to use a running Petri-net system as its working substrate.

MCP, the Model Context Protocol, gives AI clients a standard way to discover tools, prompts, and resources. AgenticNetOS now exposes that interface through the public @agenticnets/mcp package. A client can bind to a running AgenticNetOS stack and immediately write memory, recall decisions, inspect nets, build transitions, start autonomous personas, crystallize repeatable work into tool-nets, and stop a whole model when it needs to be frozen.

The simplest description is the one in the package itself: working memory that runs. A normal memory store waits for a query. An Agentic-Net keeps processing tokens after the client disconnects. It can distill raw notes, run schedules, move work through a pipeline, call APIs, execute commands, and keep an event trail that explains where every useful piece of state came from.

---

What shipped

The current MCP server is a TypeScript package in the open-source agentic-nets repository. It runs on Node.js 22, uses the official MCP SDK, and reuses the existing AgenticNetOS CLI gateway, master, node, and tool-executor clients. It supports two transports:

• stdio for local MCP clients, for example npx @agenticnets/mcp or claude mcp add.
• streamable HTTP for the compose service, exposed at POST /mcp on port 8091 and protected by a bearer token.

The tool surface has two layers. The lowercase tools are the ergonomic layer: they create the right places, wire known-good inscriptions, hide engine gotchas, and return clean results. The uppercase tools are the native AgenticNetOS catalog: the same tools in-net agent transitions use internally. Together, the server advertises 89 tools: 28 curated tools plus 61 native tools.

claude mcp add agenticnets \
  -e AGENTICOS_GATEWAY_URL=http://localhost:8083 \
  -e AGENTICOS_ADMIN_SECRET=<gateway-secret> \
  -e AGENTICOS_MODELS=my-memory \
  -- npx @agenticnets/mcp

Memory: tokens, places, graph, provenance

The memory layer uses the native AgenticNetOS model. Places hold JSON tokens. Transitions consume tokens, transform them, and emit new tokens. Everything is event-sourced, so memory is not just text retrieved from a vector store. It is structured state with provenance.

• memory_write stores prose or structured data as a memory token. It accepts the standard places inbox, notes, decisions, knowledge, and archive, or any custom runtime place id. It can also create links to related places in the same call.
• memory_recall searches memory. Plain text queries are matched across token fields. Queries that start with FROM pass through as ArcQL, the AgenticNetOS token query language.
• memory_link creates a graph edge between places using a link transition. Link transitions are structure only. They never fire.
• memory_graph walks that graph and returns reachable places, token counts, and labeled edges.
• event_trail answers the important audit question: why does the memory say this? MCP writes are routed through the master’s event proxy, so token writes show up in the model event line.

memory_write works even before the working-memory template is deployed. It auto-creates the runtime place if needed. Later, deploying the template upgrades the same places with a distiller and graph structure because the ids intentionally match.

Starter templates

The deploy_template tool installs ready-made systems. Deploys are idempotent: re-running a template skips existing design-time elements, ensures runtime places, seeds only empty places, assigns inscriptions, and starts only the transitions marked for start.

• working-memory: creates the memory places, connects them into a navigable graph, and starts an LLM distiller that turns raw inbox captures into durable notes.
• dev-team: creates a token-free development pipeline with backlog, ready, in-progress, review, done, log, and charter places. The connected coding agent is the worker. The net supplies state, WIP limits, audit, and a scheduled digest without spending server-side LLM tokens.
• brain: creates an ideation lane where an LLM panel generates candidate ideas and a critic transition narrows them into a vetted shortlist. This one deliberately uses server-side LLM calls.
• watcher: creates a zero-LLM scheduled sentinel. It probes a URL on a cron, logs every result, and can POST an alert to a webhook when the probe is not HTTP 200.
• blank: creates a minimal canvas with input and output places for manual net building.

The templates expose parameters through the agenticnets://templates resource. For example, working-memory lets you override the distiller prompt, dev-team lets you set the digest cron, and watcher lets you set the URL, webhook, cron, and label.

Building nets from an AI client

The server can build real Agentic-Nets, not just write notes. The key is that add_transition does not ask the language model to hand-author fragile runtime inscriptions. It uses kind-aware builders with safe defaults.

• create_net creates a design-time net in the configured MCP session.
• add_place creates both the design-time place for the GUI and the runtime token container required for execution.
• add_transition supports map, llm, http, command, agent, and link transitions. It creates arcs, assigns the inscription, persists a design-time inscription leaf, and starts the transition unless it is a link or start:false was requested.
• set_schedule adds or changes a cron or interval schedule and restarts the transition, because assignment stops transitions internally.
• fire_once, start_transition, and stop_transition control individual lanes.

The inscription builders bake in practical lessons from running the engine. Presets always include a non-empty ArcQL query. LLM and agent transitions get longer default timeouts. Non-link transitions include a catch-all emit rule so successful results are routed to an output place instead of disappearing.

Autonomous personas

There are two persona paths. create_persona creates a charter place and can optionally add a simple LLM lane. spawn_persona creates a full self-driving worker net: charter, task inbox, an agent-kind transition, and an output place.

spawn_persona includes presets for developer, reviewer, researcher, operator, and assistant. You can run a safe reasoning persona with capability:"reason", or grant execution capability with capability:"execute", which gives the agent role flags that allow commands and tool-net calls. You can also choose the normal worker tier or the high reasoning tier.

Once spawned, a persona runs server-side and processes task tokens from p-<name>-task. Results land in p-<name>-output. Several personas can run in parallel while the MCP client keeps working on something else.

Tool-nets and crystallization

AgenticNetOS has a strong opinion: if an agent figures out a repeatable process, that process should become deterministic infrastructure. The MCP server exposes that directly.

• scaffold_tool_net creates an invocable tool-net with input and output places, a trigger, and a manifest. It can pre-wire command, http, or llm behavior so the tool is immediately callable.
• invoke_tool_net calls a tool-net synchronously. It writes an input token, fires the trigger, polls the correlated result, and returns the output data.
• crystallize_session records a session summary, decisions, and deterministic steps into memory. If steps are supplied, it compiles shell commands or HTTP calls into a replayable command tool-net.

This is where memory turns into capability. A chat session can discover the workflow once. The net can replay it later at zero LLM cost.

Client-hosted transitions

The newest piece is host_transition. It lets an MCP process execute an llm or agent transition locally instead of running that transition on the master. In practical terms, the net can use the LLM the client side already has: by default, the local claude binary through the Claude Code provider. Other configured providers include Ollama, Anthropic, OpenAI, and Codex through the CLI provider layer.

The intended pattern is to build the lane with add_transition and start:false, then call host_transition. In watch mode, the MCP process polls the input place and works each arriving token. In once mode, it executes one waiting token immediately. unhost_transition stops hosting and returns run stats.

The honest boundary is important: hosted lanes run only while that MCP process is alive. Tokens that arrive while nobody is hosting remain safely in the input place. For 24/7 unattended work, keep the transition on the master with a server-side model.

Observability and debugging

The MCP server can debug a model without shell access, container logs, or source access.

• net_overview returns structure and live execution status for one net or for every net in the MCP session.
• query_tokens reads tokens from runtime places, either through GET-safe reads or ArcQL.
• event_trail filters the model event line by text, correlation id, category, status, or limit.
• net_stats reports running, stopped, and error transitions; scheduled cron and interval lanes; LLM and agent usage by transition; recent errors; hosted transition stats; tool-net library state; and a paused flag.
• verify_inscription checks transition configuration statically.
• dry_run_transition simulates a fire without emitting.
• diagnose_transition explains why a transition is not firing or what is wrong with its binding.

That gives an assistant a real operating loop: inspect the net, inspect the tokens, read the event trail, verify or dry-run the suspicious transition, apply a narrow fix, and verify again.

Model control: the off switch

Autonomy needs an off switch. pause_model stops every running transition in the model. That means no fires, no schedules, no command execution, and no LLM spend. It writes an audit token to p-mcp-control with the exact set of transitions that were running.

resume_model restarts exactly that recorded set, or an explicit list passed by the caller. One lane can still be controlled with stop_transition and start_transition. net_stats is the meter: it shows what is running, what is scheduled, and whether the model is effectively paused.

The native catalog: full platform parity

The uppercase tools expose the raw AgenticNetOS ToolExecutor catalog. This is full platform parity for MCP clients: create and delete model structure, inspect sessions, export PNML, run package operations, invoke Docker and registry helpers, call HTTP, inspect token size, and use the same diagnostics the in-net agents use.

The native tools currently exposed are:

ADAPT_INSCRIPTIONS, CREATE_ARC, CREATE_NET, CREATE_PLACE,
CREATE_RUNTIME_PLACE, CREATE_SESSION, CREATE_TOKEN, CREATE_TRANSITION,
DELETE_ARC, DELETE_NET, DELETE_PLACE, DELETE_TOKEN, DEPLOY_TRANSITION,
DESCRIBE_TOOL_NET, DIAGNOSE_TRANSITION, DOCKER_LIST, DOCKER_LOGS,
DOCKER_RUN, DOCKER_STOP, DRY_RUN_TRANSITION, EMIT_MEMORY,
EXECUTE_TRANSITION, EXECUTE_TRANSITION_SMART, EXPORT_PNML,
EXTRACT_RAW_DATA, EXTRACT_TOKEN_CONTENT, FIND_NET_NEIGHBORS,
FIND_SHARED_PLACES, FIRE_ONCE, GET_LINKED_PLACES, GET_NET_OVERVIEW,
GET_NET_STRUCTURE, GET_PLACE_CONNECTIONS, GET_PLACE_INFO,
GET_SESSION_OVERVIEW, GET_TRANSITION, HTTP_CALL, INSPECT_TOKEN_SIZE,
INVOKE_TOOL_NET, LIST_ALL_INSCRIPTIONS, LIST_ALL_SESSIONS,
LIST_PLACES, LIST_SESSION_NETS, LIST_SESSIONS_BY_TAG, LIST_TOOL_NETS,
NET_DOCTOR, PACKAGE_INSTALL, PACKAGE_PUBLISH, PACKAGE_SEARCH,
QUERY_TOKENS, REGISTER_TOOL_NET, REGISTRY_GET_IMAGE_INFO,
REGISTRY_LIST_IMAGES, SCAFFOLD_TOOL_NET, SET_INSCRIPTION,
START_TRANSITION, STOP_TRANSITION, TAG_SESSION, VERIFY_INSCRIPTION,
VERIFY_NET, VERIFY_RUNTIME_BINDINGS

THINK, DONE, and FAIL are intentionally excluded because they are agent-loop primitives, not meaningful stateless MCP calls. The native catalog is available in read-write mode only. Read-only mode keeps a smaller set of GET-safe tools instead of advertising operations that the gateway would reject.

Resources and prompts

MCP is more than tools. The server also teaches the client how to use Agentic-Net concepts well.

• agenticnets://models describes the allowed models, default model, mode, and session.
• agenticnets://templates lists deployable templates and parameters.
• agenticnets://tool-catalog lists the native uppercase catalog with descriptions and schemas.
• agenticnets://tool-nets lists reusable tool-nets that can be invoked.
• agenticnets://docs/concepts, arcql, recipes, and security provide the knowledge base the client can read.

It also ships prompts as named recipes: setup-working-memory, work-dev-team-backlog, capture-session, debug-net, spawn-worker, and monitor-personas. Those prompts turn common operations into one-click or one-command entry points in MCP clients that support prompt discovery.

Claude Code hooks: memory without discipline

The package includes two optional Claude Code hook scripts. They are deliberately fail-open: if configuration is missing or the stack is unavailable, they exit cleanly and never block a coding session.

• agenticnets-recall.sh runs on SessionStart, fetches recent decisions and notes, and injects them as additional context.
• agenticnets-capture.sh runs on SessionEnd, summarizes the first user ask, final assistant outcome, cwd, and branch into one raw capture token in p-mem-inbox. The working-memory distiller then turns it into a durable note.

Security and operating boundaries

The server is environment-first. Important configuration includes AGENTICOS_GATEWAY_URL, AGENTICOS_ADMIN_SECRET or AGENTICOS_GATEWAY_SECRET_FILE, AGENTICOS_MODELS, AGENTICOS_MODE, AGENTICOS_SESSION, AGENTICOS_NODE_HOST, and the HTTP transport token when running the compose service.

• Model allowlist: every tool call is validated against AGENTICOS_MODELS. With a single model, the MCP schemas do not expose a model parameter. With multiple models, the optional model argument is checked on every call.
• Read-only mode: AGENTICOS_MODE=readonly registers only memory_recall, memory_graph, net_overview, query_tokens, event_trail, and net_stats. It also authenticates as the gateway’s read-only client, so mutations are rejected by the gateway itself.
• Secrets: the gateway secret and acquired JWT are not returned in tool output. The implementation was tested against secret leakage and unsafe memory input cases.
• Honest boundary: model scoping is enforced inside the MCP process. The underlying gateway credential is not yet model-scoped, so the allowlist protects against client mistakes and prompt injection through the client, not against a malicious operator of the MCP process.
• Command power: command transitions and command tool-nets can run shell on the executor host. That is a feature, but it means read-write access belongs only with trusted clients.
• Schedules act unattended: cron and interval transitions keep firing server-side. net_stats.scheduled shows what is armed, and pause_model freezes it all.

Why this matters

The usual assistant memory loop is passive: store text, retrieve text, hope the retrieved chunk is relevant. AgenticNetOS turns that loop into an operating system for state. Memory is a token in a place. A decision can be linked to the note that caused it. A raw capture can be rewritten by a scheduled distiller. A repeated workflow can become a tool-net. A persona can keep working on task tokens after the chat message is gone. The whole thing can be inspected through an event trail and stopped with a kill switch.

That is the practical difference MCP unlocks here. AgenticNetOS no longer has to be driven through a custom control plugin or raw REST calls. Any MCP-capable assistant can become a front end to the same living substrate: memory, work, tools, personas, schedules, diagnostics, and control, all backed by the net.

There is also a NetHub design in the repository: a future package manager for templates, tool-nets, persona nets, and whole models. That is a design direction, not the current shipped MCP surface. What is available now is the local MCP server: working memory that runs, plus the controls to build, observe, and govern the nets that run it.