Installation

Installation

Agent (PyPI — Recommended)

The agent is published on PyPI. Install it anywhere Python 3.11+ is available:

pip install mcpshield-agent

Then configure and scan:

mcpshield configure --api-key YOUR_KEY --api-url https://your-instance
mcpshield scan

---

Self-Hosting the Full Platform

To run the backend and dashboard yourself you need:

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+ (or SQLite for local development)

Option A — Docker Compose (Recommended)

git clone https://github.com/RunTimeAdmin/MCPShield.git
cd MCPShield

# Generate a JWT secret (required — backend will not start without it)
export JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")
# PowerShell: $env:JWT_SECRET = python -c "import secrets; print(secrets.token_hex(32))"

docker-compose up -d

Services start at:

• Frontend → http://localhost:3000
• Backend API → http://localhost:8000
• API docs → http://localhost:8000/docs

Option B — Manual Setup

Backend:

cd backend
python -m venv venv
source venv/bin/activate      # macOS/Linux
.\venv\Scripts\activate       # Windows
pip install -r requirements.txt
export JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")
uvicorn app.main:app --reload

Frontend:

cd frontend
npm install
npm run dev

---

Environment Variables

Backend (backend/.env)

Variable	Default	Description
JWT_SECRET	Required	JWT signing key — generate with python -c "import secrets; print(secrets.token_hex(32))"
DATABASE_URL	sqlite:///./mcpshield.db	Database connection string
ACCESS_TOKEN_EXPIRE_MINUTES	30	JWT access token lifetime
ALLOWED_ORIGINS	http://localhost:3000	CORS allowed origins

Frontend (frontend/.env.local)

Variable	Default	Description
NEXT_PUBLIC_API_URL	http://localhost:8000	Backend API URL

---

Next Steps

1. Open http://localhost:3000 and register an account
2. Go to Settings → Agents and create an agent — copy the API key
3. mcpshield configure --api-key mcp_sk_YOUR_KEY --api-url http://localhost:8000
4. mcpshield scan
5. View results in Dashboard → Servers