@councly/mcp

MCP (Model Context Protocol) server for Councly - Multi-LLM Council Hearings.

Enable Claude Code, Codex, and other MCP-compatible AI assistants to invoke council hearings where multiple LLMs (Claude, GPT, Gemini, Grok) debate topics and synthesize verdicts.

Installation

npm install -g @councly/mcp

Or use directly with npx:

npx @councly/mcp

Setup

1. Get an API Key

1. Sign in to Councly
2. Go to Settings > MCP Integration
3. Create a new API key
4. Copy the key (shown only once)

2. Configure Claude Code

Add to your Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "councly": {
      "command": "npx",
      "args": ["@councly/mcp"],
      "env": {
        "COUNCLY_API_KEY": "cnc_your_key_here"
      }
    }
  }
}

3. Configure Codex CLI

export COUNCLY_API_KEY=cnc_your_key_here

Or add to your shell profile.

Tools

councly_hearing

Create a council hearing where multiple LLMs debate a topic.

Parameters:

Parameter	Type	Required	Default	Description
subject	string	Yes	-	The topic to discuss (10-10000 chars)
preset	string	No	balanced	Model preset: balanced, fast, coding, coding_plus
workflow	string	No	auto	Workflow: auto, discussion, review, brainstorming
wait	boolean	No	true	Wait for completion
timeout_seconds	number	No	300	Max wait time (30-600)

Presets:

Preset	Credits	Counsels	Best For
balanced	9	3	General purpose discussions
fast	6	3	Quick responses, simple topics
coding	14	3	Code review, technical decisions
coding_plus	17	4	Complex code problems

Example:

Use councly_hearing with subject="Review this Python function for security issues:

def authenticate(username, password):
    query = f'SELECT * FROM users WHERE username='{username}' AND password='{password}''
    return db.execute(query)

" and preset="coding"

councly_status

Check the status of a hearing.

Parameters:

Parameter	Type	Required	Description
hearing_id	string (uuid)	Yes	The hearing ID

Example:

Use councly_status with hearing_id="550e8400-e29b-41d4-a716-446655440000"

Response Format

Completed hearings return:

• Status: completed, failed, or early_stopped
• Verdict: Synthesized conclusion from the moderator
• Trust Score: 0-100 confidence rating
• Counsel Perspectives: Summary from each counsel
• Cost: Credits used

Error Handling

Common errors:

Code	Description
INSUFFICIENT_BALANCE	Not enough credits
ACTIVE_HEARING_EXISTS	One hearing already in progress
RATE_LIMIT_EXCEEDED	Too many requests
CONTENT_BLOCKED	Subject contains prohibited content

Environment Variables

Variable	Required	Description
COUNCLY_API_KEY	Yes	Your MCP API key
COUNCLY_BASE_URL	No	API base URL (default: https://councly.ai)

Pricing

Councly uses a credit-based pricing model:

• 1 credit = $0.01 USD
• Credits are deducted at hearing creation
• Failed hearings are refunded

Purchase credits at councly.ai/billing.

Links

• Councly Website
• Documentation
• API Reference
• GitHub Issues

License

Apache 2.0 - See LICENSE