MCP Agent Server

🚀 MCP Agent Server

The MCP Agent Server is an open - source "brain" for AI employees, engineered to work in harmony with n8n and other workflow engines, offering a modular and efficient solution for AI - powered task automation.

🚀 Quick Start

1. Clone the repository:

   git clone https://github.com/yourusername/mcp-agent-server.git
   cd mcp-agent-server
   

2. If necessary, copy over your docs and memory folders.
3. Build and run using Docker Compose:

   docker-compose up --build
   

4. Access the MCP server at http://localhost:4000.

📦 Installation

1. Make sure Node.js and Docker are installed on your system.
2. Remove any comments from package.json (since JSON does not support comments).
3. Install the project dependencies by running:

   npm install
   

4. Start all services using Docker Compose:

   docker-compose up --build
   

5. The server will be accessible at http://localhost:4000.
6. For in - depth architecture and design details, refer to the /docs and /memory folders, as well as the "mcp - agent - server project plan" in MCP memory.

📁 Project Structure

• /docs — Contains design, architecture, and usage documentation.
• /memory — Holds persistent memory, logs, and knowledge.

✨ Features

AI Employee Metaphor

The MCP Agent Server allows users to "hire," "assign," "grade," and "improve" long - lasting AI agents. Each agent comes with its own memory, learning capabilities, and feedback loop.

Opinionated & Agent - Centric

Unlike general workflow automation tools, this server is focused on the "AI employee" concept. Memory, feedback, and learning are core features rather than optional add - ons.

Natural Language Interface

It accepts natural language instructions, parses them into actionable tasks, and coordinates execution through n8n or other connectors.

Proactive, Adaptive, and Personalized

Agents can suggest actions, learn from user feedback, and enhance their performance over time.

Vertical Solutions & Simplicity

It supports vertical solutions such as "AI Analyst" and "AI Admin" with pre - built skills, workflows, and feedback loops. It also offers a straightforward, non - technical user experience for small and medium - sized businesses (SMBs) and individuals.

Persistent, Agent - Centric Memory

Memory and feedback are persistent and centered around agents, enabling them to remember past actions, user preferences, and performance history.

Easy Deployment & Extensibility

The server is designed for easy deployment using Docker and Docker Compose. It is also extensible with pluggable connectors and skills and supports SaaS monetization through multi - tenant management, API key management, and billing integration.

Not Just Another Workflow Tool

The MCP Agent Server is a platform for creating, managing, and improving AI employees that can work alongside humans, learn from experience, and generate real business value.

🔐 API Authentication

All endpoints, except /health, /users/register, and /users/login, require an x - api - key header. API keys are managed on a per - user basis. See the following section for user and API key management details.

👥 User & API Key Management

Endpoints

• POST /users/register — Register a new user with an email and password.
• POST /users/login — Log in and obtain an API key.
• GET /users/me/api - keys — List your API keys.
• POST /users/me/api - keys — Create a new API key.
• DELETE /users/me/api - keys/:id — Revoke an API key.

Example PowerShell Usage

# Register a new user
Invoke-RestMethod -Uri "http://localhost:4000/users/register" -Method Post -ContentType "application/json" -Body '{"email": "user@example.com", "password": "yourpassword"}'

# Login and get API key
$login = Invoke-RestMethod -Uri "http://localhost:4000/users/login" -Method Post -ContentType "application/json" -Body '{"email": "user@example.com", "password": "yourpassword"}'
$apiKey = $login.apiKey

# List API keys
Invoke-RestMethod -Uri "http://localhost:4000/users/me/api-keys" -Method Get -Headers @{ "x-api-key" = $apiKey }

# Create a new API key
Invoke-RestMethod -Uri "http://localhost:4000/users/me/api-keys" -Method Post -Headers @{ "x-api-key" = $apiKey }

# Revoke an API key (replace 1 with the actual key id)
Invoke-RestMethod -Uri "http://localhost:4000/users/me/api-keys/1" -Method Delete -Headers @{ "x-api-key" = $apiKey }

Example curl Usage

# Register a new user
curl -X POST http://localhost:4000/users/register -H "Content-Type: application/json" -d '{"email": "user@example.com", "password": "yourpassword"}'

# Login and get API key
curl -X POST http://localhost:4000/users/login -H "Content-Type: application/json" -d '{"email": "user@example.com", "password": "yourpassword"}'

# List API keys
curl http://localhost:4000/users/me/api-keys -H "x-api-key: <your-api-key>"

# Create a new API key
curl -X POST http://localhost:4000/users/me/api-keys -H "x-api-key: <your-api-key>"

# Revoke an API key (replace 1 with the actual key id)
curl -X DELETE http://localhost:4000/users/me/api-keys/1 -H "x-api-key: <your-api-key>"

💻 Usage Examples

Agent Memory & Feedback Endpoints

• POST /agents/:id/memory — Add memory or feedback for an agent.
• GET /agents/:id/memory — List all memory and feedback for an agent.
• POST /agents/:id/trigger — Trigger an agent action (a stub for n8n integration).

Example PowerShell Usage

$headers = @{ "x-api-key" = "changeme" }

# Create an agent
Invoke-RestMethod -Uri "http://localhost:4000/agents" -Method Post -Headers $headers -ContentType "application/json" -Body '{"name": "Test Agent"}'

# Add memory/feedback
Invoke-RestMethod -Uri "http://localhost:4000/agents/1/memory" -Method Post -Headers $headers -ContentType "application/json" -Body '{"content": "Agent completed onboarding."}'

# List memory/feedback
Invoke-RestMethod -Uri "http://localhost:4000/agents/1/memory" -Method Get -Headers $headers

# Trigger agent
Invoke-RestMethod -Uri "http://localhost:4000/agents/1/trigger" -Method Post -Headers $headers

Example curl Usage

curl -X POST http://localhost:4000/agents/1/memory -H "Content-Type: application/json" -H "x-api-key: changeme" -d '{"content": "Agent completed onboarding."}'
curl http://localhost:4000/agents/1/memory -H "x-api-key: changeme"
curl -X POST http://localhost:4000/agents/1/trigger -H "x-api-key: changeme"

🔧 Technical Details

Database Migrations & Schema Management

• All database migrations are automatically applied when the container starts (refer to docker - entrypoint.sh).
• To add new models or fields:
  1. Edit prisma/schema.prisma.
  2. Run the following command locally while your Docker Postgres is running:

     npx prisma migrate dev --name <desc>
     

  3. Commit the generated migration files in prisma/migrations/ to your Git repository.
• On every deployment or container rebuild, all migrations will be applied automatically.