Counsel

You can connect AI agents to Counsel’s strategic reasoning through this MCP server. It supports both hosted and self-hosted modes, offers multi-perspective analysis, and handles authentication automatically for HTTP transport or via API keys for STDIO transport, giving you flexible ways to integrate Counsel into your tooling and workflows.

How to use

You use the Counsel MCP Server by connecting your MCP client to the server via either HTTP or STDIO transport. In HTTP mode, your client talks to the server over a web URL and relies on OAuth 2.0 for authentication. In STDIO mode, the server runs locally and your client communicates through standard input/output, often using an API key for authentication.

How to install

Prerequisites: Install Node.js 18 or newer on your system. Ensure you have a Counsel account at counsel.getmason.dev.

Self-hosted installation steps provided here assume you will run the MCP server locally and connect your client via STDIO or HTTP transport.

STDIO (local) setup to start the server with an API key:

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

HTTP (remote) setup to run the HTTP server and connect a client over HTTP:

# Start the HTTP server
npx -y counsel-mcp-server http --port 3000

After starting in HTTP mode, configure your MCP client to connect to the HTTP endpoint at http://localhost:3000/mcp with transport set to http.

Configuration and practical setup notes

Quick hosted option to connect without installation is available at http://counsel-mcp.getmason.dev/mcp. If your client supports HTTP transport, you can point to that URL and specify the same path in your client configuration.

Other important configurations

STDIO mode uses an API key via the COUNSEL_API_KEY environment variable. HTTP mode uses OAuth 2.0 with automatic token management handled by the client.

Authentication modes

STDIO mode: set COUNSEL_API_KEY to your Counsel API key. You can also include it in the client MCP configuration.

HTTP mode: OAuth 2.0 is used. When you first access a Counsel tool through the client, you’ll authenticate in a browser flow and tokens are managed automatically.

Available tools and usage patterns

The Counsel MCP Server exposes a set of tools that support starting consultations, refining questions, checking progress, and interactive advisor sessions. You can start strategic consultations, sharpen questions for clarity, review consultation status, and retrieve final reports.

Troubleshooting

If you encounter a connectivity issue, verify the transport mode (HTTP vs STDIO) and ensure the server is running on the expected port. For HTTP mode, confirm OAuth flow completes in the client and tokens are being managed. For STDIO mode, verify the API key is correct and present in the environment. Restart the client after changing configurations.

Notes on security and environment

Authentication is handled by the client in HTTP mode and requires an OAuth-enabled flow. In STDIO mode, keep your API key secure and do not share it in logs or screenshots.

Available tools

start_consultation

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

get_consultation_status

Check the current status of an ongoing consultation by debate ID.

get_consultation_report

Retrieve the final synthesis report for a completed consultation.

list_consultations

List past consultations with optional limit.

sharpen_question

Refine and improve a strategic question before starting a consultation.

consult_advisor

Start an interactive advisor session for brainstorming or scoping problems.