home / mcp / mcp http agent mcp server

MCP HTTP Agent MCP Server

Provides a minimal MCP HTTP server with scratchpad memory, task orchestration, and optional subagent support.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "benhaotang-mcp-http-agent-md": {
      "url": "http://localhost:3000/mcp?apiKey=USER_API_KEY",
      "headers": {
        "HOST": "localhost",
        "PORT": "3000",
        "AI_MODEL": "gpt-5-mini",
        "BASE_PATH": "/mcp",
        "AI_API_KEY": "sk-...",
        "AI_TIMEOUT": "120",
        "AI_API_TYPE": "openai",
        "MAIN_API_KEY": "change-me",
        "USE_EXTERNAL_AI": "true",
        "AI_ATTACHMENT_TEXT_LIMIT": "120000"
      }
    }
  }
}

You run a minimal MCP (Model Context Protocol) HTTP server to manage long‑running agent projects with versioned history, a scratchpad for transient tasks, and optional subagents for focused work. It provides a streamlined way to store knowledge, track progress, and collaborate, while keeping main context lean and orchestration centralized.

How to use

Start by configuring an MCP client to connect to the server’s MCP endpoint. You can operate the server in two ways: call it over HTTP for remote access, or run a local stdio server that your client talks to directly. The HTTP endpoint exposes commands you can invoke via a standard JSON‑RPC style flow, while the local stdio option lets you launch a local process that speaks the MCP protocol.

How to install

Prerequisites: you need Node.js installed on your machine. You can also run the server in Docker if you prefer containerized deployment.

Option A — Install and run locally (Unix‑like systems) copy the installer command below and run it in your terminal. It creates a default user and sets up the server files in your home configuration.

curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install.sh | bash

Option B — Install with Docker and persist data in your home config directory.

curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install-docker.sh | bash

If you prefer to run manually, first clone the project, install dependencies, and start the server with your chosen method.

Configuration and startup details

Environment variables let you tailor the server behavior, including whether you use external AI providers, API keys, and host/port settings.

Common defaults you’ll likely customize in a .env file or in your shell are: HOST=localhost, PORT=3000, BASE_PATH=/mcp, USE_EXTERNAL_AI=true, AI_API_TYPE, AI_API_KEY, AI_MODEL, AI_TIMEOUT, AI_ATTACHMENT_TEXT_LIMIT.

For Docker usage, pass necessary variables through the container environment, for example MAIN_API_KEY and HOST. When you run with Docker, data is stored under data in your project directory unless you choose a different mount.

Project and endpoint configuration

The MCP endpoint is the primary access point for programmatic control. You can connect via HTTP in a remote setup or run a local stdio server for direct IPC.

Local HTTP and stdio configurations you can use directly in your client are shown here. The HTTP approach uses a URL, while the stdio approach runs a local command.

Security and access control

Admin access is controlled with a Main API key. Regular users are authenticated with a per‑user API key. Always protect these keys and rotate them as needed.

Notes on features and data flow

You can create and manage users, share projects with specific permissions, and upload files to projects for processing and AI summarization. Scratchpads give you ephemeral memory for a focused task set, and subagents can work on tasks with isolated context.

Available tools

list_projects

List all project names available to the authenticated user.

init_project

Create a new project with initial settings and a backup commit.

delete_project

Delete a project by name; owner only.

rename_project

Rename a project; owner only; returns updated hash.

read_agent

Read the contents of AGENTS.md for a project.

write_agent

Write or patch AGENTS.md for a project and return the updated hash.

read_progress

Read structured tasks for a project, returning tasks and a human‑friendly outline.

progress_add

Add new structured tasks to a project and create a commit.

progress_set_new_state

Update tasks by ID or by matching information; returns a new hash.

generate_task_ids

Generate unique task IDs for a user.

get_agents_md_best_practices_and_examples

Return best practices and examples from agent prompts documentation.

list_project_logs

List commit logs for a project with metadata.

revert_project

Revert to a previous commit hash within a user’s recent sequence.

list_file

List uploaded files for a project with metadata.

read_project_file

Read a chunk or pages of a project file and return text.

scratchpad_initialize

Create a new ephemeral scratchpad with initial tasks.

review_scratchpad

Review a scratchpad including common memory and task filters.

scratchpad_update_task

Update scratchpad tasks by task_id and return changes.

scratchpad_append_common_memory

Append to the scratchpad shared memory.

scratchpad_subagent

Start a subagent to work on a scratchpad task; may return in_progress with a run_id.

scratchpad_subagent_status

Check the status of an external subagent run.