Getting Started

Smart Scan is an AI-powered security analysis tool for Model Context Protocol (MCP) servers. Get started by installing the CLI tool or using the REST API directly.

Quick Start

1. Get Your API Token

Go to Dashboard

2. Install the CLI

npm install -g @mcp-shark/cli

Or use npx (no installation): npx -y @mcp-shark/cli

3. Run Your First Scan

APP_TOKEN=sk_your_token_here npx @mcp-shark/cli scan --config=mcps.json

CLI Tool

The Smart Scan CLI allows you to scan MCP servers from the command line, perfect for automation and CI/CD pipelines.

Installation

Method 1: npm (Recommended)

Global installation:

npm install -g @mcp-shark/cli

Local installation (project-specific):

npm install @mcp-shark/cli

Then use with: npx @mcp-shark/cli

Method 2: npx (No Installation Required)

Using npm package:

npx -y @mcp-shark/cli scan --config=mcps.json --token=sk_your_token

Requirements: Node.js v18+ and npm

For complete installation instructions and troubleshooting, see the CLI Installation Guide.

Commands

scan

Discover MCP server capabilities and submit them for security analysis.

cli scan
  --config=path/to/mcps.json
  --token=sk_your_token_here
  --verbose

-c, --configPath to MCP configuration file (required)

--tokenAPI token (or set APP_TOKEN env var)

--verboseEnable detailed logging

--jsonOutput results as JSON

--fail-on-highExit with error code if risk level is high or critical

--fail-on-mediumExit with error code if risk level is medium

--fail-on-lowExit with error code if risk level is low

check

Check the status and results of a previously performed scan.

cli check
  --scan-id=scan_abc123
  --token=sk_your_token_here
  --verbose

-j, --scan-idScan ID from scan command (required)

--tokenAPI token (or set APP_TOKEN env var)

--verboseEnable detailed logging

--jsonOutput results as JSON

--fail-on-highExit with error code if risk level is high or critical

--fail-on-mediumExit with error code if risk level is medium

--fail-on-lowExit with error code if risk level is low

Environment Variables

APP_TOKEN

Your API token (alternative to --token flag). The CLI connects to https://smart.mcpshark.sh by default.

API Reference

The Smart Scan REST API allows you to programmatically scan MCP servers and retrieve results.

POST/api/scans

Create a new security scan by submitting MCP server data.

Request Body

{
  "server": {
    "name": "example-server",
    "description": "An example MCP server"
  },
  "tools": [...],
  "resources": [...],
  "prompts": [...]
}

Response

{
  "id": "scan_abc123",
  "status": "completed",
  "overall_risk_level": "low",
  "created_at": "2024-01-01T00:00:00Z"
}

GET/api/scans

List all scans with optional filtering and pagination.

Query Parameters

risk_levelFilter by risk: none, low, medium, high, critical

is_errorFilter by error status: true, false

date_fromStart date (ISO 8601)

date_toEnd date (ISO 8601)

limitResults per page (max 100, default 100)

offsetPagination offset (default 0)

GET/api/scans/{id}

Retrieve detailed information about a specific scan.

CI/CD Integration

Integrate Smart Scan into your CI/CD pipeline to automatically scan MCP servers on every deployment.

GitHub Actions

name: Smart Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - name: Install CLI
        run: npm install -g @mcp-shark/cli
      
      - name: Run Smart Scan
        env:
          APP_TOKEN: ${{ secrets.SMART_SCAN_TOKEN }}
        run: |
          cli scan --config=mcps.json --verbose
      
      - name: Check Scan Results
        env:
          APP_TOKEN: ${{ secrets.SMART_SCAN_TOKEN }}
        run: |
          SCAN_ID=$(cli scan --config=mcps.json | grep -o 'scan_[a-zA-Z0-9]*')
          cli check --scan-id=$SCAN_ID

GitLab CI

stages:
  - scan

smart_scan:
  stage: scan
  image: node:20
  before_script:
    - npm install -g @mcp-shark/cli
  script:
    - cli scan --config=mcps.json --verbose
  variables:
    APP_TOKEN: "$SMART_SCAN_TOKEN"

CircleCI

version: 2.1

jobs:
  scan:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install CLI
          command: npm install -g @mcp-shark/cli
      - run:
          name: Run Smart Scan
          command: |
            cli scan --config=mcps.json --verbose
          environment:
            APP_TOKEN: ${SMART_SCAN_TOKEN}

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Getting Your Token

Sign in to the Smart Scan dashboard
Navigate to the Token Management page
Create a new API token (starts with sk_)
Copy and securely store your token

Important: Your token is only shown once. Save it securely!

Using Your Token

cURL Example:

curl -X POST https://smart.mcpshark.sh/api/scans
  -H "Authorization: Bearer sk_your_token_here"
  -H "Content-Type: application/json"
  -d @scan-data.json

CLI Example:

APP_TOKEN=sk_your_token_here
cli scan --config=mcps.json

Examples

Real-world examples of using Smart Scan in different scenarios.

Basic MCP Server Scan

# mcps.json
{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

# Run scan
cli scan --config=mcps.json --token=sk_your_token

Multiple MCP Servers

# mcps.json
{
  "mcpServers": {
    "server1": {
      "command": "npx",
      "args": ["-y", "@server1/mcp"]
    },
    "server2": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    },
    "server3": {
      "type": "websocket",
      "url": "wss://ws.example.com/mcp"
    }
  }
}

Direct API Call

curl -X POST https://smart.mcpshark.sh/api/scans
  -H "Authorization: Bearer sk_your_token"
  -H "Content-Type: application/json"
  -d '{
    "server": {
      "name": "my-server",
      "description": "My MCP server"
    },
    "tools": [
      {
        "name": "my_tool",
        "description": "Tool description",
        "input_schema": {
          "type": "object",
          "properties": {
            "param": { "type": "string" }
          }
        }
      }
    ],
    "resources": [],
    "prompts": []
  }'