Quick Start

Quick Start

Get MCPShield running in 5 minutes.

1. Install the Agent

pip install mcpshield-agent

2. Start the Backend & Frontend

The quickest way is Docker Compose:

git clone https://github.com/RunTimeAdmin/MCPShield.git
cd MCPShield
export JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")
docker-compose up -d

Or run manually — see Installation for step-by-step instructions.

3. Register an Account

1. Open http://localhost:3000
2. Click Register
3. Enter your email, password, and organization name
4. Click Create Account — you're now in the dashboard

4. Create an Agent

1. Go to Settings → Agents
2. Click Create Agent, give it a name (e.g. "My Laptop")
3. Copy the API key — it starts with mcp_sk_ and is shown only once

Important: The API key is stored as a SHA-256 hash. If you lose it, delete the agent and create a new one.

5. Configure the Agent

mcpshield configure --api-key mcp_sk_YOUR_KEY --api-url http://localhost:8000

Expected output:

Testing connection to http://localhost:8000...
Connected successfully!
Config saved.

6. Run Your First Scan

mcpshield scan

Expected output:

Scanning for MCP servers...
Found 3 servers:
  - filesystem (stdio)  MEDIUM  35
  - postgres   (stdio)  HIGH    72
  - github     (stdio)  LOW     18

Reported to MCPShield dashboard.

7. View Results

Go to Dashboard → Servers to see all discovered MCP servers with risk scores and details.

---

Common Issues

"JWT_SECRET environment variable is required" Set JWT_SECRET before starting the backend. See Installation for instructions.

"Invalid API key format" API keys must start with mcp_sk_. Make sure you copied the full key from step 4.

"Connection refused" when configuring agent The backend isn't running or the URL is wrong. Check with: curl http://localhost:8000/health

---

What's Next?

• Agent-Usage — All agent commands and options
• Risk-Scoring — How scores are calculated
• API-Reference — Integrate MCPShield into your own tooling