---
title: "Node.js / TypeScript"
description: "The official TypeScript/Node.js MCP SDK for reaching the APIBrasil APIs from modern JavaScript applications, fully typed."
lang: en
canonical: https://doc.apibrasil.io/mcp/programacao/nodejs
markdown: https://doc.apibrasil.io/mcp/programacao/nodejs.md
source: apibrasil-documentation
---

# Node.js / TypeScript

> The official TypeScript/Node.js MCP SDK for reaching the APIBrasil APIs from modern JavaScript applications, fully typed.

- **Category:** Programming languages
- **Difficulty:** Medium
- **Protocol:** connects to the MCP server
- **Updated on:** January 14, 2026

## Prerequisites

- Node.js 18 or newer
- npm or yarn installed
- TypeScript 5.0+ (optional, but recommended)
- APIBrasil tokens

## Configuration

- **File:** `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);
```

## Step by step

1. **Install the dependencies** — Install the official MCP SDK for Node.js/TypeScript
   ```bash
   npm install @modelcontextprotocol/sdk
   # ou com yarn:
   yarn add @modelcontextprotocol/sdk
   # ou com pnpm:
   pnpm add @modelcontextprotocol/sdk
   ```
2. **Set up TypeScript (optional)** — If you are using TypeScript, configure tsconfig.json
   ```json
   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "ESNext",
       "moduleResolution": "node",
       "esModuleInterop": true,
       "strict": true,
       "skipLibCheck": true
     }
   }
   ```
3. **Create a .env file** — Keep your tokens somewhere safe
   ```bash
   APIBRASIL_BEARER_TOKEN=seu_bearer_token_aqui
   APIBRASIL_DEVICE_TOKEN=seu_device_token_aqui
   ```
4. **Write the MCP client** — Create an index.ts with the client implementation
   ```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. **Run the code** — Run it with ts-node, or compile and run
   ```bash
   # Com ts-node:
   npx ts-node index.ts
   
   # Ou compilar e executar:
   npx tsc
   node dist/index.js
   ```

## Troubleshooting

- **Cannot find module '@modelcontextprotocol/sdk'** — Check that the package installed correctly. Clearing node_modules and reinstalling usually settles it
  ```
  rm -rf node_modules package-lock.json
  npm install
  ```
- **TypeError: fetch is not defined** — Use Node.js 18+, which ships fetch natively, or install node-fetch on older versions
  ```
  node --version  # Deve ser v18.0.0 ou superior
  ```
- **SSE connection timeout** — Check your network and whether the MCP server is up. Setting a custom timeout helps
  ```
  const transport = new SSEClientTransport(
    new URL('https://mcp.apibrasil.cloud/mcp'),
    { timeout: 30000 } // 30 segundos
  );
  ```
- **The headers never arrive** — Check that you are passing headers in the shape SSEClientTransport expects

## Related links

- [Official MCP TypeScript SDK documentation](https://github.com/modelcontextprotocol/typescript-sdk)
- [Advanced Node.js examples](https://doc.apibrasil.io/mcp/exemplos/nodejs.md)
- [Python integration](https://doc.apibrasil.io/mcp/programacao/python.md)
- [Deploy on Vercel](https://doc.apibrasil.io/mcp/plataformas-cloud/vercel.md)

## See also

- MCP guide: [MCP guide](https://doc.apibrasil.io/mcp.md)
- Documentation index: https://doc.apibrasil.io/llms.txt
- HTML version of this page: https://doc.apibrasil.io/mcp/programacao/nodejs