# Como o MCP Funciona

import Code from '~/components/Code/Code.astro'

O servidor MCP da Azion opera como uma ponte entre assistentes de IA e a Plataforma Azion, fornecendo acesso seguro a documentação, ferramentas e recursos através de um protocolo padronizado.

---

## Arquitetura Técnica

O MCP implementa um modelo cliente-servidor usando o protocolo Model Context Protocol da Anthropic. A arquitetura consiste em três componentes principais:

### Stack Tecnológica

| Componente | Tecnologia | Propósito |
|------------|------------|----------|
| **Runtime** | Node.js 20+ | Ambiente de execução JavaScript |
| **Linguagem** | TypeScript | Tipagem estática e segurança |
| **Protocolo** | MCP SDK | Implementação do protocolo Anthropic |
| **Hospedagem** | Edge Functions | Execução distribuída na Azion |
| **Autenticação** | Personal Token / OAuth | Controle de acesso seguro |

### Fluxo de Comunicação

```text
Assistente de IA (Cliente)
    ↓ Conexão HTTP/WebSocket
Servidor MCP (Edge Function)
    ↓ Chamadas de API
Plataforma Azion (Recursos)
```

O fluxo funciona da seguinte maneira:

1. **Conexão**: O cliente MCP estabelece conexão com o servidor usando HTTP ou WebSocket
2. **Autenticação**: O Personal Token valida a identidade do usuário
3. **Descoberta**: O cliente descobre ferramentas e recursos disponíveis
4. **Execução**: O assistente invoca ferramentas conforme necessário
5. **Resposta**: O servidor retorna dados estruturados ao cliente

---

## Componentes do MCP

O protocolo MCP define três tipos principais de capacidades que um servidor pode expor:

### Tools (Ferramentas)

Tools são funções que o assistente de IA pode invocar para realizar ações ou buscar informações. Cada tool possui:

- **Nome**: Identificador único (ex: `search_azion_docs_and_site`)
- **Descrição**: Explica o propósito e quando usar
- **Schema de entrada**: Define parâmetros esperados usando JSON Schema
- **Handler**: Função que executa a lógica

Exemplo de definição de tool:

<Code lang="typescript" code={`server.tool(
  'search_azion_docs_and_site',
  {
    description: 'Fornece informações sobre a Plataforma Azion, produtos e serviços',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Consulta para buscar documentação'
        },
        docsAmount: {
          type: 'number',
          description: 'Quantidade de documentos a retornar',
          default: 5
        }
      },
      required: ['query']
    }
  },
  async (args) => {
    // Implementação da busca
    const results = await searchDocs(args.query, args.docsAmount);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(results)
      }]
    };
  }
);`} />

### Resources (Recursos)

Resources são dados estruturados que podem ser lidos pelo cliente, similar a arquivos. Eles usam URIs para identificação:

<Code lang="typescript" code={`server.resource(
  'static-site-deploy-guide',
  'azion://static-site/deploy/step-0-preparation',
  async () => ({
    contents: [{
      uri: 'azion://static-site/deploy/step-0-preparation',
      name: 'step-0-preparation.md',
      mimeType: 'text/markdown',
      text: guideContent
    }]
  })
);`} />

URIs de recursos seguem o formato: `azion://[categoria]/[recurso]/[item]`

### Prompts

Prompts são templates pré-configurados que ajudam em cenários comuns:

<Code lang="typescript" code={`server.prompt(
  'deploy-static-site',
  {
    description: 'Guia passo a passo para deploy de sites estáticos',
    arguments: [
      {
        name: 'framework',
        description: 'Framework utilizado (ex: nextjs, astro, hugo)',
        required: true
      }
    ]
  },
  async (args) => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: 'Ajude-me a fazer deploy de um site ' + args.framework + ' na Azion'
        }
      }]
    };
  }
);`} />

---

## Implementação de um Servidor MCP

Para implementar seu próprio servidor MCP, siga estes passos:

### Estrutura do Projeto

<Code lang="text" code={`meu-mcp-server/
├── src/
│   ├── index.ts           # Ponto de entrada
│   ├── core/
│   │   ├── tools.ts       # Definição de tools
│   │   ├── resources.ts   # Definição de resources
│   │   ├── prompts.ts     # Definição de prompts
│   │   └── services/      # Lógica de negócio
│   └── middlewares/
│       └── auth.ts        # Autenticação
├── package.json
├── tsconfig.json
└── azion.config.ts        # Configuração para deploy`} />

### Ponto de Entrada

O arquivo principal inicializa o servidor e registra as capacidades:

<Code lang="typescript" code={`// src/index.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerTools } from './core/tools';
import { registerResources } from './core/resources';
import { registerPrompts } from './core/prompts';

const server = new McpServer({
  name: 'meu-mcp-server',
  version: '1.0.0'
});

// Registrar capacidades
registerTools(server);
registerResources(server);
registerPrompts(server);

// Iniciar servidor
export default {
  async fetch(request: Request): Promise<Response> {
    return server.handleRequest(request);
  }
};`} />

