Agent and MCP Workflow Platform

An approval-gated incident workflow that gathers evidence through read-only MCP tools, executes one exact idempotent action, verifies the result, and preserves a durable audit trail.

Overview

Agentic workflows introduce risks beyond ordinary request/response APIs: external tool output may be hostile, retries can duplicate side effects, approvals can become stale, and a successful tool response may not reflect persisted state.

This project implements a deliberately bounded incident-response workflow around those failure modes. A deterministic planner discovers and calls approved read tools through the Model Context Protocol (MCP), proposes a ticket, pauses for human approval, binds that approval to a SHA-256 action digest, performs an idempotent database write, and verifies the stored result. It does not use an LLM; the focus is reliable orchestration and control boundaries.

Key Features

• MCP tool discovery and calls over JSON-RPC stdio
• Separate read-only MCP server with service-status and runbook-search tools
• Application-level allowlist independent of MCP tool discovery
• Explicit workflow state machine with step-budget enforcement
• Human approval or denial before the consequential write
• SHA-256 digest binding approval to the complete proposed action
• Stable idempotency keys that prevent duplicate ticket creation during retries
• Independent post-write verification against SQLite
• Durable runs, approvals, tickets, and ordered audit events
• Bearer-authenticated FastAPI endpoints, CLI workflows, CI, and deterministic tests

Architecture

flowchart LR
    C[API Client] --> A[FastAPI]
    A --> W[Workflow Service]
    W --> P[Deterministic Planner]
    W --> M[MCP Stdio Client]
    M --> S[Read-Only MCP Server]
    W --> D[(SQLite Store)]
    H[Human Approver] --> A
    A --> W
    W --> T[Idempotent Ticket Write]
    T --> D
    D --> V[Verification]
    V --> W

The MCP peer can supply observations but has no write authority. Ticket creation remains inside the application and cannot occur until the submitted approval hash matches the current proposal.

Workflow State Machine

created -> gathering -> awaiting_approval -> executing -> verifying -> completed
                |              |               |            |
                v              v               v            v
              failed        cancelled        failed       failed
                                                 |
                                                 `-- resume with matching approval

API

Method	Endpoint	Purpose
GET	/health	Report service liveness
GET	/v1/tools	Discover the MCP server's read tools
POST	/v1/runs	Gather evidence and create an approval-ready proposal
GET	/v1/runs/{run_id}	Read durable workflow state
GET	/v1/runs/{run_id}/events	Read the ordered audit trail
POST	/v1/runs/{run_id}/approval	Approve or deny the exact action hash
POST	/v1/runs/{run_id}/resume	Retry a failed run with an existing matching approval

All /v1 endpoints require Authorization: Bearer <AGENT_API_TOKEN>.

Tech Stack

Technology	Purpose
Python 3.12	Typed workflow, MCP client/server, and persistence logic
FastAPI / Uvicorn	Authenticated workflow API and OpenAPI documentation
Pydantic / pydantic-settings	Workflow contracts and environment configuration
SQLite	Durable runs, approvals, tickets, and audit events
JSON-RPC / MCP	Tool discovery and read-only tool invocation over stdio
Pytest / HTTPX	Workflow, MCP, persistence, and API tests
Ruff / mypy	Linting and static type checking
GitHub Actions	Automated lint, type-check, and test pipeline

How It Works

1. A client creates a run for a service and reported symptom.
2. The workflow discovers MCP tools, intersects them with its own read allowlist, and gathers bounded observations.
3. Tool output is stored as untrusted evidence and never interpreted as workflow instructions.
4. The application creates one proposed ticket action, a stable idempotency key, and a canonical SHA-256 action hash.
5. The workflow persists awaiting_approval and returns without performing a write.
6. A human submits an approval or denial for the exact hash. Changed or stale proposals are rejected with HTTP 409.
7. An approved action creates the ticket idempotently, reads it back from SQLite, and marks the run complete only after verification.
8. If execution fails after approval, /resume can retry safely because the idempotency key remains stable.

Engineering Decisions

• Discovery does not grant authority. The workflow intersects MCP results with a hard-coded read allowlist, so a peer cannot gain permission by advertising another tool.
• External observations remain data. Tool output is length-bounded, marked untrusted in the audit event, and used only as ticket evidence.
• Approval is content-addressed. Canonical JSON and SHA-256 bind approval to every field of the proposed action and prevent payload substitution.
• Writes are idempotent and verified. A unique idempotency key handles retry ambiguity, while a separate read confirms the persisted record.
• State crosses side-effect boundaries durably. Status and audit events are written before and after approval, execution, verification, failure, and completion.
• The planner is intentionally deterministic. This keeps the safety model inspectable while preserving a replaceable planner boundary for future evaluated model use.

Project Structure

agent-mcp-workflow-platform/
|-- src/agent_platform/
|   |-- workflow.py          # State machine, planner, approval, execution, verification
|   |-- tools.py             # MCP stdio client and deterministic test client
|   |-- mcp_server.py        # Local read-only MCP server
|   |-- database.py          # SQLite schema and durable workflow store
|   |-- models.py            # Typed run, action, approval, event, and tool contracts
|   |-- api.py               # Authenticated FastAPI endpoints
|   |-- settings.py          # Environment-based configuration
|   `-- cli.py               # Database, MCP discovery, demo, and server commands
|-- tests/                   # Workflow safety, retry, MCP, and API tests
|-- docs/                    # Architecture and API reference
|-- .github/workflows/ci.yml
|-- SECURITY.md
|-- CONTRIBUTING.md
`-- pyproject.toml

Getting Started

Prerequisite: Python 3.12+.

cd agent-mcp-workflow-platform
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
agent-workflow init-db
agent-workflow mcp-tools
agent-workflow serve

The API runs at http://127.0.0.1:8000; interactive documentation is available at /docs.

Example Usage

Create a run:

curl -X POST http://127.0.0.1:8000/v1/runs \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"service":"payments-api","symptom":"Elevated 5xx responses"}'

The response contains the run ID, complete proposed action, and action_hash. After reviewing them, approve that exact action:

curl -X POST http://127.0.0.1:8000/v1/runs/RUN_ID/approval \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"approved":true,"action_hash":"HASH_FROM_PROPOSAL"}'

Inspect the replayable event history:

curl http://127.0.0.1:8000/v1/runs/RUN_ID/events \
  -H "Authorization: Bearer change-me"

Testing

pytest
ruff check .
mypy

The suite verifies authentication, MCP discovery and calls, approval mismatch rejection, denial behavior, untrusted-output handling, output and step limits, duplicate-execution prevention, idempotent ticket creation, failure recovery, independent verification, and ordered audit history.

What This Project Demonstrates

• Durable agent-workflow and state-machine design
• MCP integration and JSON-RPC process boundaries
• Human-in-the-loop approval controls for consequential actions
• Idempotency, failure recovery, and postcondition verification
• Security-minded handling of untrusted tool output
• Typed API and SQLite persistence design
• Automated testing and CI-based quality enforcement

Roadmap

• Replace the development bearer token with OIDC authentication and role-based authorization
• Connect the write boundary to a real ticketing provider through an idempotent adapter
• Move execution to durable background workers with concurrency control
• Add metrics, tracing, structured operational logs, and alerting
• Evaluate an LLM planner against the deterministic baseline before granting it bounded planning responsibility

See Architecture, API Reference, and Security Policy for more detail.