---
title: "Node.js / TypeScript"
description: "SDK oficial TypeScript/Node.js do MCP para integrar as APIs da APIBrasil em aplicações JavaScript modernas com type safety completo."
lang: pt-BR
canonical: https://doc.apibrasil.io/mcp/programacao/nodejs
markdown: https://doc.apibrasil.io/mcp/programacao/nodejs.md
source: apibrasil-documentation
---

# Node.js / TypeScript

> SDK oficial TypeScript/Node.js do MCP para integrar as APIs da APIBrasil em aplicações JavaScript modernas com type safety completo.

- **Categoria:** Linguagens de Programação
- **Dificuldade:** Médio
- **Protocolo:** conecta ao servidor MCP
- **Atualizado em:** 14 de janeiro de 2026

## Pré-requisitos

- Node.js 18 ou superior
- npm ou yarn instalado
- TypeScript 5.0+ (opcional, mas recomendado)
- Tokens da APIBrasil

## Configuração

- **Arquivo:** `index.ts`

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

const client = new Client(
  {
    name: 'apibrasil-client',
    version: '1.0.0',
  },
  {
    capabilities: {},
  }
);

const transport = new SSEClientTransport(
  new URL('https://mcp.apibrasil.cloud/mcp'),
  {
    headers: {
      'Authorization': `Bearer ${process.env.APIBRASIL_BEARER_TOKEN}`,
      'X-Device-Token': process.env.APIBRASIL_DEVICE_TOKEN || '',
    },
  }
);

await client.connect(transport);

// Listar ferramentas disponíveis
const tools = await client.listTools();
console.log('Ferramentas:', tools);

// Consultar CEP
const result = await client.callTool('consultar_cep', {
  cep: '01001000',
});
console.log('Resultado:', result);
```

## Passo a passo

1. **Instalar dependências** — Instale o SDK oficial do MCP para Node.js/TypeScript
   ```bash
   npm install @modelcontextprotocol/sdk
   # ou com yarn:
   yarn add @modelcontextprotocol/sdk
   # ou com pnpm:
   pnpm add @modelcontextprotocol/sdk
   ```
2. **Configurar TypeScript (opcional)** — Se estiver usando TypeScript, configure o tsconfig.json
   ```json
   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "ESNext",
       "moduleResolution": "node",
       "esModuleInterop": true,
       "strict": true,
       "skipLibCheck": true
     }
   }
   ```
3. **Criar arquivo .env** — Armazene seus tokens de forma segura
   ```bash
   APIBRASIL_BEARER_TOKEN=seu_bearer_token_aqui
   APIBRASIL_DEVICE_TOKEN=seu_device_token_aqui
   ```
4. **Implementar cliente MCP** — Crie um arquivo index.ts com a implementação do cliente
   ```typescript
   import { Client } from '@modelcontextprotocol/sdk/client/index.js';
   import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
   import dotenv from 'dotenv';
   
   dotenv.config();
   
   async function consultarCEP(cep: string) {
     const client = new Client(
       { name: 'apibrasil-client', version: '1.0.0' },
       { capabilities: {} }
     );
   
     const transport = new SSEClientTransport(
       new URL('https://mcp.apibrasil.cloud/mcp'),
       {
         headers: {
           'Authorization': `Bearer ${process.env.APIBRASIL_BEARER_TOKEN}`,
           'X-Device-Token': process.env.APIBRASIL_DEVICE_TOKEN || '',
         },
       }
     );
   
     try {
       await client.connect(transport);
       const result = await client.callTool('consultar_cep', { cep });
       return result;
     } catch (error) {
       console.error('Erro ao consultar CEP:', error);
       throw error;
     } finally {
       await client.close();
     }
   }
   
   // Uso
   consultarCEP('01001000')
     .then(resultado => console.log('Resultado:', resultado))
     .catch(erro => console.error('Erro:', erro));
   ```
5. **Executar o código** — Execute com ts-node ou compile e execute
   ```bash
   # Com ts-node:
   npx ts-node index.ts
   
   # Ou compilar e executar:
   npx tsc
   node dist/index.js
   ```

## Solução de problemas

- **Cannot find module '@modelcontextprotocol/sdk'** — Certifique-se de que instalou o pacote corretamente. Tente limpar node_modules e reinstalar
  ```
  rm -rf node_modules package-lock.json
  npm install
  ```
- **TypeError: fetch is not defined** — Use Node.js 18+ que inclui fetch nativo, ou instale node-fetch para versões anteriores
  ```
  node --version  # Deve ser v18.0.0 ou superior
  ```
- **SSE connection timeout** — Verifique sua conexão de rede e se o servidor MCP está online. Adicione timeout customizado
  ```
  const transport = new SSEClientTransport(
    new URL('https://mcp.apibrasil.cloud/mcp'),
    { timeout: 30000 } // 30 segundos
  );
  ```
- **Headers não estão sendo enviados** — Verifique se está usando o formato correto de headers no SSEClientTransport

## Links relacionados

- [Documentação oficial MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Exemplos avançados Node.js](https://doc.apibrasil.io/mcp/exemplos/nodejs.md)
- [Integração com Python](https://doc.apibrasil.io/mcp/programacao/python.md)
- [Deploy no Vercel](https://doc.apibrasil.io/mcp/plataformas-cloud/vercel.md)

## Ver também

- Guia MCP: [Guia MCP](https://doc.apibrasil.io/mcp.md)
- Índice da documentação: https://doc.apibrasil.io/llms.txt
- Versão HTML desta página: https://doc.apibrasil.io/mcp/programacao/nodejs