### Autenticação

O servidor MCP suporta múltiplos métodos de autenticação:

<Code lang="typescript" code={`// src/middlewares/auth.ts
export async function authenticate(request: Request): Promise<AuthResult> {
  const authHeader = request.headers.get('Authorization');
  
  if (!authHeader) {
    return { success: false, error: 'Token não fornecido' };
  }

  const token = authHeader.replace('Bearer ', '');

  // Verificar Personal Token (formato: azion + 35 chars)
  if (token.startsWith('azion') && token.length === 40) {
    return validatePersonalToken(token);
  }

  // Verificar OAuth token via SSO
  return validateOAuthToken(token);
}`} />

---

## Deploy na Azion

O servidor MCP pode ser deployado como uma Edge Function na Azion:

### Configuração

Crie um arquivo `azion.config.ts` na raiz do projeto:

```

export default {
  build: {
    preset: 'typescript',
    polyfills: true
  },
  functions: [
    {
      name: '$FUNCTION_NAME',
      path: './functions/index.js'
    }
  ],
  applications: [
    {
      name: '$APPLICATION_NAME',
      rules: {
        request: [
          {
            name: 'Execute Function',
            description: 'Execute function for all requests',
            active: true,
            criteria: [
              [
                {
                  variable: '${uri}',
                  conditional: 'if',
                  operator: 'matches',
                  argument: '^/'
                }
              ]
            ],
            behaviors: [
              {
                type: 'run_function',
                attributes: {
                  value: '$FUNCTION_NAME'
                }
              }
            ]
          }
        ]
      },
      functionsInstances: [
        {
          name: '$FUNCTION_INSTANCE_NAME',
          ref: '$FUNCTION_NAME'
        }
      ]
    }
  ],
  workloads: [
    {
      name: '$WORKLOAD_NAME',
      active: true,
      infrastructure: 1,
      deployments: [
        {
          name: '$DEPLOYMENT_NAME',
          current: true,
          active: true,
          strategy: {
            type: 'default',
            attributes: {
              application: '$APPLICATION_NAME'
            }
          }
        }
      ]
    }
  ]
}
```


### Deploy

Use o Azion CLI para fazer deploy:

<Code lang="bash" code={`# Link do projeto
azion link

# Build do projeto
azion build

# Deploy para produção
azion deploy`} />

O deploy cria uma URL acessível publicamente que pode ser configurada nos clientes MCP.

---

## Boas Práticas

### Design de Tools

1. **Nomes descritivos**: Use verbos e substantivos claros (ex: `search_docs`, `create_rule`)
2. **Parâmetros tipados**: Defina schemas JSON Schema completos
3. **Descrições claras**: Explique quando e como usar cada tool
4. **Tratamento de erros**: Retorne mensagens de erro informativas
5. **Idempotência**: Tools devem ser seguras para múltiplas chamadas

### Performance

1. **Cache de respostas**: Implemente cache para dados frequentemente acessados
2. **Paginação**: Use paginação para grandes conjuntos de dados
3. **Timeouts**: Defina timeouts apropriados para operações longas
4. **Compressão**: Comprima respostas grandes

### Segurança

1. **Validação de entrada**: Sempre valide parâmetros de entrada
2. **Rate limiting**: Implemente limites de taxa por token
3. **Logs de auditoria**: Registre todas as operações sensíveis
4. **Sanitização**: Remova dados sensíveis antes de retornar

---

## Exemplo Completo

Veja um exemplo completo de tool para buscar documentação:

<Code lang="typescript" code={`// src/core/services/docsService.ts
import { z } from 'zod';

const SearchSchema = z.object({
  query: z.string().min(1),
  docsAmount: z.number().min(1).max(20).default(5)
});

export async function searchDocumentation(args: unknown) {
  // Validar entrada
  const validated = SearchSchema.parse(args);
  
  // Buscar documentos
  const response = await fetch('https://api.azion.com/docs/search', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + process.env.AZION_API_KEY
    },
    body: JSON.stringify({
      query: validated.query,
      limit: validated.docsAmount
    })
  });

  if (!response.ok) {
    throw new Error('Falha na busca: ' + response.statusText);
  }

  const results = await response.json();
  
  // Formatar resposta
  return {
    content: [{
      type: 'text',
      text: JSON.stringify(results, null, 2)
    }]
  };
}`} />

---

## Recursos Adicionais

- [Especificação MCP](https://modelcontextprotocol.io) - Documentação oficial do protocolo
- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) - SDK TypeScript oficial
- [Repositório Azion MCP](https://github.com/aziontech/mcp-server) - Código-fonte do servidor Azion
- [Visão Geral do MCP](/pt-br/documentacao/devtools/mcp/) - Introdução ao MCP
- [Guia de Configuração](/pt-br/documentacao/devtools/mcp/configuracao/) - Configure seu ambiente
- [Exemplos Práticos](/pt-br/documentacao/devtools/mcp/exemplos/) - Casos de uso reais