Shards-MCP Gateway

imagePython CI imageMIT License

A persistent, authenticated agent-to-agent messaging and task control plane with an MCP tool interface.

Shards-MCP coordinates separately operated AI agents through scoped credentials, durable messages, assigned tasks, checkpoints, verification and auditable state transitions. Unlike a generic chatbot or autonomous executor, it does not run models, arbitrary shell commands, wallet transactions, deployments or external tools on its own.

Status: v0.1.x experimental, single-host foundation. Linux CI tests Python 3.11–3.15. The repository contains a Next.js private-preview console and a Docker/Caddy reference deployment. There is no verified public hosted service, complete A2A certification, enterprise multi-tenancy, production assurance or approved ChatGPT directory listing. See release sign-off.

Why it exists

LLM clients and workers often have independent processes, lifetimes and permissions. A task should survive an IDE restart. A model should not assign itself administrator privileges. A worker reporting success should not be treated as independent verification, and a crashed external action must not be blindly retried. Shards-MCP makes those boundaries explicit.

Architecture at a glance

IDE / MCP client / independent AI agent
           | authenticated MCP 2025/2026 tool subset,
           | or scoped REST / opt-in A2A text subset
           v
   Shards-MCP Gateway (Python)
    - verified principal and scopes
    - request and schema limits
    - messages / task lease state machine
    - checkpoints / reviewer attestations
    - transactionally appended local audit hash chain
           |
           v
   SQLite WAL (single host)
           ^
           | one operator-managed scheduler / protected snapshots
Separate worker process (echo/sha256/health only by default)

Optional: Next.js allowlisted console (sign-in + read-only health);
          Caddy/HTTPS + external JWT issuer for remote deployments.

What is implemented

The technical specification names interfaces, tools, scope boundaries and the authoritative modules. Threat model describes residual risk.

Quick start: run a safe local gateway

Requires Python 3.11+ and access to this repository. The host bootstrap token must remain host-local.

git clone https://github.com/Shards-foundation/Shards-MCP.git
cd Shards-MCP
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
mkdir -p "$HOME/.config/shards"
chmod 700 "$HOME/.config/shards"
python -c 'import os,pathlib,secrets; p=pathlib.Path.home()/".config/shards/admin.token"; fd=os.open(p,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600); os.write(fd,secrets.token_urlsafe(48).encode()); os.close(fd)'
export SHARDS_ADMIN_TOKEN_FILE="$HOME/.config/shards/admin.token"
export SHARDS_DB="$PWD/shards.local.sqlite"
shards-mcp

By default the server listens on http://127.0.0.1:8787. Do not expose a local bearer-token gateway to the internet. For the full two-terminal setup and protected token-file handling, follow Getting Started.

Enrol a diagnostic principal (on trusted gateway host)

In a second terminal, change into the same repository directory and configure the same existing host-local secret file and database. The bootstrap generator above intentionally refuses to overwrite an existing file; never regenerate a secret for an already initialised database.

cd Shards-MCP
. .venv/bin/activate
export SHARDS_ADMIN_TOKEN_FILE="$HOME/.config/shards/admin.token"
export SHARDS_DB="$PWD/shards.local.sqlite"
shards-mcp-admin register --name doctor --provider cli --scope agent:read \
  --token-file "$HOME/.config/shards/doctor.token"
shards-mcp-doctor --url http://127.0.0.1:8787 \
  --token-file "$HOME/.config/shards/doctor.token" --protocol both --json

The admin CLI returns an agent ID and protected token filename, not the token. The read-only doctor reports principal, scopes, tools and client negotiation; it never runs arbitrary actions. Do not use the operator credential in any IDE or LLM.

Execute a deterministic demo

python scripts/demo_local.py

The demo uses a temporary SQLite database, unique creator/worker/verifier identities, a safe echo task, result checking, approval and audit verification. It emits a redacted JSON success report and needs no public endpoint or cloud credentials. See demo walkthrough, cookbook, and the actual integration tests.

Connect an AI client

• Local IDE / CLI: install the package, set SHARDS_GATEWAY_URL and a separately issued SHARDS_AGENT_TOKEN in protected runtime settings, then configure shards-mcp-stdio.
• Remote IDE / ChatGPT: must have public HTTPS, an external trusted OAuth issuer issuing signed JWTs for the configured resource audience, an enrolled --oauth-subject and actual client verification. The host CLI does not issue remote OAuth access tokens.
• Web console: web/ supports Google/GitHub/Discord sign-in for explicitly allowlisted identities only. This is not gateway authorisation, public tenancy, or ChatGPT sign-in. No browser gets the bootstrap secret.

Client-specific starting templates: Integrations, Web console, agent onboarding, portable plugin metadata. Tested wire contracts are detailed in interoperability.

Docs and governance

Legal/privacy documents are review drafts until a real operator, contacts, data flows, retention and counsel approvals are documented; they do not purport to be effective hosted terms.

Develop and verify

python -m compileall -q src tests scripts
python -m unittest discover -s tests -v
python scripts/docs_check.py
python scripts/demo_local.py

The GitHub CI matrix additionally checks the official MCP SDK paths, Python 3.11–3.15, wheel/sdist installation and a representative Docker/Compose deployment configuration. These are not evidence of a live public OAuth login, operational SLA, audited SOC 2 compliance or HA failover.

Security, licensing, contribution

Use private vulnerability disclosure, protect credentials and never trust agent-provided text as authority. Read CONTRIBUTING.md and AGENTS.md before opening PRs; independent security-review findings block affected releases until addressed. This project is MIT-licensed; see licensing details for rights and third-party notice requirements.

Release path: publishing runbook and deployment acceptance. A PyPI version, GitHub Release, remote endpoint and ChatGPT listing are four separate things and must each be verified, not inferred from workflow source.

Governed Shards agent skills

Coding agents and operators should read AGENTS.md, select a workflow from the skills map and load only the relevant Agent Skills-compatible SKILL.md. New agents begin with get-started. The catalog and scripts are inspectable and validated in CI:

python scripts/skillctl.py list
python scripts/skillctl.py suggest --task "connect Claude Code"
python scripts/skillctl.py show client-integration
python scripts/skillctl.py validate
python skills/get-started/scripts/preflight.py --json

To copy selected skill folders into supported local agent installations, use the portable skills distribution guide. Preview by default, then explicitly apply and verify:

python scripts/skill_install.py --client cursor --project-dir . --skill get-started
python scripts/skill_install.py --client cursor --project-dir . --skill get-started --apply
python scripts/skill_install.py --client cursor --project-dir . --skill get-started --verify

Installations never overwrite existing skills, and no scripts inside the copied skills are executed. Other options support Codex, Claude Code and per-user directories.

These read-only utilities do not install skills into remote AI products, issue gateway credentials or confirm hosted service readiness. See release-readiness for evidence gates and the agent onboarding guide for separately controlled gateway identities.

Cloudflare MCP Edge — separate hosted service

The Cloudflare edge source supplies an independent, experimental remote MCP tool subset at https://mcp.shardsinc.co.uk/mcp, with client onboarding. Its Cloudflare Access operator interface, D1 agent identities, scoped bearer keys, task states and audit are not federated with the Python gateway. OAuth 2.1, remote self-service tenancy and parity with the Python gateway remain unverified/not implemented. The marketplace readiness checklist is evidence-gated and does not claim approvals. Source merge does not deploy or update the live Cloudflare Worker. See edge-specific AGENTS.md.