# Agent-MCP: a shared memory bank for coding agents, wrapped in the Model Context Protocol

> A TypeScript and Python project that stores project context in a SQLite vector store, runs specialised agents as tmux sessions, and exposes the whole arrangement to Claude Desktop as an MCP server. The docs contradict themselves on ports and version numbers, which is the interesting part.

**rinadelph/Agent-MCP** — Agent-MCP is a framework for creating multi-agent systems that enables coordinated, efficient AI collaboration through the Model Context Protocol (MCP). The system is designed for developers building AI applications that benefit from multiple specialized agents working in parallel on different aspects of a project.

- Repository: https://github.com/rinadelph/Agent-MCP
- Stars: 1,305 · Forks: 182
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/rinadelph-agent-mcp

## A memory bank first, an agent framework second

The README's own framing is that this is Obsidian for your AI agents: a knowledge graph where several agents collaborate through shared context, task management and live visualisation. That framing is worth taking literally, because it settles what the project actually is. It is not an agent library with storage attached. It is a context store with agents attached.

The storage layer is what the README calls a memory bank, holding the project's context in a searchable form that agents query to recover requirements, architectural decisions and implementation detail. The dashboard renders it as a graph where purple nodes are context entries, blue nodes are agents, and the edges are live collaborations. So the primary object in this system is a context entry, and an agent is something that reads and writes entries while a task manager decides who does what next.

The motivation list explains why. Traditional single-assistant coding hits context windows that overflow on a large codebase, knowledge that disappears between conversations, single-threaded execution, no specialisation because one agent tries to do everything, and constant rework caused by lost context. Five operational complaints, and each maps onto a subsystem: persistence answers the first two, parallel execution answers the third, role-shaped agents answer the fourth, and dependency-aware task management answers the fifth.

What is not on that list is worth noticing too. Nothing in the README claims that an agent reading this memory writes better code. The claim is narrower and more falsifiable: the same work will not have to be re-derived from scratch, and two agents working in parallel will not overwrite each other. Judge the project on that axis rather than on reasoning quality, and the feature list becomes much easier to assess.

## Two implementations, one of them barely declared

There are two codebases, and the README marks the Python one as recommended. The stated floor is Python 3.10 or newer, Node 18 or newer and npm 9 or newer, with a `.nvmrc` in the tree for version pinning.

```bash
# Clone and setup
git clone https://github.com/rinadelph/Agent-MCP.git
cd Agent-MCP

# Check version requirements
python --version  # Should be >=3.10
node --version    # Should be >=18.0.0
npm --version     # Should be >=9.0.0

# If using nvm for Node.js version management
nvm use  # Uses the version specified in .nvmrc

# Configure environment
cp .env.example .env  # Add your OpenAI API key
uv venv
uv install

# Start the server
uv run -m agent_mcp.cli --port 8080 --project-dir path-to-directory

# Launch dashboard (recommended for full experience)
cd agent_mcp/dashboard && npm install && npm run dev
```

The Python dependency list in `pyproject.toml` is a real service stack: `starlette` and `uvicorn` for HTTP, `click` for the CLI, `openai` for the model calls, `mcp>=1.8.1` for the protocol, `httpx`, `jinja2` for templates, `python-dotenv`, `anyio` and `sqlite-vec` for retrieval. That is a coherent set.

The Node manifest is where the gap shows. `package.json` in the repository root declares exactly two dependencies, `sqlite-vec` at `^0.1.7-alpha.2` and `typescript` at `^5.9.2`. There is no web framework, no MCP SDK and no model client in that list. The alternative implementation advertised in the README is launched with `npm run server` from the `agent-mcp-node` directory, or installed globally as `agent-mcp-node` and run as `agent-mcp --port 8080 --project-dir path-to-directory`, but the manifest that is supposed to support those commands does not describe them.

There is a second inconsistency in the Python dependency handling worth knowing about, because it bites people who follow the wrong file. `requirements.txt` lists `tabulate`, `pyperclip` and `requests`, none of which appear in the `pyproject.toml` dependency list. Two dependency manifests, two different answers to what the Python side needs. If you install with `uv install` you get the `pyproject` set; if you install with pip from `requirements.txt` you get a different one, and the extra three packages suggest the requirements file is the more accurate reflection of what the code imports.

## The MCP surface, which is the part clients actually see

The protocol angle is the reason this project is worth a look even if you never run the dashboard. Agent-MCP can run as an MCP server, which means the orchestration layer sits behind the same interface that Claude Desktop, Cline and other clients already speak. You describe agents and tasks in ordinary client conversation and the server does the bookkeeping.

The README shows a configuration file that declares what that surface contains.

