Counsel

Servidor MCP Counsel

Um servidor open-source Model Context Protocol (MCP) que conecta agentes de IA à API do Counsel para raciocínio estratégico e análise de múltiplas perspectivas.

Recursos

• Hospedado e Auto-hospedado - Use o servidor hospedado instantaneamente ou execute sua própria instância
• Raciocínio Estratégico - Acesse os mecanismos de debate e raciocínio multi-perspectiva do Counsel
• Sessões de Consultoria - Execute sessões interativas de coleta de perfil e ajuste
• OAuth 2.0 Nativo - Autenticação MCP padrão tratada automaticamente pelos clientes
• Transporte Duplo - STDIO para clientes locais, HTTP para clientes web e servidores compartilhados

Sumário

• Início Rápido (Hospedado)
• Instalação (Auto-hospedado)
  • Claude Desktop
  • Claude Code (CLI)
  • Cursor
  • Windsurf
  • VS Code com Copilot
  • Outros Clientes MCP
• Autenticação
• Ferramentas Disponíveis
• Exemplos de Uso
• Configuração
• Solução de Problemas
• Desenvolvimento
• Contribuição
• Licença

Início Rápido (Hospedado)

Conecte-se instantaneamente ao servidor MCP Counsel hospedado - sem necessidade de instalação:

http://counsel-mcp.getmason.dev/mcp

Para clientes MCP que suportam transporte HTTP, basta adicionar:

{
  "mcpServers": {
    "counsel": {
      "url": "http://counsel-mcp.getmason.dev/mcp",
      "transport": "http"
    }
  }
}

A autenticação OAuth é tratada automaticamente pelo seu cliente MCP.

Instalação (Auto-hospedado)

Execute sua própria instância do servidor MCP Counsel localmente.

Pré-requisitos

1. Node.js 18+ instalado no seu sistema
2. Uma conta Counsel em counsel.getmason.dev

Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

Claude Code (CLI)

claude mcp add counsel -- npx -y counsel-mcp-server start

Ou adicione manualmente às suas configurações MCP:

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

Cursor

Adicione à sua configuração MCP do Cursor (.cursor/mcp.json no seu projeto ou configurações globais):

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

Windsurf

Adicione à sua configuração MCP do Windsurf:

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

VS Code com Copilot

Adicione às suas configurações do VS Code (settings.json):

