@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
- Sign in to Councly
- Go to Settings > MCP Integration
- Create a new API key
- 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
License
Apache 2.0 - See LICENSE