Skip to main content
Glama
deenesjakoruzh
KTTechUp-Team304

VA-MCP

by KTTechUp-Team304
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

[KT Tech up] 사이버 보안 2기 TEAM 304

팀장: 이윤재 / 팀원: 김태우, 윤지훈, 최민준

Vulnerability Analyzer MCP — API 엔드포인트 정보를 받아 OWASP Top 10 관점의 취약점 점검을 수행하고, 결과 리포트를 반환하는 Model Context Protocol 서버입니다.

저장소: github.com/KTTechUp-Team304/VA_MCP

Cursor·Claude Desktop 등 MCP를 지원하는 에이전트에 연결해 사용합니다.

제공 기능

MCP Tool

설명

analyze_endpoint

엔드포인트 프로필 분석 → 시나리오 계획 → OWASP 점검 도구 자동 실행 → 결과 요약

list_supported_checks

지원 점검 목록 조회

ping

서버 연결 확인

(개별 점검 도구)

sql_injection, idor_bola, jwt_validation 등 — Planner가 선택하거나 직접 호출 가능

  • 사람용 분석 보고서: reports/{METHOD}_{path}_{시각}.md (저장소 루트)

  • 개발·디버깅 산출물: outputs/runs/<run_id>/, outputs/logs/ (DUMP_ARTIFACTS=true 시)

Related MCP server: MCP-QA

요구 사항

git --version
uv --version
python3 --version

설치

git clone https://github.com/KTTechUp-Team304/VA_MCP.git
cd VA_MCP
uv sync
uv tool install .

  • uv tool install . → ~/.local/bin/va-mcp CLI 등록 (which va-mcp로 확인)

  • ~/.local/bin이 PATH에 없으면 셸 설정에 추가한 뒤 MCP 클라이언트를 재시작하세요.

MCP 클라이언트 연동

Cursor

이 저장소에 .cursor/mcp.json이 포함되어 있습니다.

  1. Cursor에서 VA-MCP 폴더를 엽니다.

  2. Settings → MCP에서 va-mcp 서버가 활성화되어 있는지 확인합니다.

다른 프로젝트(예: broken_regist_frontend)만 연 상태에서 쓰려면, 위 설치 후 전역 ~/.cursor/mcp.json에 동일 설정을 넣거나, 워크스페이스에 VA-MCP 폴더를 추가합니다.

{
  "mcpServers": {
    "va-mcp": {
      "command": "va-mcp"
    }
  }
}

Claude Desktop

macOS 기준 설정 파일: ~/Library/Application Support/Claude/claude_desktop_config.json

mcpServers 블록에 위와 동일하게 추가한 뒤 Claude Desktop을 완전히 종료 후 재실행합니다.

사용 방법

1) 연결 확인

에이전트 채팅에서 MCP 도구 ping을 호출해 응답이 오는지 확인합니다.

2) 엔드포인트 점검 (analyze_endpoint)

점검할 API의 메서드·경로·베이스 URL·(선택) 인증·요청/응답 예시를 전달합니다. 에이전트가 analyze_endpoint 도구를 호출하면 내부적으로 프로필 파싱 → 기능 추출 → 시나리오 계획 → 점검 실행이 이어집니다.

입력 스키마 상세: docs/endpointProfile.md

예시 (개념)

{
  "base_url": "http://localhost:4000",
  "method": "GET",
  "path": "/api/enrollments/me",
  "auth_required": true,
  "headers": { "Authorization": "Bearer <access_token>" }
}

  • status: "analyzed" — 점검 완료

  • status: "need_more_context" — missing 필드를 보완한 뒤 다시 호출

3) 결과 확인

결과는 두 갈래로 제공됩니다.

A. MCP 응답 (에이전트 → 대화창)

analyze_endpoint가 반환하는 JSON을 Cursor 에이전트가 읽고 채팅으로 요약합니다. 파일을 열지 않아도 동작합니다.

필드

설명

status

analyzed / need_more_context / invalid_input

run_id

실행 추적 ID (outputs/runs/ 폴더명과 동일)

tool_results

도구별 점검 결과 (status, severity, evidence, 권고 등)

endpoint_report

OWASP 시나리오별 집계 JSON

report_paths

저장된 리포트 파일 경로 (report_md, report_json, report_basename)

B. 사람용 분석 보고서 (reports/)

저장소 루트의 reports/ 폴더에 Markdown·JSON이 저장됩니다. IDE에서 직접 열어 보거나 팀과 공유할 때 사용합니다.

파일

설명

reports/{METHOD}_{path}_{시각}_{접미사}.md

가독성 좋은 분석 보고서 (요약 표, OWASP별 상세)

reports/{METHOD}_{path}_{시각}_{접미사}.json

동일 내용의 구조화 JSON

예: reports/GET_api_admin_2026-05-20T05-42-56_9ddf04.md

MCP 연결 문제는 Cursor Output → MCP Logs, 서버 내부 로그는 outputs/logs/va-mcp.log를 참고하세요.

업데이트

cd VA_MCP
git pull
uv sync
uv tool install --reinstall .

이후 MCP 클라이언트를 재시작합니다.

환경 변수 (선택)

프로젝트 루트 .env 또는 MCP 설정의 env 블록으로 지정할 수 있습니다.

변수

기본값

설명

LOG_LEVEL

INFO

로그 상세도 (DEBUG 등)

OUTPUT_DIR

(자동) 저장소/outputs

개발·디버깅 산출물 (runs, logs)

REPORTS_DIR

(자동) 저장소/reports

사람용 취약점 분석 리포트 (.md / .json)

