mcp-scorecard

Três passos

1. Aponte para um servidor mcp-scorecard scan ./server.py Um arquivo Python ou um diretório. Há também variantes por camada (footprint / scoping / security / name).
2. O scorecard volta Overall grade: D (ORANGE) · tools=4 Nota geral, band por camada, contagem de tokens por ferramenta e uma lista de findings por camada.
3. Você aparara --json / --format sarif Saída legível por máquina para CI. Exit codes: 0=GREEN/YELLOW, 1=ORANGE, 2=RED.

Exemplo: um scan real

execução real, 2026-07-13: mcp-scorecard scan sobre ~/repos/domain-pre-flight, condensado da saída real do CLI

O que o scorecard pesa

Seis eixos são medidos na superfície declarada do servidor MCP; nenhum código é executado, apenas a saída de tools/list e as docstrings por trás dela:

• Carga inicial de tokens soma de description + schema + name em todas as ferramentas, tiktoken cl100k
• Inchaço por ferramenta quebra de custo por ferramenta; descriptions acima de 150 tokens são marcadas
• Verbos vagos run / handle / process / manage / execute em descriptions capturados com uma dica de ação
• Gatilho quando-usar cada ferramenta é checada para uma frase de gatilho explícita na description
• Padrões de segredo varredura regex de AWS / GitHub / OpenAI / Anthropic / Slack / PEM nas descriptions
• Namespace de nomes colisão de case, similaridade Levenshtein contra ~50 marcas + 23 MCPs conhecidos, variantes de separador

Segurança em runtime (prompt injection em tráfego vivo, wrap do MCP-Scan) e SARIF estão no roadmap para a v0.2; alvos de fonte de registry (`github:` / `npm:`) ficam para a v0.4. O scorecard v0.1 é honesto sobre o que inspeciona: a superfície declarada, e não o servidor em execução.

Para quem é

• Autores de MCP prestes a publicar e querendo uma varredura de tokens, nomes e segredos antes do release
• Integradores de agentes avaliando um MCP de terceiros antes de adicioná-lo a uma configuração de Claude Code / Cursor
• Revisores de segurança que querem uma passagem estrutural rápida antes de testes de runtime mais profundos (MCP-Scan, Inspector)
• Leitores de『MCP実践セキュリティ』 que querem rodar as checagens do livro contra seus próprios servidores

Quando usar

• Antes de publicar um novo MCP no PyPI ou npm: um único scan expõe descrições inchadas e verbos vagos sem especificação
• Antes de adicionar um MCP de terceiros ao seu agente: uma leitura estrutural rápida sobre custo, segredos e higiene de nomes
• Em CI: --json ou --format sarif para um gate legível por máquina, com ORANGE/RED como exit codes não-zero
• Ao escrever revisões no estilo『MCP実践セキュリティ』: as mesmas regras propostas pelo livro, aplicadas de forma consistente

Instalação

pip install mcp-scorecard              # CLI + library
pip install "mcp-scorecard[mcp]"       # + MCP server (stdio)
mcp-scorecard scan ./server.py

O CLI funciona sozinho. Adicione o extra opcional `[mcp]` para expor `mcp-scorecard-mcp` como um servidor MCP e deixar um LLM dentro do Claude Code / Cursor / Windsurf auditar outros MCPs a partir do chat.

O que ele olha

• Camada A — Footprint Passivo: description, schema e name contados via tiktoken por ferramenta; initial_token_load somado; descriptions acima de 150 tokens marcadas como inchadas
• Camada B — Use-Case Scoping: varredura de verbos vagos (run, handle, process, manage, execute), checagem de gatilho quando-usar, detecção de sobreposição entre pares de ferramentas, consistência de estilo de nome (snake / camel / flat)
• Camada C — Regras próprias de Security: varredura regex para chaves AWS / GitHub / OpenAI / Anthropic / Slack e blocos PEM em descriptions, checagem de shadowing contra ls / cat / rm / família curl, marcadores de injeção em docstrings. O wrap do MCP-Scan está planejado para v0.2
• Camada D — Name Safety: detecção de colisão de case, similaridade Levenshtein contra um conjunto embutido de ~50 marcas e 23 nomes de MCP conhecidos, varredura de variantes de separador (mcp_scorecard vs mcp-scorecard), higiene de namespace
• 5 ferramentas MCP via mcp-scorecard-mcp: preflight_scan (as quatro camadas), preflight_footprint, preflight_scoping, preflight_security, preflight_name_check. Todas aceitam um caminho ou um manifest JSON, portanto MCPs em TypeScript / Node são suportados via o manifest deles

