AgentX: a Java platform for building chat agents through natural language and MCP

What AgentX is and what the design bet is

AgentX is a platform for building intelligent agents on top of large language models and a multi-capability platform based on MCP. The README states its goal directly: to simplify the process of creating an agent, so that a user can build a personalised intelligent agent without complex flow nodes or drag-and-drop operations, using only natural language and tool integration.

That is the whole bet of the design. Most agent platforms start from a canvas and expect you to wire nodes. AgentX starts from a description and expects you to attach capabilities, on the assumption that the tool interface matters more than the orchestration graph. If that assumption is right, the person who can describe what an agent should do is the person who can build it, and no diagram is needed.

The project is Java, built as a Spring Boot backend with a Next.js frontend. The repository layout shows the pieces: an AgentX/ directory holding the Maven backend with its pom.xml and src/, an agentx-frontend-plus/ directory for the frontend, a deploy/ directory, a docker/ directory, a production/ directory, a docs/ directory and a TODO.md.

The feature list is checked off in the README and it is worth reading as a scope statement. Agent management for creation and publishing, LLM context management with a sliding window and a summarisation algorithm, agent strategy through MCP, large model providers, users, a tool marketplace, the MCP Server community, the MCP gateway, preset tools, agent scheduled tasks, agent OpenAPI, the model high-availability component, RAG, billing, agent monitoring, embedded website widgets and long-term memory.

Two entries are not ticked. Multi Agent and the knowledge graph are both still to do, which is a useful thing to know before you plan an architecture around them.

The one-image deployment and the ports it opens

The recommended path is a single Docker command, aimed at people who want to try the whole thing without reading the source.

You fetch the configuration template and edit it:

curl -O https://raw.githubusercontent.com/lucky-aeon/AgentX/master/.env.example
cp .env.example .env

Then you start everything, frontend, backend, database and message queue together:

docker run -d \
  --name agentx \
  -p 3000:3000 \
  -p 8088:8088 \
  -p 5432:5432 \
  -p 5672:5672 \
  -p 15672:15672 \
  --env-file .env \
  -v agentx-data:/var/lib/postgresql/data \
  -v agentx-storage:/app/storage \
  -v /var/run/docker.sock:/var/run/docker.sock\
  --add-host=localhost:host-gateway \
  ghcr.nju.edu.cn/lucky-aeon/agentx:latest

The port map is the service list: 3000 is the frontend, 8088 the backend API, 5432 the PostgreSQL instance, 5672 RabbitMQ and 15672 the RabbitMQ management interface. The last two ports are described as optional in the README's service table, since you can point the application at external PostgreSQL and RabbitMQ instances instead.

The Dockerfile explains the packaging. It is a three-stage build: a Maven stage on eclipse-temurin-17 builds the backend jar with tests skipped, a Node 18 Alpine stage installs the frontend dependencies with legacy peer deps and runs the Next.js build, and the runtime stage is based on pgvector/pgvector:pg15, which brings PostgreSQL 15 with the vector extension the RAG feature needs. The runtime stage also installs OpenJDK 17, RabbitMQ server, supervisor and Node 18, and the application jar plus the built frontend are copied in from the earlier stages.

Two things about that command are worth reading carefully rather than copying. The container mounts the host Docker socket at /var/run/docker.sock, which gives the container control of the Docker daemon on the host. And the add-host line maps localhost to the host gateway, which is what lets the frontend inside the container reach a service running on the host.

The image is pulled from ghcr.nju.edu.cn rather than from GitHub Container Registry, which is a mirror, and that choice is usually about download speed from mainland China rather than about the image contents.

Configuration: the keys that matter and the ones you must change

Configuration is entirely through a .env file, and the README groups the keys into categories with a table of defaults.

The basics are SERVER_PORT for the backend API, defaulting to 8088, DB_PASSWORD for the database, defaulting to agentx_pass, and RABBITMQ_PASSWORD for the queue, defaulting to guest. Under security there is JWT_SECRET, marked as must change, and AGENTX_ADMIN_PASSWORD with a default of admin123. Under external services there are EXTERNAL_DB_HOST and EXTERNAL_RABBITMQ_HOST, both empty, meaning use the built-in ones.

The security section is where the README spends most of its warning, and the list of keys that must change before production is short and specific: JWT_SECRET set to a secure key of at least 32 characters, AGENTX_ADMIN_PASSWORD, DB_PASSWORD and RABBITMQ_PASSWORD.

JWT_SECRET=your_secure_jwt_secret_key_at_least_32_characters
AGENTX_ADMIN_PASSWORD=your_secure_admin_password
DB_PASSWORD=your_secure_db_password
RABBITMQ_PASSWORD=your_secure_mq_password

There are also groups for cloud storage and external services. For object storage you can configure Alibaba Cloud OSS with its endpoint, access key, secret key and bucket, or AWS S3 with its secret id, secret key, region and bucket name. For AI services there is a SILICONFLOW_API_KEY and a HIGH_AVAILABILITY_ENABLED flag pointing at HIGH_AVAILABILITY_GATEWAY_URL.

For notifications and authentication there is SMTP mail configuration, GitHub OAuth with a client id and secret, and payment service keys for Alipay and Stripe.

