MCP Server com SSE e Autenticação Bearer

by br-silvano

420 downloads

Not rated

GitHub

Other
AI

About

This is an MCP (Model Context Protocol) server implementation in TypeScript that uses Server-Sent Events (SSE) for remote message transport and Bearer token authentication. It enables secure, real-time communication between LLM hosts (e.g., Claude Desktop) and custom tools…

Details

Author: br-silvano
Downloads: 420
Categories: Other, AI

- Real‑time remote transport via Server‑Sent Events (SSE)
- Bearer token authentication on all endpoints
- Four example math tools (add, subtract, multiply, divide)
- Modular architecture following SOLID and Clean Code principles
- Development with ts‑node without pre‑compilation
- Easy inspection via @modelcontextprotocol/inspector

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name MCP Server com SSE e Autenticação Bearer

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

From the repository

Install Node.js 20+, clone the repository, run npm install, create a .env file with BEARER_TOKEN and PORT (default 3001). For development, execute npm run dev (uses ts-node). For production, run npm run build then node dist/index.js. Use npm run dev:inspect to start the MCP Inspector at http://127.0.0.1:6274 for testing tools.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "mcp server com sse e autentica\u00e7\u00e3o bearer": {
            "mcp-sse-br-silvano": {
                "command": "node",
                "args": [
                    "dist/index.js"
                ]
            }
        }
    }
}

McpServers

{
    "mcp-sse-br-silvano": {
        "command": "node",
        "args": [
            "dist/index.js"
        ]
    }
}

MCP Server com SSE e Autenticação Bearer

Este projeto é uma implementação de um MCP Server (Model Context Protocol) construído em TypeScript. Ele utiliza Server-Sent Events (SSE) para o transporte remoto de mensagens e autenticação baseada em Bearer Token, permitindo a comunicação segura e em tempo real com clientes, como hosts de LLM (ex.: Claude Desktop).

---

Índice

- Visão Geral
- Arquitetura
- Recursos e Funcionalidades
- Requisitos
- Instalação e Configuração
- Execução
- Diagrama de Sequência
- Contribuição
- Licença

---

Visão Geral

Este projeto implementa um servidor MCP que expõe ferramentas (tools) para serem chamadas via protocolo MCP, utilizando SSE para comunicação em tempo real e autenticando requisições através de um token Bearer.
<a href="https://modelcontext.org" target="_blank" rel="noopener noreferrer">Saiba mais sobre o protocolo MCP no site oficial</a>

---

Arquitetura

A arquitetura do projeto é composta pelos seguintes módulos:

- MCP Module: Responsável pela criação e configuração do servidor MCP, incluindo o registro de ferramentas.
- Middlewares: Inclui o middleware de autenticação (Bearer Token) e o middleware condicional para o processamento de JSON, garantindo que o fluxo de dados no endpoint /messages não seja consumido indevidamente.
- Rotas: Define os endpoints do Express para estabelecer a conexão SSE (/sse) e para a recepção de mensagens (/messages).
- Config: Armazena configurações como token de autenticação e porta do servidor.
- App: Centraliza a configuração do Express, integração dos middlewares e rotas, e o início do servidor.

---

Recursos e Funcionalidades

- Transporte SSE: Conexão remota em tempo real usando Server-Sent Events.
- Autenticação Bearer: Verificação de segurança via token fornecido no header Authorization.
- Ferramentas de Exemplo: Quatro ferramentas simples que realizam as quatro operações básicas de matemática, demonstrando a estrutura de registro e execução de ferramentas no MCP Server.
- Estrutura Modular: Separação de responsabilidades conforme os princípios SOLID e Clean Code.
- Desenvolvimento com ts-node: Execução direta dos arquivos TypeScript sem necessidade de pré-compilação (ideal para desenvolvimento e debugging).

---

Requisitos

- Node.js (versão 20 ou superior)
- npm
- TypeScript
- ts-node (para desenvolvimento)
- Ambiente compatível com WSL (se aplicável)

---

Instalação e Configuração