```json
{
  "server": {
    "name": "agent-mcp",
    "version": "1.0.0"
  },
  "tools": [
    {
      "name": "create_agent",
      "description": "Create a new specialized AI agent"
    },
    {
      "name": "assign_task", 
      "description": "Assign tasks to specific agents"
    },
    {
      "name": "query_project_context",
      "description": "Query the shared knowledge graph"
    },
    {
      "name": "manage_agent_communication",
      "description": "Handle inter-agent messaging"
    }
  ],
  "resources": [
    {
      "name": "agent_status",
      "description": "Real-time agent status and activity"
    },
    {
      "name": "project_memory",
      "description": "Persistent project knowledge graph"
    }
  ]
}
```

Treat that file as a statement of intent rather than proof of implementation, since it is described as something you create. The tool list does describe a coherent division of labour though: `create_agent` and the `list_agents` and `terminate_agent` trio from the README handle the agent lifecycle, `assign_task` handles delegation, `query_project_context` is the read path into the memory bank, and `manage_agent_communication` covers agent-to-agent messaging. Splitting reads (`query_project_context`, `agent_status`, `project_memory`) from writes is the right shape for a shared store, because it lets a client observe state without mutating it.

The client wiring is a stdio command with an environment block, which is the ordinary Claude Desktop pattern:

```json
{
  "mcpServers": {
    "agent-mcp": {
      "command": "uv",
      "args": ["run", "-m", "agent_mcp.cli", "--port", "8080"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}
```

One thing to note there. This launches the server as a stdio MCP server, but the same command also opens an HTTP port. So a client talking over stdio and a browser dashboard connecting over HTTP are looking at the same process, which is convenient and also means the admin token path in `.env.example` becomes relevant, since `MCP_ADMIN_TOKEN` is documented as granting direct access without prompting.

## Version numbers that do not agree with each other

The package metadata says 2.5.0. The newest release tag says 4.20.1.

`pyproject.toml` declares `version = "2.5.0"` with the description line "AgentMCP v2.5 - Enhanced multi-agent system with tmux integration and worktree support". The two releases in the repository are `v4.20.0` and `v4.20.1`, and both were published within a few hours of each other in September 2025. Nothing in the README or the docs directory reconciles the two numbering schemes, and the repository tree does contain several comparison documents, `AGENT_MCP_COMPARISON_ANALYSIS.md`, `TASK_CREATION_REQUIREMENTS_ANALYSIS.md` and `TOOL_BY_TOOL_LOGIC_COMPARISON.md`, none of which mention the discrepancy in what is visible here.

The practical consequence is that you cannot use the manifest version to decide what you are running. If you install from a source checkout you get 2.5.0 metadata regardless of which commit you are on. If you pin a tag you get the release behaviour and the metadata still says 2.5.0. So pin the tag and ignore the version field, and if you need to know whether a fix landed, compare tag dates rather than version strings.

Licensing has a similar shape. Repository metadata reports the license as unasserted, while `pyproject.toml` states `license = {text = "MIT"}` and carries the `License :: OSI Approved :: MIT License` classifier, and a `LICENSE` file exists in the tree. Three sources, and the two authoritative-looking ones agree on MIT. Read that as MIT in practice, but note that the automated detection came back empty, which usually means the file is non-standard or the metadata was never set properly.

On activity, the most recent push is dated 2026-03-28, with 1,293 stars, 180 forks and 20 open issues. That push is a little over six months old as of October 2026, and the newest release predates it by more than six months, so there is a stretch of work on `main` with no release attached to it. Read the diffs since the last tag before assuming a bug is fixed.

## Ports, module names, and two dependency files

The setup instructions contradict each other in a way that will cost you an afternoon if you do not spot it in advance.

Every start command in the project uses port 8080. The Python quick start passes `--port 8080`, the Node global invocation passes `--port 8080`, the Claude Desktop config passes `--port 8080`, the rye scripts hardcode `--port 8080`, and `.env.example` sets `MCP_SERVER_URL=http://localhost:8080/messages/`. The quick MCP setup block, however, tells the client to connect to `http://localhost:8000/mcp` and `ws://localhost:8000/mcp/ws`. Port 8000 appears nowhere else in the project. So a client configured from that block will not reach a server started from any documented command.

The endpoint path disagrees as well. The example client path ends in `/mcp`, which matches the MCP transport convention, while the environment variable ends in `/messages/`, which is a JSON-RPC style path. At least one of them is stale.

The module name has a second problem. The README consistently says `agent_mcp.cli` with an underscore, and so does the Claude Desktop config, which is correct for a Python package. The rye scripts in `pyproject.toml` say `agent-mcp.cli` with a hyphen, in all three of `run`, `start` and `cli`. A hyphen is not a legal character in a Python module path, so those three scripts cannot work as written. They also pass a `server` subcommand that the README never mentions, meaning `uv run rye run start` and the documented `uv run -m agent_mcp.cli --port 8080` are not the same command.

