MCP vs API vs Skills vs CLI: quando usar cada um

Use CLI quando o sistema já tem uma linha de comando e você está logado nela; API direta pra chamada pontual ou script seu; MCP quando não há CLI, quando vários clientes ou agentes precisam do mesmo acesso, ou quando a autenticação não deve ficar no shell. Skill não conecta em nada: ela ensina o agente qual desses caminhos usar e como, e costuma ficar por cima de uma CLI ou de um MCP.

MCP, API, Skill e CLI aparecem nas mesmas discussões, mas não são quatro opções do mesmo tipo. Três são jeitos de o agente alcançar um sistema; a Skill é um jeito de ensinar o agente a usar o que ele alcança. Abaixo, a mesma tarefa (listar as issues abertas de um repositório do GitHub) feita pelos três caminhos no Claude Code 2.1.300, uma Skill que amarra tudo e uma tabela de decisão.

Qual a diferença entre MCP, API, Skill e CLI?

A documentação do Claude Code resume assim: MCP conecta o Claude a serviços externos; Skills ampliam o que ele sabe, inclusive como usar esses serviços. Por isso "MCP vs Skill" quase sempre termina em "MCP + Skill".

Como fica a mesma tarefa pela CLI?

Se o gh está instalado e logado, o agente não precisa de mais nada. É o caminho de menor configuração:

$ gh issue list -R anthropics/claude-code --state open --limit 3 --json number,title
102375 [FEATURE] Feature request: periodic lightweight context audit (...)
102374 [BUG] Desktop (Windows): session worktree creation fails with (...)
102373 [BUG] Remote Control: Artifact delete confirmation renders only (...)

O custo: a saída entra inteira no contexto, e o agente precisa saber as flags. Pedir --json com só os campos necessários ajuda nas duas coisas.

E pela API direta?

Mesmos números, sem instalar nada além do curl:

$ curl -s "https://api.github.com/repos/anthropics/claude-code/issues?state=open&per_page=3"
# JSON com os 3 mesmos números: 102375, 102374, 102373

$ curl -sI https://api.github.com/repos/anthropics/claude-code | grep -i x-ratelimit-limit
x-ratelimit-limit: 60

Sem token, a API REST do GitHub dá 60 requisições por hora (o header acima). Com token, você passa a cuidar de onde guardá-lo, da paginação e dos erros. A API direta serve pra chamada pontual ou dentro de um script seu; como interface fixa do agente, ela empurra pra você o trabalho que um CLI ou um MCP já fazem.

E por MCP?

O servidor MCP remoto do GitHub expõe ferramentas como listar issues e abrir PR, com autenticação por token no header. Adicionar sem o header falha na hora de conectar:

$ claude mcp add --transport http github https://api.githubcopilot.com/mcp/
$ claude mcp list
github: https://api.githubcopilot.com/mcp/ (HTTP) - ✘ Failed to connect — Incompatible auth server: does not support dynamic client registration

# com o .mcp.json acima, no escopo de projeto:
$ claude mcp list
github: https://api.githubcopilot.com/mcp/ (HTTP) - ⏸ Pending approval (run `claude` to approve)

O jeito que funciona é o guia oficial do servidor: um personal access token no header Authorization. No .mcp.json do projeto, use a variável de ambiente em vez do token literal, assim o arquivo pode ir pro git:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    }
  }
}

Servidor de escopo de projeto fica pendente até você aprovar numa sessão do claude, como mostra a segunda saída. Escopos, aprovação e variáveis estão em como configurar MCP no Claude Code.

O ganho do MCP aparece quando o mesmo acesso precisa servir vários clientes (Claude Code, Claude Desktop, outro agente) ou quando o sistema não tem CLI. Segundo a documentação de MCP, as ferramentas carregam só o nome no início da sessão e o schema completo sob demanda, então servidor ocioso pesa pouco no contexto.

Onde entra a Skill?

A Skill não substitui nenhum dos três. Ela diz qual caminho usar e como. Esta escolhe a CLI, limita o Bash a gh issue list e define o formato da resposta:

---
name: issues-abertas
description: Lista e resume as issues abertas de um repositório do GitHub. Use quando pedirem triagem, resumo ou contagem de issues.
allowed-tools: Bash(gh issue list *)
---

Pra listar issues, rode o gh (não chame a API na mão):

    gh issue list -R <dono>/<repo> --state open --limit 20 --json number,title,labels

Agrupe por label e devolva uma tabela curta: número, título, label.
Se o gh não estiver autenticado, diga isso e pare.

$ claude plugin validate .claude/skills
Validating components in: .../.claude/skills

✔ Validation passed

Estrutura do SKILL.md, allowed-tools e argumentos estão no passo a passo de como criar uma Skill no Claude Code.

Quando usar cada um?

Comece pela CLI quando ela existe. Promova pra MCP quando aparecer o segundo cliente ou quando o token não puder ficar no shell. Escreva a Skill na terceira vez que você explicar o mesmo procedimento no chat.

O que foi testado aqui

• gh issue list e curl na API pública do GitHub, em 15/10/2026: os mesmos 3 números de issue, e x-ratelimit-limit: 60 sem token.
• claude mcp add sem header (falha de conexão acima) e o .mcp.json com ${GITHUB_PAT} (pendente de aprovação), no Claude Code 2.1.300. A conexão com um token válido não foi testada.
• claude plugin validate na pasta da Skill: passou. A invocação numa sessão logada não foi testada.

Perguntas frequentes

Leia também

• Claude Code é um harness, o guia principal de Claude Code
• Como configurar MCP no Claude Code
• Como criar uma Skill no Claude Code
• Como criar um servidor MCP em Python
• Harness, RAG e context engineering

Quer colocar agentes de IA conectados aos sistemas do seu time? Fale com a Capiva.