MCP bridge for tamper-evident evidence around consequential AI and agent decisions.
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.
Current version:
0.1.0
Available through:
loopgrid-mcpgithub.com/loopgridio/loopgrid-mcpio.github.loopgridio/loopgrid-mcpThe official MCP Registry entry is active and currently points to the PyPI 0.1.0 package using local stdio transport.
MCP-compatible AI host/client
|
| stdio MCP
v
loopgrid-mcp
|
| LoopGrid REST API
v
LoopGrid
|
v
signed, tamper-evident
decision evidence
The v0.1 release uses local stdio transport.
No separate hosted MCP service, Railway deployment, Render deployment, AWS service, or MCP-specific database is required.
The server exposes six tools:
loopgrid.record_decisionloopgrid.record_reviewloopgrid.record_actionloopgrid.record_outcomeloopgrid.get_evidenceloopgrid.verify_evidenceLoopGrid 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.
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,<3
For local evaluation using Docker:
docker run --rm `
--platform linux/amd64 `
-p 8000:8000 `
-v loopgrid_demo_data:/app/data `
ghcr.io/cybertechsoft/loopgrid:edge
Leave the LoopGrid container running.
By default, LoopGrid MCP expects the service at:
http://127.0.0.1:8000
Create a Python virtual environment:
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
Install the published package:
pip install loopgrid-mcp
Run:
loopgrid-mcp-doctor
Expected 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: default
The local evaluation configuration does not require a service key when LoopGrid authentication is disabled.
Run:
loopgrid-mcp
Because 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.
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.exe
See:
examples/mcp-client-config.windows.json
for an example.
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-doctor
Run:
python -m pytest -ra
Run:
python .\scripts\release_check.py
Run:
python .\scripts\smoke_test.py
The 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.
Run:
python .\scripts\mcp_stdio_test.py
This 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 default
A 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.
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.py
If your installed MCP development tooling supports the Inspector cleanly, you can also try:
mcp dev .\src\loopgrid_mcp\server.py
loopgrid.record_decisionCaptures 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_reviewRecords 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_actionAppends 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_outcomeAppends 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_evidenceDownloads the portable LoopGrid evidence ZIP to:
LOOPGRID_EVIDENCE_DIR
The default directory is:
./loopgrid-evidence
Raw disclosure payloads are blocked from MCP evidence export unless explicitly enabled:
$env:LOOPGRID_MCP_ALLOW_PAYLOAD_EXPORT="true"
loopgrid.verify_evidenceAsks 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.
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.
See:
.env.example
for 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_EXPORT
The 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.
LoopGrid supports evidence workflows with different disclosure levels.
The MCP bridge follows conservative defaults:
LoopGrid core and LoopGrid MCP intentionally remain separate:
github.com/cybertechsoft/loopgrid
core LoopGrid evidence infrastructure
github.com/loopgridio/loopgrid-mcp
MCP protocol bridge
The MCP bridge communicates with the LoopGrid core runtime only over HTTP.
LoopGrid MCP 0.1.0 has been validated on Windows against the public LoopGrid 0.8.1-design-partner container.
Validation included:
The official MCP Python client successfully negotiated MCP protocol:
2026-07-28
See VALIDATION.md for the detailed release-gate record.
LoopGrid MCP is published in the official MCP Registry as:
io.github.loopgridio/loopgrid-mcp
Current Registry version:
0.1.0
Registry metadata:
Status: active
Latest: true
Package registry: PyPI
Package: loopgrid-mcp
Transport: stdio
The Registry entry is publicly discoverable and points to:
https://github.com/loopgridio/loopgrid-mcp
The corresponding Python package is published as:
loopgrid-mcp==0.1.0
The hidden ownership marker near the top of this README:
is intentionally retained because it is used for MCP Registry package ownership verification.
For future releases:
server.json to the same version;server.json with mcp-publisher;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.
Apache-2.0.
See LICENSE.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx loopgrid-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-loopgridio-loopgrid-mcp": {
"command": "uvx",
"args": [
"loopgrid-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceloopgrid-mcppypiLoopGrid MCP works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.