Overview

The Dispatch Agent MCP Server is a lightweight orchestration layer that exposes a set of filesystem-focused ReAct sub-agents as MCP-compatible tools. It lets language models and other automated agents call specialized filesystem operations (read, write, list, search, etc.) through a single, secure HTTP API. By isolating each operation into a focused sub-agent and exposing a consistent tool interface, the server makes filesystem interactions faster, safer, and easier to integrate into LLM-driven workflows.

Typical deployments are used where an LLM needs reliable, auditable, and permissioned access to project files or document stores. The protocol-oriented design (MCP — Model Context Protocol) provides discoverable tools, structured input/output, and streaming support for large results so that models can compose operations using ReAct-style reasoning with concrete side-effects.

Features

MCP-compatible tool discovery and invocation API
Focused filesystem sub-agents: read, write, list, search, delete, tail, stat
Permission and authentication support (API token)
Streaming responses for large reads (file tails, big files)
Concurrency control and configurable worker limits
Pluggable storage root and sandboxing to prevent directory escape
Structured JSON inputs/outputs for reliable LLM parsing
Logging and audit trail for each tool invocation

Installation / Configuration

Quick start (clone and run with Docker)

git clone https://github.com/abhinav-mangla/dispatch-agent.git
cd dispatch-agent
docker build -t dispatch-agent .
docker run -e AUTH_TOKEN="your-token" -e DATA_ROOT="/data" -p 8080:8080 dispatch-agent

Environment variables

# Port the server listens on
PORT=8080

# Directory used as the root/sandbox for filesystem operations
DATA_ROOT=/srv/dispatch-data

# Token for simple HTTP bearer auth
AUTH_TOKEN=replace-with-secret

# Max concurrent workers for sub-agents
MAX_WORKERS=8

# Log level: debug, info, warn, error
LOG_LEVEL=info

Example Docker Compose (docker-compose.yml)

version: "3.8"
services:
  dispatch-agent:
    image: dispatch-agent:latest
    build: .
    ports:
      - "8080:8080"
    environment:
      - AUTH_TOKEN=${AUTH_TOKEN}
      - DATA_ROOT=/data
      - LOG_LEVEL=info
    volumes:
      - ./data:/data

Configuration file (optional YAML)

server:
  port: 8080
  data_root: /data
  max_workers: 8
auth:
  token: "your-token"
logging:
  level: info

Available Tools / Resources

The server exposes a set of filesystem tools. Each tool accepts a JSON payload and returns structured JSON (or a streaming response for large outputs).

Tool	Purpose	Key input fields	Output
read_file	Read entire file contents	path, encoding, max_bytes	{ path, content, size }
write_file	Write text or bytes to file	path, content, mode (append/overwrite)	{ path, bytes_written }
list_dir	List directory entries	path, recursive, max_entries	{ path, entries: [{name,type,size,mtime}] }
search_files	Search files by regex or keyword	path, pattern, max_results	{ results: [{path, snippet, score}] }
delete_file	Remove file or empty dir	path, recursive	{ path, deleted: true }
tail_file	Stream appended lines from a file	path, since, follow	streaming lines
file_stat	Return metadata for a path	path	{ path, size, is_dir, mtime }

Example tool discovery (GET tools)

curl -H "Authorization: Bearer $AUTH_TOKEN" http://localhost:8080/mcp/v1/tools

Example execute (POST /mcp/v1/execute)

curl -X POST http://localhost:8080/mcp/v1/execute \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "read_file",
    "input": { "path": "notes/project.md", "encoding": "utf-8" }
  }'

Response (example)

{
  "tool": "read_file",
  "output": {
    "path": "notes/project.md",
    "content": "# Project\nThis is the file content...",
    "size": 2345
  },
  "meta": { "duration_ms": 23, "worker_id": "worker-3" }
}

Use Cases

LLM-powered code assistant
- The model uses read_file to inspect project files and write_file to update README or configuration. list_dir helps it discover repository structure while search_files locates relevant code patterns.
Document ingestion pipeline
- Use read_file and file_stat to batch-read documents into an indexing pipeline. Tail_file can stream logs or incoming files for near-real-time ingestion.
Remote file manager / dashboard
- A web UI calls list_dir and file_stat to show a file tree and uses delete_file and write_file (with permission checks) to manage files remotely.
Test orchestration for CI
- Tests or agents request files, patch configuration, and run isolated operations in a sandboxed DATA_ROOT. The audit trail helps trace which automated action created a change.

Security and Best Practices

Always run the agent with DATA_ROOT set to a sandbox directory to avoid accidental access to the host filesystem.
Use a strong AUTH_TOKEN or integrate with an external authentication proxy.
Limit MAX_WORKERS and monitor logs to detect abusive access patterns.
Enable audit logging if you require traceability for automated edits performed by LLMs.

For source, examples, and contributions, see the project repository: https://github.com/abhinav-mangla/dispatch-agent.

Dispatch Agent MCP Server for ReAct Filesystem Sub-Agents