1. Clone o repositório:

   git clone <URL_DO_REPOSITORIO>
   cd mcp-sse

2. Instale as dependências:

   npm install

3. Configuração:

- Token de Autenticação:
Crie um arquivo .env na raiz do projeto e defina o token Bearer:

     BEARER_TOKEN=meu-token-secreto
     PORT=3001

- O projeto utiliza variáveis de ambiente para carregar essas configurações em runtime.

---

Execução

Usando `ts-node`

Durante o desenvolvimento, é possível executar o servidor sem pré-compilá-lo:

npm run dev

> ℹ️ _Nota: o script "start" no package.json está configurado para uso com node e exige build prévio via tsc._

---

Usando `@modelcontextprotocol/inspector`

Para visualizar e testar as ferramentas MCP em tempo real via interface web, execute:

npm run dev:inspect

> 💡 Esse comando utiliza ts-node para rodar o projeto sem build prévio.
> 🔐 A interface ficará disponível em: http://127.0.0.1:6274

---

Build e Execução em Produção

Para compilar os arquivos TypeScript:

npm run build

Depois, execute a versão compilada:

node dist/index.js

Diagrama de Sequência

O fluxo de comunicação e uso do MCP Server está ilustrado no diagrama abaixo:

@startuml
title "Fluxo de Comunicação do MCP Server com SSE e Autenticação Bearer"
actor "MCP Client" as Client
participant "Express Server" as Express

participant "Auth Middleware" as Auth

participant "Route /sse" as SSERoute

participant "SSE Server Transport" as SSE

participant "MCP Server" as MCP

participant "Route /messages" as MsgRoute
== Estabelecimento da Conexão ==

Client -> Express: GET /sse\n(Authorization: Bearer <token>)

Express -> Auth: Verifica header Authorization

Auth --> Express: Token válido\n(continua)

Express -> SSERoute: Rota /sse invocada

SSERoute -> SSE: Cria nova instância SSEServerTransport

note right of SSE: Armazena sessionId

SSE -> SSERoute: Retorna transport

SSERoute -> Express: Retorna resposta SSE

Express -> MCP: mcpServer.connect(transport SSE)

MCP -> SSE: Inicia comunicação\n(enviar mensagens iniciais)

SSE -> Client: Envia eventos SSE\n(ex.: lista de tools)
== Envio de Mensagem (POST /messages) ==

Client -> Express: POST /messages?sessionId=XYZ\n(Corpo da mensagem)

Express -> MsgRoute: Rota /messages invocada

MsgRoute -> SSE: Procura transporte pelo sessionId

SSE -> MsgRoute: Transport encontrado

MsgRoute -> SSE: transport.handlePostMessage(request)

SSE -> MCP: Encaminha mensagem recebida

MCP -> SSE: Processa mensagem e retorna resposta

SSE -> Client: Envia resposta via SSE
== Encerramento da Conexão ==

Client -> Express: Fecha conexão SSE

Express -> SSE: Detecta fechamento da conexão

SSE -> Express: Notifica desconexão

Express -> SSERoute: Remove transporte (sessionId)

@enduml

_Nome Recomendado: "Diagrama de Sequência - Fluxo de Comunicação do MCP Server com SSE e Autenticação Bearer"._

---

Contribuição

Contribuições são bem-vindas! Se você deseja melhorar este projeto:

1. Faça um fork e clone o repositório.
2. Crie uma branch para a sua feature ou correção.
3. Submeta um Pull Request com suas alterações, seguindo as diretrizes de código e mantendo os princípios SOLID e Clean Code.

---

Licença

Este projeto está licenciado sob a MIT License.

---

Documentação atualizada em 15/04/2025.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

MCP Server com SSE e Autenticação Bearer

Índice

Visão Geral

Arquitetura

Recursos e Funcionalidades

Requisitos

Instalação e Configuração

Execução

Usando ts-node

Usando @modelcontextprotocol/inspector

Build e Execução em Produção

Diagrama de Sequência

Contribuição

Licença

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Context 7

Reactive Resume

Usando `ts-node`

Usando `@modelcontextprotocol/inspector`