Protocolo de Contexto de Modelo (MCP): Construindo uma Ponte de AI para API

1. O Que É MCP?

Protocolo de Contexto de Modelo (MCP) permite que um assistente de IA, como Kiro, Codex, Claude ou outro agente compatível com MCP, interaja com sistemas externos de maneira estruturada.

Um modelo mental útil é:

Agente de IA --> Cliente MCP --> Servidor MCP -->  
API Externa / Banco de Dados / Aplicação

Para este exemplo, suponha que temos uma API interna de Gerenciamento de Tarefas chamada TodoHub.

TodoHub fornece APIs REST como:

GET  /todos/123
POST /todos
PUT  /todos/123
POST /todos/123/comments

Queremos que um agente de IA entenda solicitações como:

Mostrar a tarefa 123

ou:

Criar uma tarefa de alta prioridade para corrigir o problema de login.

Nosso servidor MCP atua como a ponte entre o agente de IA e a API TodoHub.

2. O Que Estamos Construindo?

Nossa arquitetura será assim:

Usuário  ----> "Mostrar a tarefa 123"

Agente de IA
(Kiro / Codex / Claude)  ---->  Chamada de ferramenta MCP

Servidor MCP TodoHub ---->  Chamada HTTP REST  ---> API TodoHub

O servidor MCP expõe ferramentas como:

get_todo
create_todo
update_todo
add_comment

Estas são ferramentas MCP.

A IA não precisa saber exatamente como a API REST subjacente funciona.

Ela só precisa entender a ferramenta e sua entrada:

Ferramenta: get_todo

Entrada:
  todo_id

O servidor MCP lida com a comunicação real da API.

Por exemplo:

IA  ----> get_todo(todo_id=123)
 |
 |-----> Servidor MCP ---> GET /api/todos/123
 ----> TodoHub

3. Servidor MCP vs API REST

Essa distinção é importante.

Você pode se perguntar:

Por que não simplesmente damos à IA nossa API REST?

A razão é que um servidor MCP fornece à IA uma abstração mais limpa e amigável para IA sobre a API subjacente.

Sua API REST pode exigir algo como:

POST /api/v2/workitems

com um corpo de solicitação:

{
  "subject": "...",
  "type_id": 7,
  "priority_id": 3,
  "workspace_id": 19,
  "creator": 758
}

No entanto, expor todos esses detalhes de implementação internos para a IA é desnecessário.

Em vez disso, a ferramenta MCP poderia expor uma interface muito mais simples:

create_todo(
    title,
    description,
    priority
)

O servidor MCP traduz os parâmetros amigáveis para IA nos parâmetros exigidos pela aplicação interna.

Por exemplo:

priority = "high"
        │
        ▼
   Servidor MCP
        │
        ▼
priority_id = 3

Assim, a arquitetura se torna:

Parâmetros amigáveis para IA
        │
        ▼
    Servidor MCP
        │
        ▼
Parâmetros da aplicação interna
        │
        ▼
     API REST

Isso mantém os detalhes de implementação longe da IA e dá à IA uma interface mais simples para trabalhar.

4. Ferramentas MCP

Um servidor MCP pode expor diferentes ferramentas para diferentes operações.

Para nosso exemplo do TodoHub:

Por exemplo:

get_todo

Entrada:
  todo_id: inteiro

create_todo

Entrada:
  title: string
  description: string
  priority: string

A IA pode então selecionar a ferramenta apropriada com base na solicitação do usuário.

5. Configurando o Servidor MCP

O agente de IA precisa saber como iniciar e se comunicar com o servidor MCP.

Por exemplo, podemos criar um arquivo de configuração mcp.json:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",

  "mcpServers": {
    "todohub": {
      "type": "stdio",

      "command": "uvx",

      "args": [
        "--from",
        "mcp-todohub",
        "mcp-todohub"
      ],

      "env": {
        "TODOHUB_URL": "https://todos.example.com",
        "TO