An open-source Model Context Protocol (MCP) server that connects AI agents to the Counsel API for strategic reasoning and multi-perspective analysis. - 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
Add this skill
npx mdskills install mercurialsolo/counsel-mcpConnects AI agents to strategic reasoning API with solid OAuth integration and comprehensive setup docs
1# Counsel MCP Server23[](https://www.npmjs.com/package/counsel-mcp-server)4[](https://opensource.org/licenses/MIT)5[](https://nodejs.org)67An open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects AI agents to the [Counsel](https://counsel.getmason.dev) API for strategic reasoning and multi-perspective analysis.89## Features1011- **Hosted & Self-Hosted** - Use the hosted server instantly or run your own instance12- **Strategic Reasoning** - Access Counsel's debate and multi-perspective reasoning engines13- **Advisor Sessions** - Run interactive intake and profile tuning sessions14- **Native OAuth 2.0** - Standard MCP authentication handled automatically by clients15- **Dual Transport** - STDIO for local clients, HTTP for web clients and shared servers1617---1819## Table of Contents2021- [Quick Start (Hosted)](#quick-start-hosted)22- [Installation (Self-Hosted)](#installation-self-hosted)23 - [Claude Desktop](#claude-desktop)24 - [Claude Code (CLI)](#claude-code-cli)25 - [Cursor](#cursor)26 - [Windsurf](#windsurf)27 - [VS Code with Copilot](#vs-code-with-copilot)28 - [Other MCP Clients](#other-mcp-clients)29- [Authentication](#authentication)30- [Available Tools](#available-tools)31- [Usage Examples](#usage-examples)32- [Configuration](#configuration)33- [Troubleshooting](#troubleshooting)34- [Development](#development)35- [Contributing](#contributing)36- [License](#license)3738---3940## Quick Start (Hosted)4142Connect instantly to the hosted Counsel MCP server - no installation required:4344```45http://counsel-mcp.getmason.dev/mcp46```4748For MCP clients that support HTTP transport, simply add:4950```json51{52 "mcpServers": {53 "counsel": {54 "url": "http://counsel-mcp.getmason.dev/mcp",55 "transport": "http"56 }57 }58}59```6061OAuth authentication is handled automatically by your MCP client.6263---6465## Installation (Self-Hosted)6667Run your own instance of the Counsel MCP server locally.6869### Prerequisites70711. **Node.js 18+** installed on your system722. A **Counsel account** at [counsel.getmason.dev](https://counsel.getmason.dev)7374### Claude Desktop7576Add to your `claude_desktop_config.json`:7778<details>79<summary><b>macOS</b>: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></summary>8081```json82{83 "mcpServers": {84 "counsel": {85 "command": "npx",86 "args": ["-y", "counsel-mcp-server", "start"]87 }88 }89}90```9192</details>9394<details>95<summary><b>Windows</b>: <code>%APPDATA%\Claude\claude_desktop_config.json</code></summary>9697```json98{99 "mcpServers": {100 "counsel": {101 "command": "npx",102 "args": ["-y", "counsel-mcp-server", "start"]103 }104 }105}106```107108</details>109110### Claude Code (CLI)111112```bash113claude mcp add counsel -- npx -y counsel-mcp-server start114```115116Or manually add to your MCP settings:117118```json119{120 "mcpServers": {121 "counsel": {122 "command": "npx",123 "args": ["-y", "counsel-mcp-server", "start"]124 }125 }126}127```128129### Cursor130131Add to your Cursor MCP configuration (`.cursor/mcp.json` in your project or global settings):132133```json134{135 "mcpServers": {136 "counsel": {137 "command": "npx",138 "args": ["-y", "counsel-mcp-server", "start"]139 }140 }141}142```143144### Windsurf145146Add to your Windsurf MCP configuration:147148```json149{150 "mcpServers": {151 "counsel": {152 "command": "npx",153 "args": ["-y", "counsel-mcp-server", "start"]154 }155 }156}157```158159### VS Code with Copilot160161Add to your VS Code settings (`settings.json`):162163```json164{165 "mcp.servers": {166 "counsel": {167 "command": "npx",168 "args": ["-y", "counsel-mcp-server", "start"]169 }170 }171}172```173174### Other MCP Clients175176The server supports two transport modes. Choose based on your client's capabilities:177178#### STDIO Mode (Default)179180Most MCP clients use STDIO transport. Configure with:181182```json183{184 "mcpServers": {185 "counsel": {186 "command": "npx",187 "args": ["-y", "counsel-mcp-server", "start"],188 "env": {189 "COUNSEL_API_KEY": "your_api_key_here"190 }191 }192 }193}194```195196#### HTTP Mode with OAuth197198For clients that support HTTP transport with OAuth 2.0, run the server separately:199200```bash201# Start the HTTP server202npx -y counsel-mcp-server http --port 3000203```204205This starts an HTTP server with:206- **MCP endpoint**: `http://localhost:3000/mcp`207- **OAuth discovery**: `http://localhost:3000/.well-known/oauth-authorization-server`208209Then configure your client to connect:210211```json212{213 "mcpServers": {214 "counsel": {215 "url": "http://localhost:3000/mcp",216 "transport": "http"217 }218 }219}220```221222HTTP mode uses OAuth 2.0 with automatic token management - no API key required.223224#### Transport Comparison225226| Feature | STDIO Mode | HTTP Mode |227|---------|------------|-----------|228| **Command** | `npx -y counsel-mcp-server start` | `npx -y counsel-mcp-server http` |229| **Auth** | API key via env var | OAuth 2.0 (automatic) |230| **Setup** | Single config | Run server + configure client |231| **Best for** | Claude Desktop, Cursor, VS Code | Web clients, shared servers |232233---234235## Authentication236237The server supports two authentication modes:238239### STDIO Mode (Default)240241Set the `COUNSEL_API_KEY` environment variable with your API key from [counsel.getmason.dev](https://counsel.getmason.dev):242243```bash244export COUNSEL_API_KEY=your_api_key_here245```246247Or add it to your MCP client configuration:248```json249{250 "mcpServers": {251 "counsel": {252 "command": "npx",253 "args": ["-y", "counsel-mcp-server", "start"],254 "env": {255 "COUNSEL_API_KEY": "your_api_key_here"256 }257 }258 }259}260```261262### HTTP Mode (OAuth 2.0)263264When running in HTTP mode (`npx -y counsel-mcp-server http`), authentication is handled automatically through OAuth 2.0:2652661. When you first use a Counsel tool, your MCP client will prompt for authentication2672. You'll be redirected to sign in with your Counsel account2683. After authorization, tokens are managed automatically269270**No manual API key required** in HTTP mode - your MCP client handles the entire OAuth flow.271272### OAuth Endpoints (HTTP Mode)273274The server exposes standard OAuth 2.0 endpoints:275276| Endpoint | Description |277|----------|-------------|278| `/.well-known/oauth-authorization-server` | OAuth metadata discovery |279| `/authorize` | Authorization endpoint |280| `/token` | Token exchange endpoint |281| `/register` | Dynamic client registration |282283---284285## Available Tools286287### `start_consultation`288289Start a new strategic consultation (debate) to analyze a complex question with multiple perspectives.290291| Parameter | Type | Required | Description |292|-----------|------|----------|-------------|293| `question` | string | Yes | The core question to analyze |294| `context` | string | No | Additional context about the situation |295| `mode` | enum | No | Depth of analysis: `quick`, `standard` (default), `deep` |296| `stakeholders` | string[] | No | Key stakeholders to consider |297298**Example:**299```300Start a consultation about "Should we migrate our monolith to microservices?"301with context about our 50-person engineering team and mode set to deep302```303304### `get_consultation_status`305306Check the status of an ongoing consultation.307308| Parameter | Type | Required | Description |309|-----------|------|----------|-------------|310| `debate_id` | string | Yes | The ID of the consultation |311312### `get_consultation_report`313314Retrieve the final synthesis report from a completed consultation.315316| Parameter | Type | Required | Description |317|-----------|------|----------|-------------|318| `debate_id` | string | Yes | The ID of the consultation |319320### `list_consultations`321322List your past consultations.323324| Parameter | Type | Required | Description |325|-----------|------|----------|-------------|326| `limit` | number | No | Number of results (default: 10) |327328### `sharpen_question`329330Refine and improve a strategic question before starting a consultation.331332| Parameter | Type | Required | Description |333|-----------|------|----------|-------------|334| `question` | string | Yes | The question to refine |335| `context` | string | No | Additional context |336337**Example:**338```339Sharpen this question: "Is AI good for our company?"340```341342### `consult_advisor`343344Start an interactive advisor session for brainstorming or scoping problems.345346| Parameter | Type | Required | Description |347|-----------|------|----------|-------------|348| `question` | string | Yes | The initial topic or question |349350---351352## Usage Examples353354### Strategic Decision Making355356```357Use Counsel to analyze: "Should we expand into the European market in 2025?"358359Consider these stakeholders: CEO, CFO, Head of Sales, Legal360Use deep analysis mode361```362363### Question Refinement364365```366Use the sharpen_question tool to improve this question:367"How do we fix our culture?"368369Context: We're a 200-person startup experiencing rapid growth370```371372### Checking Consultation Progress373374```375Check the status of consultation abc-123-def376```377378---379380## Configuration381382### Environment Variables383384| Variable | Default | Description |385|----------|---------|-------------|386| `COUNSEL_API_URL` | `https://counsel.getmason.dev` | Counsel API base URL |387| `PORT` | `3000` | Server port (HTTP mode) |388389### CLI Commands390391```bash392# STDIO mode (default) - for most MCP clients393npx -y counsel-mcp-server start394395# HTTP mode - for clients supporting OAuth396npx -y counsel-mcp-server http [options]397398HTTP Options:399 -p, --port <port> Port to listen on (default: 3000)400 --host <host> Host to bind to (default: localhost)401```402403---404405## Troubleshooting406407### "Tool not found" Error408409Ensure the MCP server is properly configured in your client. Restart your client after adding the configuration.410411### Authentication Issues4124131. Check that you have a valid Counsel account4142. Try removing and re-adding the MCP server configuration4153. Clear your client's MCP cache if available416417### Connection Refused418419If running in HTTP mode, ensure:420- The server is running (`npx counsel-mcp-server start`)421- The port isn't blocked by a firewall422- No other process is using the same port423424### Server Not Starting425426```bash427# Check Node.js version (requires 18+)428node --version429430# Try running directly to see errors431npx counsel-mcp-server start432```433434### Debug Mode435436For verbose logging, check your MCP client's logs or run the server directly in a terminal to see output.437438---439440## Development441442### Prerequisites443444- Node.js 18+445- npm 9+446447### Setup448449```bash450git clone https://github.com/mercurialsolo/counsel-mcp.git451cd counsel-mcp-server452npm install453npm run build454```455456### Commands457458```bash459npm run build # Compile TypeScript460npm run dev # Watch mode461npm run start # Run server462npm test # Run tests463npm run lint # Type check464npm run security:check # Scan staged files for secrets465npm run security:check:all # Scan all files for secrets466```467468### Security469470This project includes automated secret detection:471472- **Pre-commit hook**: Automatically scans staged files before each commit473- **CI integration**: Security checks run on all pull requests474- **Pattern detection**: AWS keys, GitHub tokens, API keys, private keys, etc.475476See [CONTRIBUTING.md](CONTRIBUTING.md#security-checks) for details.477478### Project Structure479480```481src/482├── index.ts # HTTP server, OAuth proxy, MCP transport483├── client.ts # API client with request-scoped auth484├── config.ts # Environment configuration485└── tools/486 ├── debates.ts # Consultation tools487 └── advisor.ts # Advisor session tools488```489490---491492## Contributing493494We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.495496### Quick Start4974981. Fork the repository4992. Create a feature branch: `git checkout -b feature/your-feature`5003. Make your changes and add tests5014. Run `npm test` to ensure tests pass5025. Submit a pull request503504---505506## License507508MIT License - see [LICENSE](LICENSE) for details.509510---511512## Links513514- [Counsel Platform](https://counsel.getmason.dev) - Strategic reasoning platform515- [MCP Specification](https://modelcontextprotocol.io) - Model Context Protocol documentation516- [GitHub Issues](https://github.com/mercurialsolo/counsel-mcp/issues) - Report bugs or request features517- [GitHub Discussions](https://github.com/mercurialsolo/counsel-mcp/discussions) - Ask questions518
Full transparency — inspect the skill content before installing.