Quickstart Guide

Get a fully governed Model Context Protocol (MCP) gateway environment running locally in less than 5 minutes. This guide installs the local P1 Docker Compose stack, deploys PostgreSQL and Redis, configurations Aegis, and boots a mock downstream server.

Pre-MVP Milestone

Aegis is currently in pre-MVP status. This guide shows how to stand up the sandbox environment corresponding to the Phase 1 (P1) Single-Node Docker Compose design.

Prerequisites

Before running the gateway, ensure you have the following installed on your machine:

  • Docker Engine & Docker Compose (v2.x or later)
  • Git (to clone specifications)
  • .NET 10 SDK (required only if building the source files; not needed for compose sandbox)
  • A tool to dispatch HTTP/gRPC requests (e.g., curl, Postman, or `grpcurl`)

1. Scaffolding

Clone the gateway repository to your local workspace and navigate to the project directory:

git clone https://github.com/Nshai/MCP-Gateway.git
cd MCP-Gateway
mkdir -p config policies

2. Configuration

Aegis leverages a simple layered configuration model. Create a file named config/gateway.yaml to set up the Phase 1 in-process defaults and PostgreSQL + Redis adapters:

gateway:
  role: all
  tenancy: single
adapters:
  state: postgres
  objects: filesystem
  bus: inproc
  secrets: env
  audit: postgres
policy:
  evaluator: cedar
  failMode: closed
identity:
  issuers: [ "https://mock-identity-provider" ]

3. Compose Setup

We declare the gateway along with its core supporting datastores. Create a docker-compose.yml file in your directory root:

version: "3.8"
services:
  gateway:
    image: aegis-mcp-gateway:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config:/app/config
      - ./policies:/app/policies
    environment:
      - ConnectionString=Host=postgres;Database=aegis;Username=aegis;Password=secure
      - Redis=redis:6379
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_DB=aegis
      - POSTGRES_USER=aegis
      - POSTGRES_PASSWORD=secure
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

4. Running Aegis

Spin up the environment in the background. The database schemas are provisioned and migrated automatically on startup:

docker compose up -d
docker compose ps

5. Register Server

Register a downstream MCP server. We supply a JSON payload specifying metadata, target transports, schemas, and credentials to /api/v1/servers:

curl -X POST http://localhost:8080/api/v1/servers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mock-dev-token" \
  -d '{
    "id": "sql-prod",
    "name": "Production Database Server",
    "transport": "HTTP",
    "endpoint": "http://sql-server-internal:8081/mcp",
    "riskLevel": "High",
    "pinnedSchemaHash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }'

6. Verify Audits

Aegis intercepts every operation and pushes records into the append-only audit sink. Execute a query and inspect the audit table in PostgreSQL to verify that operations are recorded:

docker compose exec postgres psql -U aegis -d aegis -c "SELECT timestamp, user, server, primitive, decision FROM audit_records LIMIT 5;"

Next Steps

Now that you have a running development gateway, read deeper into specific operational areas: