counsel MCP Server

![npm version](https://www.npmjs.com/package/counsel-mcp-server) ![License: MIT](https://opensource.org/licenses/MIT) ![Node.js Version](https://nodejs.org)

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

Features

Hosted & Self-Hosted - Use the hosted server instantly or run your own instance
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
Dual Transport - STDIO for local clients, HTTP for web clients and shared servers

---

Quick Start (Hosted)
Installation (Self-Hosted)
Claude Desktop
Claude Code (CLI)
Cursor
Windsurf
VS Code with Copilot
Other MCP Clients
Authentication
Available Tools
Usage Examples
Configuration
Troubleshooting
Development
Contributing
License

---

Quick Start (Hosted)

Connect instantly to the hosted Counsel MCP server - no installation required:

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

For MCP clients that support HTTP transport, simply add:

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

OAuth authentication is handled automatically by your MCP client.

---

Installation (Self-Hosted)

Run your own instance of the Counsel MCP server locally.

Prerequisites

Node.js 18+ installed on your system
A Counsel account at counsel.getmason.dev

Claude Desktop

Add to your claude_desktop_config.json:

<details> <summary><b>macOS</b>: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></summary>

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

</details>

<details> <summary><b>Windows</b>: <code>%APPDATA%\Claude\claude_desktop_config.json</code></summary>

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

</details>

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

The server supports two transport modes. Choose based on your client's capabilities:

STDIO Mode (Default)

Most MCP clients use STDIO transport. Configure with:

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

HTTP Mode with OAuth

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

# Start the HTTP server
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 to connect:

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

HTTP mode uses OAuth 2.0 with automatic token management - no API key required.

Transport Comparison

| Feature | STDIO Mode | HTTP Mode | |---------|------------|-----------| | Command | npx -y counsel-mcp-server start | npx -y counsel-mcp-server http | | Auth | API key via env var | OAuth 2.0 (automatic) | | Setup | Single config | Run server + configure client | | Best for | Claude Desktop, Cursor, VS Code | Web clients, shared servers |

---

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: ``json { "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:

When you first use a Counsel tool, your MCP client will prompt for authentication
You'll be redirected to sign in with your Counsel account
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

Check that you have a valid Counsel account
Try removing and re-adding the MCP server configuration
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

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes and add tests
Run npm test to ensure tests pass
Submit a pull request

---

License

MIT License - see LICENSE for details.

---

counsel-mcp