Counsel MCP Server

An open-sourceModel Context Protocol (MCP)server that connects AI agents to theCounselAPI for strategic reasoning and multi-perspective analysis.

- Quick Start (Hosted)
- Installation (Self-Hosted)

- Claude Desktop
- Claude Code (CLI)
- Cursor
- Windsurf
- VS Code with Copilot
- Other MCP Clients

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

Run your own instance of the Counsel MCP server locally.
- Node.js 18+installed on your system
- ACounsel accountatcounsel.getmason.dev

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

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

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

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

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

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

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

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

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

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

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" } } } }

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

- MCP endpoint:http://localhost:3000/mcp
- OAuth discovery:http://localhost:3000/.well-known/oauth-authorization-server

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

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

The server supports two authentication modes:

Set theCOUNSEL_API_KEYenvironment variable with your API key fromcounsel.getmason.dev:

export COUNSEL_API_KEY=your_api_key_here

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

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

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

The server exposes standard OAuth 2.0 endpoints:

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

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

Check the status of an ongoing consultation.

Retrieve the final synthesis report from a completed consultation.

Refine and improve a strategic question before starting a consultation.

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

Start an interactive advisor session for brainstorming or scoping problems.

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

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

Check the status of consultation abc-123-def

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

Ensure the MCP server is properly configured in your client. Restart your client after adding the configuration.
- 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

- 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

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

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

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

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

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.

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

We welcome contributions! SeeCONTRIBUTING.mdfor guidelines.
- Fork the repository
- Create a feature branch:git checkout -b feature/your-feature
- Make your changes and add tests
- Runnpm testto ensure tests pass
- Submit a pull request

- Counsel Platform- Strategic reasoning platform
- MCP Specification- Model Context Protocol documentation
- GitHub Issues- Report bugs or request features
- GitHub Discussions- Ask questions

Complete Swiss accounting integration for Bexio via MCP. Works with Claude Desktop, n8n, and any MCP client. 221 tools for invoices, contacts, projects & more.