MCP Agent Server

MCP Agent Server

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

Quick Start

1. Clone the repo: git clone https://github.com/yourusername/mcp-agent-server.git cd mcp-agent-server

2. Copy over your docs and memory folders if needed.

3. Build and run with Docker Compose: docker-compose up --build

4. The MCP server will be available at http://localhost:4000

Getting Started

1. Ensure you have Node.js and Docker installed.
2. Remove any comments from package.json (JSON does not support comments).
3. Run npm install to install dependencies.
4. Use docker-compose up --build to start all services.
5. The server will be available at http://localhost:4000.
6. 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": "[email protected]", "password": "yourpassword"}'

# Login and get API key
$login = Invoke-RestMethod -Uri "http://localhost:4000/users/login" -Method Post -ContentType "application/json" -Body '{"email": "[email protected]", "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": "[email protected]", "password": "yourpassword"}'

# Login and get API key
curl -X POST http://localhost:4000/users/login -H "Content-Type: application/json" -d '{"email": "[email protected]", "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.