mercurialsolo/counsel-mcp

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
---
Table of Contents
- 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:
For MCP clients that support HTTP transport, simply add:
OAuth authentication is handled automatically by your MCP client.
---
Installation (Self-Hosted)
Run your own instance of the Counsel MCP server locally.
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:
macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
Claude Code (CLI)
Or manually add to your MCP settings:
Cursor
Add to your Cursor MCP configuration (.cursor/mcp.json in your project or global settings):
Windsurf
Add to your Windsurf MCP configuration:
VS Code with Copilot
Add to your VS Code settings (settings.json):
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:
HTTP Mode with OAuth
For clients that support HTTP transport with OAuth 2.0, run the server separately:
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:
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:
Or add it to your MCP client configuration:
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 |