Padrões de segurança capturados (amostra)

A Camada C roda varreduras regex nas descrições das ferramentas e checagens estruturais nos nomes das ferramentas. Alguns dos padrões que ela captura, com o conserto apontado:

fonte: src/mcp_preflight/rules/security.py · rules/footprint.py (padrões embutidos na v0.1)

Reescritas que o scorecard de fato recompensa

Dois exemplos de antes/depois do tipo de mudança que o scorecard pontua mais alto:

Uso

# scan completo
mcp-scorecard scan ./server.py

# JSON legível por CI
mcp-scorecard scan ./server.py --json

# registrar como servidor MCP no Claude Code
claude mcp add mcp-scorecard -- mcp-scorecard-mcp

Pontuar, não bloquear

O scorecard é um pre-flight, não um firewall. Ele pontua o que consegue inspecionar estaticamente e aponta o que consertar:

• Cada camada devolve o próprio band (GREEN / YELLOW / ORANGE / RED); a nota geral é a pior das quatro, então uma camada ORANGE derruba o cartão inteiro
• Findings vêm tipados por severidade ("warn" / "error"), então o CI consegue fazer o gate por severidade via exit code (0=GREEN/YELLOW, 1=ORANGE, 2=RED)
• A v0.1 inspeciona só a superfície declarada; prompt injection em runtime sobre tráfego MCP vivo é o trabalho do wrap do MCP-Scan planejado para v0.2

O contrato de exit codes segue as convenções do SARIF, então `mcp-scorecard scan --format sarif` cabe em um gate de segurança de CI sem cola extra.

Auto-checagem: rodar a ferramenta contra o próprio servidor MCP devolve nota geral D (ORANGE), com 557 tokens em 5 ferramentas, todas as camadas menos scoping em verde. Os findings de scoping batem em verbos vagos (handle / process / manage / execute) porque as docstrings mencionam esses verbos explicitamente como exemplos do que evitar. É um falso positivo naquele contexto, e está rotulado como tal; ainda assim, a mesma régua vai contra a própria ferramenta, sem modificação.

Por que esta ferramenta existe

O ecossistema MCP cresceu mais rápido que as regras de revisão para ele. Um único servidor verboso pode queimar milhares de tokens por turno em silêncio só por estar registrado, porque toda description e todo inputSchema vão para o LLM a cada turno. As ferramentas existentes cobrem bem o lado de runtime: o MCP-Scan cuida de injection e shadowing na hora da chamada, e o MCP Inspector cuida da conformidade de protocolo. A superfície virada para o LLM (o quanto custa manter o servidor listado, o quão bem escopadas estão as ferramentas, se os nomes colidem com comandos comuns) não tinha um scorecard dedicado. O `mcp-scorecard` preenche essa lacuna e faz isso como companheiro das checagens propostas no livro『MCP実践セキュリティ』.

Ao lado do MCP-Scan e do MCP Inspector

Três ferramentas, três perguntas diferentes. A diferença honesta é o que cada uma inspeciona na prática:

O travessão indica que a ferramenta não cobre aquele eixo, e não que ela é pior. O MCP-Scan e o MCP Inspector são as referências para segurança em runtime e depuração de protocolo respectivamente; o mcp-scorecard fica na etapa anterior, na qualidade da superfície voltada ao LLM. Os detalhes sobre MCP-Scan e MCP Inspector refletem o estado dos docs públicos deles em 2026-07; eixos não mencionados por eles ficam marcados como "—" em vez de virarem chute.

FAQ

Sobre o autor

Criado por Ken Imoto: mais de 300 artigos técnicos em Zenn, Qiita, Dev.to e neste site, mais de 40 livros em 4 idiomas, mais de 400 mil pageviews em Zenn e Qiita, 4 artigos de pesquisa no Zenodo e criador do LLMO Framework. As regras deste scorecard seguem o mesmo desenho das checagens que vão para o livro no prelo『MCP実践セキュリティ』(Impress NextPublishing).

Mais sobre Ken →

Relacionado

Combina com o domain-pre-flight, o CLI + MCP de pre-flight para escolha de domínio: mesma linha de nomenclatura pre-flight, mesmo formato duplo CLI + MCP, e o scan de amostra desta página é uma execução real contra aquele repo.

domain-pre-flight →