MCP Artifact Store

Shared artifact store for multi-agent systems — reduces context window bloat by storing large tool outputs and passing only artifact IDs between agents.

The Problem

In multi-agent pipelines, agents pass large payloads through shared graph state:

Agent A  ──────────────────────────────────────────────►  Agent B
         "Here is the full 15KB analysis: {...full JSON...}"

As pipelines grow, this bloats context windows, increases token costs, and creates hard limits on what agents can pass to each other.

The Solution

Store the payload once. Pass only a short artifact ID:

Agent A  ──────────────────────────────────────────────►  Agent B
              "artifact_id: art_8e565a6d"  (12 bytes)

Agent B fetches the full payload from the store only when it needs it. Context stays clean.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                     MCP Artifact Store                        │
├─────────────────────────┬────────────────────────────────────┤
│   React Dashboard       │   LangGraph / Claude Agents        │
│   (port 5173)           │   (any MCP client)                 │
│         │               │          │                         │
│    HTTP fetch()         │   MCP over stdio                   │
│         │               │          │                         │
│         ▼               │          ▼                         │
│   FastAPI (port 8000)   │    FastMCP Server                  │
│         │               │          │                         │
│         └───────────────┴──────────┘                         │
│                         │                                     │
│                   SQLAlchemy ORM                              │
│                         │                                     │
│              PostgreSQL in Docker (:5432)                     │
│              ┌───────────┴───────────┐                        │
│           artifacts             audit_log                     │
└──────────────────────────────────────────────────────────────┘

Two interfaces, one store:

FastAPI — HTTP endpoints consumed by the React dashboard
FastMCP — MCP tools consumed by LangGraph agents or Claude Desktop

Both call the same backend/services/storage.py functions.

Features

Write artifacts with TTL, ownership, and per-reader access control
Read artifacts by ID — access checked against allowed_readers
List artifacts — only shows what the requesting agent is allowed to see
Delete artifacts — only the original creator can delete
Audit log — every READ, WRITE, LIST, DELETE is logged atomically
React dashboard — live health indicator, context-saved metric, formatted JSON viewer
TTL enforcement — expired artifacts are invisible to all operations

Demo — Codebase Auditor Pipeline

A two-agent LangGraph pipeline that audits a Python codebase:

[Analyzer Agent]
  1. Reads .py files from a directory
  2. Sends code to GPT-4o-mini for analysis
  3. Writes findings JSON to artifact store  →  receives artifact_id
                    ↓  only artifact_id travels in graph state
[Reporter Agent]
  4. Reads findings using artifact_id
  5. Generates a structured markdown audit report

Without artifact store: full findings blob (~1.6 KB) travels between agents
With artifact store: 12-byte artifact_id travels between agents

Run the demo

# Audit the backend directory
python -m examples.codebase_auditor.main backend

# Audit any directory
python -m examples.codebase_auditor.main path/to/your/code

Sample output:

[Analyzer] Found 12 file(s)
[Analyzer] Analysis complete — findings payload: 1780 bytes
[Analyzer] ✅ Stored as artifact: art_8e565a6d
[Analyzer] → Handing off artifact_id only — 1780 bytes stay in the store

[Reporter] Received artifact_id: art_8e565a6d
[Reporter] ✅ Fetched artifact — 1780 bytes, 3 finding(s)
[Reporter] ✅ Report generated

Artifact ID : art_8e565a6d  ← stored, any authorized agent can read this

Project Structure

mcp-artifact-store/
├── main.py                        ← FastAPI entry point
├── backend/
│   ├── models/                    ← SQLAlchemy models (Artifact, AuditLog)
│   ├── routes/artifacts.py        ← HTTP endpoints
│   ├── schemas/artifacts.py       ← Pydantic request/response schemas
│   ├── services/storage.py        ← Core business logic
│   └── db/session.py              ← DB connection
├── server/
│   ├── mcp_server.py              ← FastMCP entry point
│   └── tools/artifacts.py         ← MCP tool definitions
├── examples/
│   └── codebase_auditor/          ← LangGraph demo pipeline
│       ├── main.py                ← StateGraph orchestrator
│       ├── agents/analyzer.py     ← Agent 1: analyze + write artifact
│       └── agents/reporter.py     ← Agent 2: read artifact + generate report
├── dashboard/                     ← React + Vite + Tailwind frontend
├── alembic/                       ← DB migrations
└── requirements.txt

Quick Start

Prerequisites

Python 3.11+
Docker Desktop
Node.js 18+
OpenAI API key

1. Clone and install

git clone https://github.com/Himeshxx04/mcp-artifact-store.git
cd mcp-artifact-store

python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Mac/Linux

pip install -r requirements.txt

2. Configure environment

Create a .env file in the project root:

DATABASE_URL=postgresql://postgres:password@127.0.0.1:5432/artifact_store
OPENAI_API_KEY=your-openai-api-key-here
ALLOWED_ORIGINS=http://localhost:5173

3. Start the database

docker run --name artifact-db \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=artifact_store \
  -p 5432:5432 -d postgres

4. Run migrations

alembic upgrade head

5. Start the FastAPI server

uvicorn main:app --reload
# API docs → http://127.0.0.1:8000/docs

6. Start the dashboard

cd dashboard
npm install
npm run dev
# Dashboard → http://localhost:5173

7. Run the demo

python -m examples.codebase_auditor.main backend

MCP Tools

Connect any MCP-compatible client to server/mcp_server.py:

Tool	Description
`write_artifact_tool`	Store data, get back an artifact_id
`read_artifact_tool`	Fetch data by artifact_id (access controlled)
`list_artifacts_tool`	List all artifacts visible to the requester
`delete_artifact_tool`	Delete an artifact (creator only)

Claude Desktop config:

{
  "mcpServers": {
    "artifact-store": {
      "command": "python",
      "args": ["-m", "server.mcp_server"],
      "cwd": "/path/to/mcp-artifact-store"
    }
  }
}

API Reference

Method	Endpoint	Description
`GET`	`/health`	Health check (includes DB connectivity)
`POST`	`/artifacts/`	Write a new artifact
`GET`	`/artifacts/`	List artifacts for a requester
`GET`	`/artifacts/{id}`	Read a specific artifact
`DELETE`	`/artifacts/{id}`	Delete an artifact

Full interactive docs: http://127.0.0.1:8000/docs

Tech Stack

Layer	Technology
Backend API	FastAPI
MCP Server	FastMCP
Database	PostgreSQL (Docker)
ORM + Migrations	SQLAlchemy + Alembic
Agent Framework	LangGraph
LLM	OpenAI GPT-4o-mini
Dashboard	React + Vite + Tailwind CSS

Roadmap

API key authentication for remote deployment
S3/R2 backend for large artifact storage
Deploy to Railway/Render as a hosted service
Python SDK (pip install mcp-artifact-store)
Prebuilt LangGraph node factory for one-line integration

Built by

Himesh Pandey — Final year ECE, PES University Bangalore
GitHub

Open source. Built to learn, built to ship.