Quick Start

Quick Start

Get MCPShield running in 5 minutes.

1. Clone & Start Backend

git clone https://github.com/RunTimeAdmin/MCPShield.git
cd MCPShield/backend
python -m venv venv
source venv/bin/activate  # Windows: .\venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

2. Start Frontend

cd ../frontend
npm install
npm run dev

3. Register Account

1. Open http://localhost:3000
2. Click Register
3. Enter email, password, organization name
4. Click Create Account

Expected output:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "organization_name": "My Org"
  }
}

4. Create Agent

1. Go to Dashboard → Agents
2. Click Create Agent
3. Copy the API key (starts with mcp_sk_)

Save the API key immediately! It is shown only once and stored as a SHA-256 hash in the database. If lost, use the regenerate endpoint.

5. Install & Configure Agent

cd ../agent
pip install -e .
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 to <platform-specific-path>

6. Run First Scan

mcpshield scan

Expected output:

Scanning for MCP servers...
Found 3 servers:
  - filesystem (stdio)
  - github (stdio)
  - fetch (stdio)

Risk Report saved to: /path/to/report.json

7. View Results

Go to Dashboard → Servers to see discovered MCP servers.

Common Issues

"JWT_SECRET environment variable is required" You need to set JWT_SECRET before starting the backend. See the Installation Guide for instructions.

"Invalid API key format" API keys must start with mcp_sk_. Make sure you copied the complete key from the agent creation step.

"Connection refused" when configuring agent The backend is not running or the API URL is incorrect. Verify with: curl http://localhost:8000/health

For more troubleshooting help, see the Troubleshooting Guide.

What's Next?

• Agent-Usage - Learn all agent commands
• Risk-Scoring - Understand risk calculations
• API-Reference - Integrate with your systems