The default accounts are stated in the README and repeated in the example configuration. The administrator is [email protected] with the password admin123, and there is a test user [email protected] with test123, which the example file marks as something to disable in production. The README also carries a note that before deploying to production you should change the default passwords and the JWT secret in the .env file.

The default values in the example file are a reminder that this configuration is meant to be edited, and the file is commented in Chinese throughout to explain what each key does.

The sub-repositories: the MCP gateway and the model availability component

The architecture deliberately splits the platform into a main repository and three related ones, and the README lists them under related links.

API-Premium-Gateway is the model high-availability component. mcp-gateway is the MCP service unified management piece. agent-mcp-community is an open source community for MCP Servers.

The gateway is deployed separately and is optional. The README says that if you need the API high availability functionality you can additionally deploy it, and it gives the command:

docker run -d \
  --name agentx-gateway \
  -p 8081:8081 \
  ghcr.io/lucky-aeon/api-premium-gateway:latest

The Dockerfile carries a comment confirming the split. It says the API gateway has been removed and that users can choose to deploy it separately, and if you need the gateway functionality you should run that container.

This arrangement is the practical answer to the problem of the main image becoming enormous. Bundling the frontend, the backend, PostgreSQL with pgvector, RabbitMQ and Node into one image is convenient for a first run and painful to operate, so the component that has an independent lifecycle, the model gateway, is a separate image that you can place wherever it belongs, including next to a cluster of upstream providers.

The community repository is the other half of the picture. MCP is only useful if there are servers to connect to, so shipping a community of MCP Servers alongside the gateway means a new user can build an agent with tools on day one rather than writing their own first.

The README also links learning resources, a video tutorial on Bilibili, a detailed guide in the community, and an online slide deck introducing the project, which suggests the project expects a lot of its users to arrive through documentation rather than through the code.

Limits: default credentials, a Docker socket mount and an unfinished feature set

The limits are worth being concrete about, and most of them are visible in the documentation itself.

The first is the default credentials. The README publishes the administrator account and password, the test account and password, and the defaults sit in the example .env file. Anything that starts the container with the default configuration is running with a known administrator password on a known email address, and the ports are published on the host by default, so 3000, 8088, 5432, 5672 and 15672 are reachable as written.

The second is the Docker socket mount. Mounting /var/run/docker.sock gives the container the ability to control the Docker daemon on the host, which is a privilege escalation path if anything in the container is compromised. It is presumably there so the platform can start or manage the runtimes it needs, but it is a mount to think about rather than accept.

The third is the unfinished feature set. Multi Agent and the knowledge graph are unchecked in the README's list. For a platform whose selling point is natural-language agent building, the absence of multi-agent orchestration is a real gap, and a knowledge graph is the usual answer to long-term memory questions that this project otherwise addresses with the sliding window and summarisation approach.

The fourth is the release history. The tags are v0.0.14, v0.0.13 and v0.0.12, all from September 2025, while the last push to the repository was on 2026-06-22. A version 0.0.x line signals that the interface is not settled, and the gap between the last tag and the last commit means the code in the repository is ahead of the last published release.

The fifth is the licence mismatch worth checking. The README carries an MIT licence badge pointing at opensource.org, while GitHub shows Apache-2.0. Two different licences for the same project means one of the two records is stale, and for a platform that handles payments, model provider keys and user accounts, you need to know which text actually governs before you deploy it.

AgentX against building on an MCP client directly and against a hosted agent builder

Two comparisons make the choice clearer.

The first is against writing your own agent on top of an MCP client library. The MCP protocol and its client SDKs exist precisely so you can connect a model to tools without inventing anything. Building it directly gives you a small program: a client, a set of tool definitions, a prompt, and a loop that calls the model and executes the tools. The difference in approach is that AgentX puts a platform around that: agents you create, publish and monitor, context management with a sliding window and summarisation, a tool marketplace, scheduled tasks, RAG, long-term memory, billing and embedded widgets.

The cost is the same cost as any platform. You are adopting a runtime, a configuration file, a database and a message queue to build something that might have been fifty lines of Python or Java. If your agent is one agent with two tools, the platform is overhead.

The second comparison is against a hosted agent builder, where someone else runs the model access, the storage and the hosting. The difference in approach is where the data goes and who holds the keys. A hosted builder is faster to start and usually has a better interface, and your prompts and your tools sit on somebody else's infrastructure. AgentX runs on your host, so your agent definitions, your conversation history and your provider keys stay with you, and you can point it at whichever model provider you want, which the configuration supports for several Chinese and international providers.

The honest framing is that AgentX sits at the point where one agent becomes many. Below that point, a client library and a handful of tools is the better answer. Above it, when you need publishing, scheduling, monitoring, retrieval and billing across a set of agents, the platform is what removes the work.

Editorial conclusion

Adopt AgentX if you want to build and publish chat agents over MCP without assembling the plumbing, and you are comfortable running the whole stack yourself on one host. Do not adopt it if you need multi-agent orchestration or a knowledge graph, since the README lists both as unfinished. Verify first that the default credentials in the example configuration are changed before the service is reachable, that the JWT secret is replaced with a real one, and that the Docker socket mount the image expects is acceptable to your host, because that mount gives the container control of the Docker daemon.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. lucky-aeon/AgentX on GitHub
4. README
5. Releases