loopgrid-mcp
This server is an MCP bridge that lets an AI host record, retrieve, and verify signed, tamper-evident decision evidence in LoopGrid without executing external business actions.
Record decisions (
loopgrid.record_decision): Capture AI/agent decisions with proposed actions, optional model output, context, authority, policy evaluation, privacy mode, and idempotency keys.Record human reviews (
loopgrid.record_review): Log approve/reject reviews, but this tool is disabled by default and requires explicit operator configuration.Record action evidence (
loopgrid.record_action): Append evidence that an external tool/action executed; it does not call the actual business system.Record outcome evidence (
loopgrid.record_outcome): Append observed downstream outcomes for a decision after execution evidence exists.Export evidence (
loopgrid.get_evidence): Download a portable LoopGrid evidence ZIP to a local evidence directory, with raw payloads excluded by default.Verify evidence (
loopgrid.verify_evidence): Ask the connected LoopGrid service to verify the decision's signed workspace chain.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@loopgrid-mcp Record a decision to approve the vendor payment and then verify its evidence."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
LoopGrid MCP Server — v0.1 design preview
MCP access to the LoopGrid evidence plane for consequential AI and agent decisions.
loopgrid-mcp is a thin Model Context Protocol (MCP) bridge for LoopGrid.
It lets an MCP-compatible AI host record and retrieve signed, tamper-evident decision evidence through six MCP tools while keeping the MCP layer separate from the LoopGrid core runtime.
The bridge communicates with LoopGrid exclusively through its REST API. It does not import LoopGrid internals, access the LoopGrid database directly, change signing logic, alter the evidence schema, or modify the existing LoopGrid SDK contracts.
Public release
Current version:
0.1.0Available through:
PyPI:
loopgrid-mcpGitHub:
github.com/loopgridio/loopgrid-mcpMCP Registry:
io.github.loopgridio/loopgrid-mcp
The official MCP Registry entry is active and currently points to the PyPI 0.1.0 package using local stdio transport.
Related MCP server: audit-ledger-mcp
Architecture
MCP-compatible AI host/client
|
| stdio MCP
v
loopgrid-mcp
|
| LoopGrid REST API
v
LoopGrid
|
v
signed, tamper-evident
decision evidenceThe v0.1 release uses local stdio transport.
No separate hosted MCP service, Railway deployment, Render deployment, AWS service, or MCP-specific database is required.
MCP tools
The server exposes six tools:
loopgrid.record_decisionloopgrid.record_reviewloopgrid.record_actionloopgrid.record_outcomeloopgrid.get_evidenceloopgrid.verify_evidence
Important safety boundary
LoopGrid MCP is an evidence bridge, not a business-action executor.
loopgrid.record_action does not issue a Stripe refund, modify Salesforce, change ServiceNow, or invoke another external business system. It records evidence supplied by the calling integration that an external action occurred.
Likewise, loopgrid.record_outcome records an outcome reported by the calling integration.
LoopGrid can cryptographically verify the integrity of the captured record. That verification does not independently prove that every external-world claim in the record is true and does not determine legal or regulatory compliance.
Human review receives additional protection. loopgrid.record_review is registered as an MCP tool but is disabled by default. To enable it, an operator must explicitly configure both the review flag and reviewer identity. The model cannot choose the configured reviewer identity.
Raw FULL-mode disclosure payloads are also excluded from MCP evidence export by default.
Requirements
Python 3.10+
A reachable LoopGrid v0.8.x service
For local evaluation, the public LoopGrid GHCR image is sufficient
Normal use of the Python stdio server does not require Node.js.
Node.js is only needed for optional browser-based MCP Inspector tooling.
The project uses the official MCP Python SDK v2 line:
mcp>=2,<3Quick start
1. Start LoopGrid
For local evaluation using Docker:
docker run --rm `
--platform linux/amd64 `
-p 8000:8000 `
-v loopgrid_demo_data:/app/data `
ghcr.io/cybertechsoft/loopgrid:edgeLeave the LoopGrid container running.
By default, LoopGrid MCP expects the service at:
http://127.0.0.1:80002. Install LoopGrid MCP from PyPI
Create a Python virtual environment:
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pipInstall the published package:
pip install loopgrid-mcp3. Check connectivity
Run:
loopgrid-mcp-doctorExpected shape:
[OK] LoopGrid reachable: http://127.0.0.1:8000
[OK] version: 0.8.1-design-partner
[OK] evidence profile: 3.0-draft
[OK] database: ok
[OK] signer: local_ed25519
[OK] MCP workspace: defaultThe local evaluation configuration does not require a service key when LoopGrid authentication is disabled.
4. Start the MCP server
Run:
loopgrid-mcpBecause this is a stdio MCP server, running it directly normally causes it to wait for MCP messages on standard input.
In normal use, an MCP-compatible host starts this command for you.
Generic MCP client configuration
A generic client configuration looks like:
{
"mcpServers": {
"loopgrid": {
"command": "loopgrid-mcp",
"env": {
"LOOPGRID_BASE_URL": "http://127.0.0.1:8000",
"LOOPGRID_WORKSPACE": "default"
}
}
}
}On Windows, some MCP hosts may require the full path to the executable, for example:
.venv\Scripts\loopgrid-mcp.exeSee:
examples/mcp-client-config.windows.jsonfor an example.
Install from source
For development or repository validation:
git clone https://github.com/loopgridio/loopgrid-mcp.git
cd loopgrid-mcp
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"Then verify connectivity:
loopgrid-mcp-doctorDevelopment and validation
Unit and protocol tests
Run:
python -m pytest -raRepository release check
Run:
python .\scripts\release_check.pyREST smoke test
Run:
python .\scripts\smoke_test.pyThe smoke test creates a synthetic decision, records synthetic action and outcome evidence, verifies the decision, and downloads an evidence ZIP.
It does not call a real external business system.
Real stdio MCP client test
Run:
python .\scripts\mcp_stdio_test.pyThis launches loopgrid-mcp as a child stdio server using the official MCP Python client and verifies:
connect
-> discover all 6 tools
-> record decision
-> record action evidence
-> record outcome evidence
-> service-side verification
-> evidence ZIP export
-> review tool remains disabled by defaultA successful run ends with:
[PASS] Real stdio MCP client test completed successfully.This is the recommended automated release-gate test for the MCP protocol path.
Optional MCP Inspector
The browser-based MCP Inspector can be useful for manual exploration, but it is not required to run or validate LoopGrid MCP.
The canonical automated protocol test in this repository remains:
python .\scripts\mcp_stdio_test.pyIf your installed MCP development tooling supports the Inspector cleanly, you can also try:
mcp dev .\src\loopgrid_mcp\server.pyTool behavior
loopgrid.record_decision
Captures a decision through the LoopGrid REST API.
Optional inputs can also append model evidence and evaluate an existing LoopGrid policy.
It never executes proposed_action.
Example:
{
"decision_type": "customer_refund",
"agent_id": "support-agent",
"agent_version": "1.0",
"proposed_action": {
"tool": "stripe.refunds.create",
"amount": 720,
"currency": "USD"
},
"model": {
"provider": "openai",
"name": "gpt-5"
},
"authority": {
"acting_for": "Acme",
"limit_usd": 1500,
"scope": ["refund:create"]
}
}loopgrid.record_review
Records an approve/reject review through the LoopGrid review endpoint.
This tool is disabled by default.
To enable it deliberately:
$env:LOOPGRID_MCP_ENABLE_REVIEW_TOOL="true"
$env:LOOPGRID_MCP_REVIEWER_ID="reviewer@example.com"When LoopGrid authentication is enabled, the configured service key must also have the appropriate review scope.
loopgrid.record_action
Appends tool_executed evidence to the decision record.
It does not execute the external tool.
Canonical fields such as the tool name cannot be overwritten by free-form details.
loopgrid.record_outcome
Appends outcome_observed evidence.
The calling integration is responsible for obtaining the real downstream outcome.
Canonical fields such as status and verified_against cannot be overwritten by free-form details.
loopgrid.get_evidence
Downloads the portable LoopGrid evidence ZIP to:
LOOPGRID_EVIDENCE_DIRThe default directory is:
./loopgrid-evidenceRaw disclosure payloads are blocked from MCP evidence export unless explicitly enabled:
$env:LOOPGRID_MCP_ALLOW_PAYLOAD_EXPORT="true"loopgrid.verify_evidence
Asks the connected LoopGrid service to verify the decision's signed workspace chain.
This is service-side verification.
Independent/offline verification of an exported evidence bundle should use the corresponding LoopGrid evidence-verification workflow rather than duplicating that verifier inside the MCP bridge.
Authenticated LoopGrid deployments
For local evaluation with LoopGrid authentication disabled, no service key is required.
When authentication is enabled:
$env:LOOPGRID_SERVICE_KEY="<scoped-service-key>"Use the minimum scopes required by the MCP tools you enable.
Do not use an administrative key unless administration is genuinely required.
Configuration
See:
.env.examplefor the complete supported environment-variable configuration.
Common settings include:
LOOPGRID_BASE_URL
LOOPGRID_WORKSPACE
LOOPGRID_SERVICE_KEY
LOOPGRID_EVIDENCE_DIR
LOOPGRID_MCP_TIMEOUT_SECONDS
LOOPGRID_MCP_ENABLE_REVIEW_TOOL
LOOPGRID_MCP_REVIEWER_ID
LOOPGRID_MCP_ALLOW_PAYLOAD_EXPORTThe bridge does not automatically load .env.
The MCP host should inject environment variables, or the operator should configure them in the environment that starts the server.
The LoopGrid service URL is operator configuration rather than an MCP tool argument. This prevents a model from redirecting the bridge to an arbitrary LoopGrid host through a tool call.
Privacy and disclosure defaults
LoopGrid supports evidence workflows with different disclosure levels.
The MCP bridge follows conservative defaults:
human review recording is disabled unless explicitly enabled;
reviewer identity is operator-configured;
raw FULL-mode payload export is disabled by default;
authenticated deployments should use scoped service keys;
external business actions are never executed by the MCP bridge itself.
Repository boundary
LoopGrid core and LoopGrid MCP intentionally remain separate:
github.com/cybertechsoft/loopgrid
core LoopGrid evidence infrastructure
github.com/loopgridio/loopgrid-mcp
MCP protocol bridgeThe MCP bridge communicates with the LoopGrid core runtime only over HTTP.
Validation status
LoopGrid MCP 0.1.0 has been validated on Windows against the public LoopGrid 0.8.1-design-partner container.
Validation included:
clean repository installation;
Python unit/protocol tests;
REST connectivity;
synthetic decision creation;
action evidence recording;
outcome evidence recording;
service-side cryptographic verification;
portable evidence ZIP export;
official MCP Python client stdio negotiation;
discovery of all six MCP tools;
confirmation that the review tool remains disabled by default.
The official MCP Python client successfully negotiated MCP protocol:
2026-07-28See VALIDATION.md for the detailed release-gate record.
MCP Registry
LoopGrid MCP is published in the official MCP Registry as:
io.github.loopgridio/loopgrid-mcpCurrent Registry version:
0.1.0Registry metadata:
Status: active
Latest: true
Package registry: PyPI
Package: loopgrid-mcp
Transport: stdioThe Registry entry is publicly discoverable and points to:
https://github.com/loopgridio/loopgrid-mcpThe corresponding Python package is published as:
loopgrid-mcp==0.1.0The hidden ownership marker near the top of this README:
<!-- mcp-name: io.github.loopgridio/loopgrid-mcp -->is intentionally retained because it is used for MCP Registry package ownership verification.
For future releases:
update the package version;
update
server.jsonto the same version;run the repository validation suite;
publish the new version to PyPI;
confirm the package is publicly installable;
validate
server.jsonwithmcp-publisher;publish the corresponding version to the MCP Registry.
Release posture
0.1.0 is a design preview, not Production GA.
It is intended to validate a clean MCP integration path for LoopGrid v0.8.x without changing LoopGrid's signing, hash-chain, evidence-bundle, verification, or SDK contracts.
LoopGrid provides signed, tamper-evident evidence and append-only decision history. Verification confirms the integrity of the captured record; it does not determine legal compliance.
License
Apache-2.0.
See LICENSE.
Available Tools
6 toolsloopgrid.get_evidenceA
Download a portable LoopGrid evidence ZIP for a decision to the configured local evidence directory. Raw disclosure payloads are excluded by default.
Inputs: decision_id (required), include_payloads. Returns: object
loopgrid.record_actionC
Record evidence that an external tool/action executed. This does NOT call Stripe, Salesforce, ServiceNow, or any other business system; it only records execution evidence supplied by the integration.
Inputs: tool (required), decision_id (required), details, actor_id, +1 more. Returns: object
loopgrid.record_decisionA
Capture a consequential AI/agent decision in LoopGrid. Optionally record model output and evaluate an existing LoopGrid policy. This records evidence only and does not execute the proposed action.
Inputs: decision_type (required), proposed_action (required), model, context, +10 more. Returns: object
loopgrid.record_outcomeA
Record an observed downstream outcome for a decision after execution evidence exists. The integration is responsible for obtaining the outcome from the real downstream system.
Inputs: status (required), decision_id (required), verified_against (required), details, +2 more. Returns: object
loopgrid.record_reviewA
Record a human approve/reject review in LoopGrid. Disabled by default. The operator must explicitly enable it and configure reviewer identity; the MCP host should require human confirmation.
Inputs: action (required), decision_id (required), reason. Returns: object
loopgrid.verify_evidenceB
Ask the connected LoopGrid service to verify the decision's signed workspace chain. For independent offline verification of an exported ZIP, use the standalone LoopGrid verifier.
Inputs: decision_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct stage in the evidence lifecycle: decision, review, action, outcome, retrieval, and verification. The descriptions clearly separate recording evidence from executing actions, so there is no real ambiguity between tools.
All tool names follow a consistent snake_case verb_noun pattern with a uniform loopgrid. prefix. The record_* tools form a clear family, while get_evidence and verify_evidence follow the same predictable convention.
Six tools is well-scoped for a focused governance/evidence server. Each tool earns its place and covers a necessary function without redundancy or bloat.
The tool set covers the full evidentiary workflow: capture decisions, record reviews, log actions, record outcomes, retrieve portable evidence, and verify integrity. There are no obvious dead ends for the stated purpose.
Maintenance
Related MCP Connectors
Append-only decisions with provenance, supersession, retrieval, and audited MCP actions.
Tamper-evident proof creation and verification for AI agents via MCP, A2A, and REST.
Evidence-readiness MCP server: validate, audit, and score briefs, memos, and evidence packs.
Remote MCP for MCP consent scope receipt, structured receipts, audit logs, and reviewer-ready eviden
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables preserving, querying, and managing engineering decisions with reasoning and evidence through CLI, HTTP API, and MCP tools.16-
- AlicenseAqualityDmaintenanceTamper-evident audit logging for AI decisions. Three tools (record_decision, verify_decision, list_decisions) write to a regulator-grade ledger built on AWS S3 Object Lock with 7-year retention. Designed for EU AI Act Article 12 and FCA SS1/23 evidence requirements. Try zero-config: npx audit-ledger-mcp boots in sandbox mode against a public hosted tenant.353 npm1Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEvidence-first delivery audit MCP server that evaluates task requirements against delivery evidence and returns a reproducible pass/needs_review/fail decision with a deterministic receipt.MIT
- AlicenseAqualityBmaintenanceFree seven-tool proof loop for MCP agents: scoped sessions, bounded authorization, typed outcomes, evidence-bound claims, and tamper-evident local closure. Upgrade to Complete Local for durable memory, recovery, signed traces, release verification, and multi-agent workflows.7Apache 2.0