Ferrok API Documentation

Scan MCP server configurations for security vulnerabilities. Map findings to the OWASP MCP Top 10. Integrate automated security into your workflow.

Authentication

All requests require a Bearer token in the Authorization header.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.ferrok.dev/v1/health

Base URL

https://api.ferrok.dev

Local dev: http://localhost:8000.

Quickstart

Send your first scan in under a minute:

curl -X POST https://api.ferrok.dev/v1/scan \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "config": {
      "server_name": "my-mcp-server",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@my-org/mcp-server"],
      "tools": [{
        "name": "read_file",
        "description": "Read a file from the filesystem",
        "inputSchema": {
          "type": "object",
          "properties": { "path": { "type": "string" } },
          "required": ["path"]
        }
      }]
    }
  }'

Response:

{
  "scan_id": "scan_a1b2c3d4",
  "summary": {
    "overall_score": 62,
    "grade": "C-",
    "total_findings": 5,
    "pass_fail": "FAIL"
  },
  "findings": [ /* ... */ ]
}

POST /v1/scan

Analyzes an MCP server configuration and returns findings mapped to the OWASP MCP Top 10.

Responses

GET /v1/health

Health check. No auth required.

{ "status": "healthy", "version": "0.1.0", "engine": "Ferrok" }

ScanRequest

MCPServerConfig

ToolDefinition

ScanResponse

Finding

ScanSummary

Scoring & Grades

Start at 100. Deductions per finding:

Severity Levels

OWASP MCP Top 10

Scanner Modules

Tool Poisoning Scanner TP-*

Prompt injection, hidden instructions, data exfiltration, role manipulation, encoded chars, zero-width unicode.

Permission Analyzer PA-*

Filesystem, network, code execution, database, secrets access, wildcard patterns.

Schema Validator SV-*

Missing schemas, non-object roots, empty properties, unconstrained strings, description mismatches.

Transport Security TS-*

Insecure HTTP, hardcoded secrets, npx -y supply chain, shell injection, missing capabilities.

CI/CD Integration

GitHub Actions

# .github/workflows/mcp-security.yml
name: MCP Security Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan MCP config
        run: |
          RESULT=$(curl -s -X POST https://api.ferrok.dev/v1/scan \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer ${{ secrets.FERROK_API_KEY }}" \
            -d @mcp-config.json)
          echo "$RESULT" | jq .
          VERDICT=$(echo "$RESULT" | jq -r '.summary.pass_fail')
          [ "$VERDICT" = "PASS" ] || exit 1

GitLab CI

mcp_security:
  stage: test
  script:
    - |
      RESULT=$(curl -s -X POST https://api.ferrok.dev/v1/scan \
        -H "Authorization: Bearer $FERROK_API_KEY" -d @mcp-config.json)
      [ "$(echo $RESULT | jq -r '.summary.pass_fail')" = "PASS" ] || exit 1

Python

import httpx, sys, json

resp = httpx.post(
    "https://api.ferrok.dev/v1/scan",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"config": json.load(open("mcp-config.json"))}
)
result = resp.json()
if result["summary"]["pass_fail"] == "FAIL":
    sys.exit(1)

Error Handling

Rate Limits

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709683200