{
  "mcp.servers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

Outros Clientes MCP

O servidor suporta dois modos de transporte. Escolha com base nas capacidades do seu cliente:

Modo STDIO (Padrão)

A maioria dos clientes MCP usa transporte STDIO. Configure com:

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"],
      "env": {
        "COUNSEL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Modo HTTP com OAuth

Para clientes que suportam transporte HTTP com OAuth 2.0, execute o servidor separadamente:

# Start the HTTP server
npx -y counsel-mcp-server http --port 3000

Isso inicia um servidor HTTP com:

• Endpoint MCP: http://localhost:3000/mcp
• Descoberta OAuth: http://localhost:3000/.well-known/oauth-authorization-server

Em seguida, configure seu cliente para conectar:

{
  "mcpServers": {
    "counsel": {
      "url": "http://localhost:3000/mcp",
      "transport": "http"
    }
  }
}

O modo HTTP usa OAuth 2.0 com gerenciamento automático de tokens - nenhuma chave de API necessária.

Comparação de Transportes

Autenticação

O servidor suporta dois modos de autenticação:

Modo STDIO (Padrão)

Defina a variável de ambiente COUNSEL_API_KEY com sua chave de API de counsel.getmason.dev:

export COUNSEL_API_KEY=your_api_key_here

Ou adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"],
      "env": {
        "COUNSEL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Modo HTTP (OAuth 2.0)

Ao executar no modo HTTP (npx -y counsel-mcp-server http), a autenticação é tratada automaticamente através do OAuth 2.0:

1. Quando você usar uma ferramenta Counsel pela primeira vez, seu cliente MCP solicitará autenticação
2. Você será redirecionado para entrar com sua conta Counsel
3. Após a autorização, os tokens são gerenciados automaticamente

Nenhuma chave de API manual necessária no modo HTTP - seu cliente MCP lida com todo o fluxo OAuth.

Endpoints OAuth (Modo HTTP)

O servidor expõe endpoints OAuth 2.0 padrão:

Ferramentas Disponíveis

start_consultation

Inicie uma nova consulta estratégica (debate) para analisar uma questão complexa com múltiplas perspectivas.

Exemplo:

Start a consultation about "Should we migrate our monolith to microservices?"
with context about our 50-person engineering team and mode set to deep

get_consultation_status

Verifique o status de uma consulta em andamento.

get_consultation_report

Recupere o relatório de síntese final de uma consulta concluída.

list_consultations

Liste suas consultas anteriores.

sharpen_question

Refine e melhore uma questão estratégica antes de iniciar uma consulta.

Exemplo:

Sharpen this question: "Is AI good for our company?"

consult_advisor

Inicie uma sessão interativa de consultoria para brainstorming ou definição de escopo de problemas.

Exemplos de Uso

Tomada de Decisão Estratégica

Use Counsel to analyze: "Should we expand into the European market in 2025?"

Consider these stakeholders: CEO, CFO, Head of Sales, Legal
Use deep analysis mode

Refinamento de Questões

Use the sharpen_question tool to improve this question:
"How do we fix our culture?"

Context: We're a 200-person startup experiencing rapid growth

Verificando o Progresso da Consulta

Check the status of consultation abc-123-def

Configuração

Variáveis de Ambiente

Comandos CLI

# STDIO mode (default) - for most MCP clients
npx -y counsel-mcp-server start

# HTTP mode - for clients supporting OAuth
npx -y counsel-mcp-server http [options]

HTTP Options:
  -p, --port <port>  Port to listen on (default: 3000)
  --host <host>      Host to bind to (default: localhost)

Solução de Problemas

Erro "Ferramenta não encontrada"

Certifique-se de que o servidor MCP está configurado corretamente no seu cliente. Reinicie o cliente após adicionar a configuração.

Problemas de Autenticação

1. Verifique se você tem uma conta Counsel válida
2. Tente remover e adicionar novamente a configuração do servidor MCP
3. Limpe o cache MCP do seu cliente, se disponível

Conexão Recusada

Se estiver executando no modo HTTP, certifique-se de que:

• O servidor está em execução (npx counsel-mcp-server start)
• A porta não está bloqueada por um firewall
• Nenhum outro processo está usando a mesma porta

Servidor Não Iniciando

# Check Node.js version (requires 18+)
node --version

# Try running directly to see errors
npx counsel-mcp-server start

Modo de Depuração

Para registro detalhado, verifique os logs do seu cliente MCP ou execute o servidor diretamente em um terminal para ver a saída.

Desenvolvimento

Pré-requisitos

• Node.js 18+
• npm 9+

Configuração

git clone https://github.com/mercurialsolo/counsel-mcp.git
cd counsel-mcp-server
npm install
npm run build

Comandos

npm run build            # Compile TypeScript
npm run dev              # Watch mode
npm run start            # Run server
npm test                 # Run tests
npm run lint             # Type check
npm run security:check   # Scan staged files for secrets
npm run security:check:all  # Scan all files for secrets

Segurança

Este projeto inclui detecção automatizada de segredos:

• Hook de pré-commit: Escaneia automaticamente arquivos preparados antes de cada commit
• Integração CI: Verificações de segurança executadas em todos os pull requests
• Detecção de padrões: Chaves AWS, tokens GitHub, chaves de API, chaves privadas, etc.

Consulte CONTRIBUTING.md para detalhes.

Estrutura do Projeto

src/
├── index.ts        # HTTP server, OAuth proxy, MCP transport
├── client.ts       # API client with request-scoped auth
├── config.ts       # Environment configuration
└── tools/
    ├── debates.ts  # Consultation tools
    └── advisor.ts  # Advisor session tools

Contribuição

Aceitamos contribuições! Consulte CONTRIBUTING.md para diretrizes.

Início Rápido

1. Faça um fork do repositório
2. Crie um branch de recurso: git checkout -b feature/your-feature
3. Faça suas alterações e adicione testes
4. Execute npm test para garantir que os testes passem
5. Envie um pull request

Licença

Licença MIT - consulte LICENSE para detalhes.

Links

• Plataforma Counsel - Plataforma de raciocínio estratégico
• Especificação MCP - Documentação do Model Context Protocol
• Issues no GitHub - Reporte bugs ou solicite recursos
• Discussões no GitHub - Faça perguntas