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.0

Available through:

• PyPI: loopgrid-mcp
• GitHub: github.com/loopgridio/loopgrid-mcp
• MCP 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.

Architecture

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.

MCP tools

The server exposes six tools:

• loopgrid.record_decision
• loopgrid.record_review
• loopgrid.record_action
• loopgrid.record_outcome
• loopgrid.get_evidence
• loopgrid.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,<3

Quick 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:edge

Leave the LoopGrid container running.

By default, LoopGrid MCP expects the service at:

http://127.0.0.1:8000

2. 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 pip

Install the published package:

pip install loopgrid-mcp

3. Check connectivity

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.

4. Start the MCP server

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.

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.exe

See:

examples/mcp-client-config.windows.json

for 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-doctor

Development and validation

Unit and protocol tests

Run:

python -m pytest -ra

Repository release check

Run:

python .\scripts\release_check.py

REST smoke test

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.

Real stdio MCP client test

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.

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.py

If your installed MCP development tooling supports the Inspector cleanly, you can also try:

mcp dev .\src\loopgrid_mcp\server.py

Tool 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_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_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.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.

Privacy and disclosure defaults