Skip to main content
Glama
mercurialsolo

Counsel MCP Server

by mercurialsolo
OverviewInspectSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

Counsel MCP Server

npm version License: MIT Node.js Version

An open-source Model Context Protocol (MCP) server that connects AI agents to the Counsel API for strategic reasoning and multi-perspective analysis.

Features

  • Strategic Reasoning - Access Counsel's debate and multi-perspective reasoning engines

  • Advisor Sessions - Run interactive intake and profile tuning sessions

  • Native OAuth 2.0 - Standard MCP authentication handled automatically by clients

  • HTTP Transport - Works with any MCP client supporting HTTP/SSE transport

Table of Contents

Installation

Prerequisites

  1. Node.js 18+ installed on your system

  2. A Counsel account at counsel.getmason.dev

Claude Desktop

Add to your 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

Or manually add to your MCP settings:

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

Cursor

Add to your Cursor MCP configuration (.cursor/mcp.json in your project or global settings):

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

Windsurf

Add to your Windsurf MCP configuration:

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

VS Code with Copilot

Add to your VS Code settings (settings.json):

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

Other MCP Clients

For any MCP-compatible client, configure with:

  • Command: npx

  • Args: ["-y", "counsel-mcp-server", "start"]

  • Transport: stdio (default) or http at http://localhost:3000/mcp

HTTP Mode with OAuth (Advanced)

For clients that support HTTP transport with OAuth 2.0, run the server in HTTP mode:

npx -y counsel-mcp-server http --port 3000

This starts an HTTP server with:

  • MCP endpoint: http://localhost:3000/mcp

  • OAuth discovery: http://localhost:3000/.well-known/oauth-authorization-server

Then configure your client with:

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

The HTTP mode proxies OAuth requests to Counsel's authorization server, enabling standard OAuth 2.0 authentication without manual API key configuration.

Authentication

The server supports two authentication modes:

STDIO Mode (Default)

Set the COUNSEL_API_KEY environment variable with your API key from counsel.getmason.dev:

export COUNSEL_API_KEY=your_api_key_here

Or add it to your MCP client configuration:

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

HTTP Mode (OAuth 2.0)

When running in HTTP mode (npx -y counsel-mcp-server http), authentication is handled automatically through OAuth 2.0:

  1. When you first use a Counsel tool, your MCP client will prompt for authentication

  2. You'll be redirected to sign in with your Counsel account

  3. After authorization, tokens are managed automatically

No manual API key required in HTTP mode - your MCP client handles the entire OAuth flow.

OAuth Endpoints (HTTP Mode)

The server exposes standard OAuth 2.0 endpoints:

Endpoint

Description

/.well-known/oauth-authorization-server

OAuth metadata discovery

/authorize

Authorization endpoint

/token

Token exchange endpoint

/register

Dynamic client registration

Available Tools

start_consultation

Start a new strategic consultation (debate) to analyze a complex question with multiple perspectives.

Parameter

Type

Required

Description

question

string

Yes

The core question to analyze

context

string

No

Additional context about the situation

mode

enum

No

Depth of analysis: quick, standard (default), deep

stakeholders

string[]

No

Key stakeholders to consider

Example:

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

Check the status of an ongoing consultation.

Parameter

Type

Required

Description

debate_id

string

Yes

The ID of the consultation

get_consultation_report

Retrieve the final synthesis report from a completed consultation.

Parameter

Type

Required

Description

debate_id

string

Yes

The ID of the consultation

list_consultations

List your past consultations.

Parameter

Type

Required

Description

limit

number

No

Number of results (default: 10)

sharpen_question

Refine and improve a strategic question before starting a consultation.

Parameter

Type

Required

Description

question

string

Yes

The question to refine

context

string

No

Additional context

Example:

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

consult_advisor

Start an interactive advisor session for brainstorming or scoping problems.

Parameter

Type

Required

Description

question

string

Yes

The initial topic or question

Usage Examples

Strategic Decision Making

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

Question Refinement

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

Checking Consultation Progress

Check the status of consultation abc-123-def

Configuration

Environment Variables

Variable

Default

Description

COUNSEL_API_URL

https://counsel.getmason.dev

Counsel API base URL

PORT

3000

Server port (HTTP mode)

CLI Commands

# 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)

Troubleshooting

"Tool not found" Error

Ensure the MCP server is properly configured in your client. Restart your client after adding the configuration.

Authentication Issues

  1. Check that you have a valid Counsel account

  2. Try removing and re-adding the MCP server configuration

  3. Clear your client's MCP cache if available

Connection Refused

If running in HTTP mode, ensure:

  • The server is running (npx counsel-mcp-server start)

  • The port isn't blocked by a firewall

  • No other process is using the same port

Server Not Starting

# Check Node.js version (requires 18+) node --version # Try running directly to see errors npx counsel-mcp-server start

Debug Mode

For verbose logging, check your MCP client's logs or run the server directly in a terminal to see output.

Development

Prerequisites

  • Node.js 18+

  • npm 9+

Setup

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

Commands

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

Security

This project includes automated secret detection:

  • Pre-commit hook: Automatically scans staged files before each commit

  • CI integration: Security checks run on all pull requests

  • Pattern detection: AWS keys, GitHub tokens, API keys, private keys, etc.

See CONTRIBUTING.md for details.

Project Structure

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

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Start

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/your-feature

  3. Make your changes and add tests

  4. Run npm test to ensure tests pass

  5. Submit a pull request

License

MIT License - see LICENSE for details.

Links

This server cannot be installed

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mercurialsolo/counsel-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server