MCP Agent Toolkit

An MCP (Model Context Protocol) server that exposes production agent-kernel tools — blackboard shared state, SCAR failure memory, and LLM response cache — as standard MCP tools any Claude or GPT agent can call.

For project walkthroughs, architecture flowcharts, and system context, visit the live landing page: my-portfolio-github-io-beta-five.vercel.app/projects/mcp-agent-toolkit.html

What it does

Connects the three core reliability patterns from 18 months of building production multi-agent systems into a single MCP server:

Related MCP server: memhippo

Part of The Machine OS

This repo is a spoke of The Machine OS: it backs the ~~scar-memory and ~~blackboard connectors that supercharge the /debug, /incident-response, and /agent-design skills.

Prerequisite: Node.js 22.5+ (node:sqlite is built in from 22.5; on recent versions it runs without a flag and just prints an experimental warning to stderr, which does not affect the stdio protocol).

Option A — install via the Machine OS plugin (recommended for Claude Code)

/plugin marketplace add shubham0086/the-machine-os
/plugin install ai-engineering-tools@machine-os
/reload-plugins

This launches the server for you (as the agent-memory MCP server) — no manual config.

Option B — point any MCP client at it directly

Works in Claude Desktop, Cursor, Windsurf, Cline, Zed, or any mcp.json client. No clone needed; npx fetches and runs it:

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "github:shubham0086/mcp-agent-toolkit"],
      "env": { "MCP_AGENT_TOOLKIT_DATA_DIR": "/abs/path/to/persist" }
    }
  }
}

MCP_AGENT_TOOLKIT_DATA_DIR is optional but recommended under npx: it points the SQLite store at a stable path so blackboard state and SCAR memory survive across runs (the npx package dir is ephemeral). Omit it and storage falls back to the package's own data/ dir.

Local dev

npm install
npm start    # runs the stdio server from this checkout

Tool reference

Blackboard

blackboard_write(run_id, agent, key, value)  — persist an artifact
blackboard_read(run_id, agent, key)          — read latest artifact
blackboard_list(run_id, agent)               — list all keys for an agent

Agents communicate through the blackboard, never directly. The Coder writes code. The Auditor reads code. If either fails and retries, the other's work is still in SQLite.

SCAR Memory

scar_lookup(agent, error_type, context?)  — retrieve known resolution
scar_record(agent, error_type, resolution, context?)  — store a new resolution

When an agent hits JSONDecodeError and you fixed it with json_repair(), record it. Next time any agent hits the same error in the same context, scar_lookup returns the fix before the retry loop starts.

Response Cache

cache_get(messages, model)                    — check cache before calling LLM
cache_set(messages, model, response, provider)  — store response after call

SHA-256 hashes the messages + model into a cache key. Identical requests never hit the API twice.

Tests

npm test

13 tests covering blackboard isolation, SCAR round-trips, and cache hit/miss behavior.

Stack

• MCP SDK (@modelcontextprotocol/sdk) — the official Anthropic MCP server library

• node:sqlite — Node.js 22 built-in synchronous SQLite, zero native compilation

• stdio transport — standard MCP pattern, works with any client

Related repos

• agent-scars — standalone SCAR pattern

• agent-recall — solution memory

• equilibrium — the AgentKernel these patterns came from