Memory Cloud Protocol (MCP) Server

A server for agent memory persistence and coordination, designed to work with AI agents like Cursor and other tools.

Features

- Persists memory records for Supabase projects, including UUIDs, table names, RLS states, and keys
- Stores API tokens, project states, and function deployment metadata
- Logs agent tasks and output
- Provides automatic lookup of known entities to prevent repetitive errors
- Exposes REST endpoints for memory management and agent coordination

Setup

1. Clone the repository
2. Install dependencies

cd mcp-server

npm install

cp .env.example .env

npm run dev # for development

npm start   # for production

Testing

We provide test scripts for both local and Railway deployments:

- Local testing:

./test-local.sh

- Railway testing:

./test-railway.sh

The tests verify the basic health endpoints and authentication.

API Endpoints

- POST /api/v1/memory/save: Save memory records
- GET /api/v1/memory/:project: Fetch last known memory for a project
- POST /api/v1/log/error: Save function or agent error
- POST /api/v1/dispatch: Instruct next agent action
- GET /api/v1/health: Authenticated health check
- GET /health: Public health check (no authentication required)

Database Setup

The MCP server uses Supabase/PostgreSQL as its database. You need to create the following tables in your Supabase project:

-- Create extension for UUID generation
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-- Create memory table

CREATE TABLE IF NOT EXISTS memory (

  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),

  project_id TEXT NOT NULL,

  key TEXT NOT NULL,

  value JSONB NOT NULL,

  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()

);
-- Create logs table

CREATE TABLE IF NOT EXISTS logs (

  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),

  project_id TEXT,

  agent_id TEXT,

  level TEXT NOT NULL,

  message TEXT NOT NULL,

  metadata JSONB,

  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()

);
-- Create dispatches table

CREATE TABLE IF NOT EXISTS dispatches (

  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),

  project_id TEXT NOT NULL,

  agent_id TEXT NOT NULL,

  action TEXT NOT NULL,

  parameters JSONB,

  status TEXT NOT NULL DEFAULT 'pending',

  result JSONB,

  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  completed_at TIMESTAMPTZ

);
-- Create indexes for faster lookups

CREATE INDEX IF NOT EXISTS memory_project_id_idx ON memory(project_id);

CREATE INDEX IF NOT EXISTS memory_key_idx ON memory(key);

CREATE INDEX IF NOT EXISTS logs_project_id_idx ON logs(project_id);

CREATE INDEX IF NOT EXISTS logs_agent_id_idx ON logs(agent_id);

CREATE INDEX IF NOT EXISTS dispatches_project_id_idx ON dispatches(project_id);

CREATE INDEX IF NOT EXISTS dispatches_agent_id_idx ON dispatches(agent_id);

CREATE INDEX IF NOT EXISTS dispatches_status_idx ON dispatches(status);

Deployment to Railway

This server is designed to be deployed on Railway.app. Follow these steps:

1. Push your code to a Git repository
2. Create a new project on Railway.app
3. Connect your Git repository
4. Add the required environment variables from .env under the "Variables" tab
5. Deploy your project

Railway will automatically build and deploy the project using the included Dockerfile and railway.json configuration.

Environment Variables for Railway

Make sure to set all the environment variables from .env in your Railway project:

- PORT (Railway sets this automatically)
- NODE_ENV=production
- SUPABASE_URL
- SUPABASE_KEY
- SUPABASE_SERVICE_KEY
- SUPABASE_DB_URL
- MCP_API_KEY
- MCP_API_URL (Your public Railway URL)

Docker

The server can be run in Docker locally:

```bash