None of this is exotic. It is the ordinary state of a fast-moving project whose documentation is written faster than it is verified, and the README says as much in a notice at the top, describing itself as aimed at experienced developers who already know MCP and distributed systems, and stating that documentation and ease of use are being worked on. Read that notice as accurate. When a command disagrees with itself, trust the one that appears in the working code path rather than the one in the summary section.

## What the release notes reveal about the internals

The two release notes are short and unusually revealing, because they name internal modules, tables and URI schemes rather than listing features.

`v4.20.0` introduced a testing task system. Testing agents receive their own tasks carrying full audit information, and the README of the release lists exactly what they can reach: all subtasks created by the original agent, every context entry modified during the work, the complete list of changed files with notes, the full log of agent actions, and the complete timeline. A new `testingTasks.ts` module carries the audit tools, and testing agents launch automatically when the original task completes, then feed results back.

That list is the strongest evidence for the project's central claim. An audit surface over subtasks, context entries, files and actions is what turns persistent memory from a promise into something you can inspect after the fact. It also explains why the dashboard can draw collaboration edges at all: there must be a recorded link between an agent, a task and the context entries that task touched.

`v4.20.1` then fixed three concrete defects, and each one names a mechanism. Token resource URIs were corrected from a bare `admin` to the `token://admin` form so MCP resource access resolves, and a `logs://server` URI scheme was added for debugging access, which implies resources are URI-addressed with distinct schemes per kind. A column reference bug in the `agent_actions` table was preventing testing agents from logging at all, and token authentication problems were preventing those agents from reaching MCP tools at all. The release claims the workflow is now task completion, automatic testing agent launch, validation, then feedback to the original agent.

So agent state is a resource a client can read, not only a tool result, and the same URI scheme namespace covers tokens, agents, tmux and server logs. The repeated mention of tmux, in both the package description and the release notes, indicates that agents run as tmux sessions rather than as in-process tasks. That design choice explains how concurrency and worktree support are practical, and it has a side effect worth planning for: each agent is a separate process with its own terminal, so you can attach to one and watch what it is doing, and a wedged agent can be inspected rather than simply killed. Storage is `sqlite-vec` in both ecosystems, and a `LOCAL_EMBEDDINGS_GUIDE.md` in the tree points at retrieval running against local embeddings, so there is no vector database service to operate.

## Conclusion

Agent-MCP is worth reading if your problem is context loss across agents rather than weak reasoning, because the audit surface in v4.20.0 is the part that makes persistence checkable: subtasks, context entries, changed files and action logs are all addressable, and state lives in SQLite through sqlite-vec rather than in a service you have to operate. Three things to check before you adopt it. The version numbers do not agree, since `pyproject.toml` says 2.5.0 while the newest tag is v4.20.1, so pin the tag rather than the manifest. The setup instructions conflict, because the quick MCP block points a client at port 8000 while every start command uses 8080, and the rye scripts spell the module `agent-mcp.cli` with a hyphen that a Python module path cannot contain. And the Node manifest declares only sqlite-vec and typescript, so treat the Python path as the only complete one. Start with `uv run -m agent_mcp.cli --port 8080 --project-dir .` and open `agent_mcp/dashboard` before wiring a client to anything.

## FAQ

### What is an MCP agent?

In this project an MCP agent is a specialised worker that Agent-MCP creates and supervises, reachable through the Model Context Protocol so that a client such as Claude Desktop can spawn one, assign it a task, query shared project context, read its status and terminate it when the work is done.

### Is an MCP the same as an agent?

No. The Model Context Protocol is the transport and interface standard, while an agent is the process that acts through it. Agent-MCP uses both: the agents do the work, and the protocol is the layer that lets an MCP client create them, assign tasks and read resources without knowing anything about the Python process underneath.

### Can an agent be an MCP server?

Yes, and that is exactly how Agent-MCP is positioned. The system runs as an MCP server exposing multi-agent orchestration as tools and resources, so a separate client such as Claude Desktop or Cline drives the agents rather than the agents driving the client. The configuration launches it with a stdio command while the same process also serves HTTP on port 8080.

### What does the MCP do?

It gives an AI client a standard way to reach external tools and data. Here that means the context memory bank, the agent lifecycle tools including create, list and terminate, task assignment, and inter-agent messaging, plus resources for live agent status and the persistent project knowledge graph.

## Sources

- [Issues](https://github.com/rinadelph/Agent-MCP/issues)
- [README](https://github.com/rinadelph/Agent-MCP/blob/main/README.md)
- [Releases](https://github.com/rinadelph/Agent-MCP/releases)
- [rinadelph/Agent-MCP on GitHub](https://github.com/rinadelph/Agent-MCP)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rinadelph-agent-mcp