MCP Agent Server

This is the open-source "brain" for AI employees, designed to work with n8n and other workflow engines.

Quick Start

Clone the repo: git clone https://github.com/yourusername/mcp-agent-server.git cd mcp-agent-server
Copy over your docs and memory folders if needed.
Build and run with Docker Compose: docker-compose up --build
The MCP server will be available at http://localhost:4000

Getting Started

Ensure you have Node.js and Docker installed.
Remove any comments from package.json (JSON does not support comments).
Run npm install to install dependencies.
Use docker-compose up --build to start all services.
The server will be available at http://localhost:4000.
For architecture and design, see the /docs and /memory folders and the "mcp-agent-server project plan" in MCP memory.

Project Structure

/docs — Design, architecture, and usage documentation
/memory — Persistent memory, logs, and knowledge

Project Vision: MCP Agent Server

The mcp-agent-server is an open-source, modular "brain" for AI employees/agents, designed to work seamlessly with n8n and other workflow engines.

AI Employee Metaphor:
Enables users to "hire," "assign," "grade," and "improve" persistent AI agents, each with their own memory, learning, and feedback loop.
Opinionated & Agent-Centric:
Unlike generic workflow automation tools, the MCP agent server is opinionated and focused on the "AI employee" metaphor, making memory, feedback, and learning core features—not optional add-ons.
Natural Language Interface:
Accepts natural language instructions (not just API calls or workflow triggers), parses them into actionable tasks, and orchestrates execution via n8n or other connectors.
Proactive, Adaptive, and Personalized:
Agents can suggest actions, learn from user feedback, and improve over time.
Vertical Solutions & Simplicity:
Supports vertical solutions (e.g., "AI Analyst," "AI Admin") with prebuilt skills, workflows, and feedback loops, as well as a simple, non-technical user experience for SMBs and individuals.
Persistent, Agent-Centric Memory:
Memory and feedback are persistent and agent-centric, enabling agents to remember past actions, user preferences, and performance history.
Easy Deployment & Extensibility:
Designed for easy deployment (Docker, Docker Compose), extensibility (pluggable connectors and skills), and SaaS monetization (multi-tenant, API key management, billing integration).
Not Just Another Workflow Tool:
The MCP agent server is a platform for building, managing, and improving AI employees that work alongside humans, learn from experience, and deliver real business value.

For full design, architecture, and context, see the "mcp-agent-server project plan" entity in MCP memory and the /docs and /memory folders.

API Authentication

All endpoints (except /health, /users/register, and /users/login) require an x-api-key header. API keys are managed per user. See below for user and API key management.

User & API Key Management

Endpoints

POST /users/register — Register a new user (email, password)
POST /users/login — Login and receive 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>"

Agent Memory & Feedback Endpoints

POST /agents/:id/memory — Add memory/feedback for an agent.
GET /agents/:id/memory — List all memory/feedback for an agent.
POST /agents/:id/trigger — Trigger an agent action (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"

Database Migrations & Schema Management

All database migrations are applied automatically on container startup (see docker-entrypoint.sh).
To add new models or fields:
1. Edit prisma/schema.prisma.
2. Run npx prisma migrate dev --name <desc> locally (with your Docker Postgres running).
3. Commit the generated migration files in prisma/migrations/ to git.
On every deploy or container rebuild, all migrations will be applied automatically.

MCP Agent Server

This is the open-source "brain" for AI employees, designed to work with n8n and other workflow engines.

Quick Start

Clone the repo: git clone https://github.com/yourusername/mcp-agent-server.git cd mcp-agent-server
Copy over your docs and memory folders if needed.
Build and run with Docker Compose: docker-compose up --build
The MCP server will be available at http://localhost:4000

Getting Started

Ensure you have Node.js and Docker installed.
Remove any comments from package.json (JSON does not support comments).
Run npm install to install dependencies.
Use docker-compose up --build to start all services.
The server will be available at http://localhost:4000.
For architecture and design, see the /docs and /memory folders and the "mcp-agent-server project plan" in MCP memory.

Project Structure

/docs — Design, architecture, and usage documentation
/memory — Persistent memory, logs, and knowledge

Project Vision: MCP Agent Server

The mcp-agent-server is an open-source, modular "brain" for AI employees/agents, designed to work seamlessly with n8n and other workflow engines.

AI Employee Metaphor:
Enables users to "hire," "assign," "grade," and "improve" persistent AI agents, each with their own memory, learning, and feedback loop.
Opinionated & Agent-Centric:
Unlike generic workflow automation tools, the MCP agent server is opinionated and focused on the "AI employee" metaphor, making memory, feedback, and learning core features—not optional add-ons.
Natural Language Interface:
Accepts natural language instructions (not just API calls or workflow triggers), parses them into actionable tasks, and orchestrates execution via n8n or other connectors.
Proactive, Adaptive, and Personalized:
Agents can suggest actions, learn from user feedback, and improve over time.
Vertical Solutions & Simplicity:
Supports vertical solutions (e.g., "AI Analyst," "AI Admin") with prebuilt skills, workflows, and feedback loops, as well as a simple, non-technical user experience for SMBs and individuals.
Persistent, Agent-Centric Memory:
Memory and feedback are persistent and agent-centric, enabling agents to remember past actions, user preferences, and performance history.
Easy Deployment & Extensibility:
Designed for easy deployment (Docker, Docker Compose), extensibility (pluggable connectors and skills), and SaaS monetization (multi-tenant, API key management, billing integration).
Not Just Another Workflow Tool:
The MCP agent server is a platform for building, managing, and improving AI employees that work alongside humans, learn from experience, and deliver real business value.

For full design, architecture, and context, see the "mcp-agent-server project plan" entity in MCP memory and the /docs and /memory folders.

API Authentication

All endpoints (except /health, /users/register, and /users/login) require an x-api-key header. API keys are managed per user. See below for user and API key management.

User & API Key Management

Endpoints

POST /users/register — Register a new user (email, password)
POST /users/login — Login and receive 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>"

Agent Memory & Feedback Endpoints

POST /agents/:id/memory — Add memory/feedback for an agent.
GET /agents/:id/memory — List all memory/feedback for an agent.
POST /agents/:id/trigger — Trigger an agent action (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"

Database Migrations & Schema Management

All database migrations are applied automatically on container startup (see docker-entrypoint.sh).
To add new models or fields:
1. Edit prisma/schema.prisma.
2. Run npx prisma migrate dev --name <desc> locally (with your Docker Postgres running).
3. Commit the generated migration files in prisma/migrations/ to git.
On every deploy or container rebuild, all migrations will be applied automatically.