DUMP_ARTIFACTS

false

true 시 outputs/runs/에 단계별 JSON 덤프

문제 해결

증상

확인

MCP 서버를 찾을 수 없음

which va-mcp, PATH에 ~/.local/bin 포함 여부

도구 목록이 비어 있음

Cursor/Claude 재시작, MCP 설정 JSON 문법

점검 중 통신 오류

대상 API(예: localhost:4000)가 실행 중인지

JSON 파싱 실패

서버 코드에 print()로 stdout 사용 금지 — stdio 전용 채널

관련 프로젝트

취약점 학습용 수강신청 웹서버와 함께 사용할 수 있습니다. 같은 상위 폴더에 clone한 경우:

  • ../broken_regist_backend — NestJS API (기본 http://localhost:4000)

  • ../broken_regist_frontend — Next.js UI

개발자용 문서

기능 개발·브랜치 전략·테스트 작성 규칙은 팀 내부 문서를 참고하세요.

제한 사항

  • 현재 배포 형태는 로컬 stdio MCP입니다. Cursor/Claude가 자식 프로세스로 va-mcp를 실행합니다.

  • 원격 HTTP MCP·다중 사용자 호스팅은 추후 별도 배포 단계에서 검토 예정입니다.

Available Tools

2 tools
list_supported_checksB

현재 지원 예정인 점검 항목 목록을 반환한다.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool returns a list, implying a read-only operation, but doesn't specify details like response format, potential errors, rate limits, or authentication requirements. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function without any unnecessary words or fluff. It is front-loaded with the core action and resource, making it easy to parse and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate for conveying the basic purpose. However, it lacks details on output format or behavioral traits, which could be helpful for an agent to understand what to expect from the response. It meets the minimum viable level but doesn't provide comprehensive context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the schema description coverage is 100% (as there are no parameters to describe). The description doesn't need to add parameter semantics, so it meets the baseline for this scenario. No additional value is required or provided, which is appropriate given the lack of parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '현재 지원 예정인 점검 항목 목록을 반환한다' translates to 'Returns a list of inspection items currently scheduled for support.' This specifies the verb ('returns') and resource ('list of inspection items scheduled for support'), making the purpose clear. However, it doesn't explicitly differentiate from the sibling tool 'ping', which likely serves a different function (e.g., connectivity testing), so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling tool 'ping' or any other context for usage, such as prerequisites or scenarios where this tool is appropriate. Without such information, the agent lacks explicit direction on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pingB

MCP 서버 상태를 확인한다.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. The description only states what the tool does ('checks server status') but provides no information about what the check entails, what 'status' means, whether this is a read-only operation, what permissions might be required, or what happens when invoked. For a tool with zero annotation coverage, this is insufficient behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise - a single sentence that directly states the tool's purpose. There's zero wasted language or unnecessary elaboration. It's appropriately sized for a simple tool with no parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has no parameters, 100% schema coverage, and an output schema exists, the description is minimally adequate. However, for a status-checking tool with no annotations, the description should ideally provide more context about what 'server status' means and what the output represents. The existence of an output schema helps, but the description itself lacks completeness for understanding the tool's behavior and results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and schema description coverage is 100%. With no parameters to document, the baseline for this dimension is 4. The description doesn't need to compensate for any parameter documentation gaps since there are none.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'MCP 서버 상태를 확인한다' (Checks MCP server status). It uses a specific verb ('확인한다' - checks/verifies) and resource ('MCP 서버 상태' - MCP server status). However, it doesn't explicitly differentiate from its sibling tool 'list_supported_checks', which might have overlapping or related functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There's no mention of when this tool should be used, when it shouldn't, or how it differs from the sibling tool 'list_supported_checks'. The agent receives no contextual usage information beyond the basic purpose statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedlist_supported_checks
    • First observedping
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: one lists supported checks (a domain-specific operation) and the other checks server status (a general utility). There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tools follow a consistent snake_case naming pattern with clear verb_noun structure: 'list_supported_checks' and 'ping'. The naming is predictable and readable throughout.

Tool Count2/5

With only two tools, the server feels severely under-scoped for a domain like 'VA-MCP' (which suggests vulnerability assessment or similar). A single domain-specific tool plus a ping utility is too thin for meaningful agent workflows.

Completeness2/5

The server appears to target vulnerability/security checks, but only lists supported checks without tools to run checks, get results, or manage them. This leaves significant gaps that will hinder agent operations in this domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • CyberMCP

    ricauts
    A
    license
    C
    quality
    D
    maintenance
    A Model Context Protocol server designed for testing backend APIs for security vulnerabilities like authentication bypass, injection attacks, and data leakage.
    14
    16
    MIT

  • MCP-QA

    qa-reysser
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server for the comprehensive analysis of Swagger 2.0 and OpenAPI 3.x contracts. It allows users to extract detailed information about endpoints, request/response schemas, parameters, and security configurations from API documentation.
    -

  • DevSecOps MCP Server

    JesusDavidQuarksoft
    A
    license
    B
    quality
    D
    maintenance
    An MCP server that integrates SAST, DAST, and SCA security tools to enable AI-driven vulnerability scanning and automated security reporting. It allows AI assistants to execute and analyze results from tools like Semgrep, OWASP ZAP, and Trivy within a DevSecOps workflow.
    6
    MIT

  • sentinel-mcp

    kal72
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server for AI-powered API testing that enables automated positive, negative, and security testing directly from AI chat interfaces. It supports multiple AI providers and generates detailed security reports.
    8 npm
    -