# mcp-stack

Composition and operation of independent scientific MCP servers. MCP One provides
the native gateway, registry, routing and failure policy. The stack owns manifests,
scientific contracts, fixtures and deployment. Version **0.3.0**, Scientific MCP
Contract **v1**, MCP **2026-07-28**, official Python SDK **2.2.0**.

```text
Codex / MCP SDK client
          |
   MCP One :8765/mcp
          |
 mock-scientific-mcp /mcp
```

No gateway-edge, legacy-bridge or REST execution adapter is required. The clean
upstream source is pinned by full commit in config/stack.yaml and built using its
own Dockerfile and lock. Scientific libraries do not depend on the gateway.

## Start

Requires Git, Make, Python 3.12–3.14, Docker and Compose with include support.

```bash
make bootstrap
make up
make health
make tools
make test-e2e
make codex-config
```

Open **[the local monitor](http://127.0.0.1:8766)** after `make up`. It shows gateway
readiness, server/circuit states, a searchable native tool catalog and live metrics.
Light/dark themes, request/response schema modals, throughput/latency/error charts
and per-server performance indicators are included.
An optional sanitized Cordis export adds run selection, task dependencies, agent
attempts, failure routing, gates, observed usage and evidence metadata links to the
same panel. Configure `dashboard.cordis_snapshot_dir` as described in the dashboard docs.
The dashboard is read-only; disabled library manifests appear as pending integrations.
See [Dashboard](docs/dashboard.md) for configuration, security and signal semantics.

Endpoint: `http://127.0.0.1:8765/mcp`, directly served by MCP One. Expected tools:
demo.echo, demo.identity_matrix, demo.contract_error, demo.slow and demo.artifact.
These are integration fixtures. To test the actual running containers:

```bash
STACK_ENDPOINT=http://127.0.0.1:8765/mcp make test-e2e
make fault-check
make down
```

Bootstrap refuses dirty or differently pinned dependencies. An intentional pin
migration uses `python3 scripts/bootstrap.py --update-dependency` after reviewing
the candidate. It verifies the official origin, exact commit, compilation and
native import, and installs each repository's own committed dependency lock.

## Development

```bash
make validate render
make lint test test-contract test-template
make test-integration test-e2e
make logs
make restart
```

Edit config/stack.yaml and config/servers.d/*.yaml, then make render. Generated
Compose/native config is ignored; the generated JSON Schema is checked for drift.
The stack does not copy, patch or reimplement MCP One. `MCP_ONE_SOURCE` is an
explicit subprocess-test-only override for upstream development, not a production
bootstrap/build override. Final validation must use the pinned clean checkout.

[Architecture](docs/architecture.md) · [Quickstart](docs/quickstart.md) ·
[Add a server](docs/adding-a-server.md) · [Codex](docs/codex-integration.md) ·
[Compatibility](docs/protocol-compatibility.md) · [Native migration](docs/mcp-one-upgrade-path.md) ·
[Observability](docs/observability.md) · [Security](docs/security.md) ·
[Troubleshooting](docs/troubleshooting.md) · [Scientific contract](docs/contracts/scientific-result-v1.md) ·
[Validation](docs/validation.md).

[Cordis orchestration integration](docs/cordis.md) explains explicit capability
enrollment through the existing gateway without changing dependency pins.