Documentation

Getting Started

Run your first council query in under a minute. No setup required.

1. Type your question

   Enter any high-stakes question into the query box on the home page. Be specific: include context, constraints, and what kind of recommendation you need. For example: "Should we migrate our monolith to microservices given a 6-person engineering team and $2M ARR?"

2. Choose a panel

   Select a panel of expert agents from the dropdown. Each panel is a curated group of AI specialists tuned for a specific domain. The Default Panel (Strategist, Risk Analyst, Devil's Advocate) works for most general questions. Pick a specialized panel for domain-specific queries.

3. Review the results

   Each agent delivers an independent analysis with a recommendation, confidence score, key considerations, and risks. A synthesis step combines all opinions into a single decision document with an executive summary, action plan, and risk matrix. Expand any agent card to see their full reasoning.

Panels

A panel is a curated group of expert AI agents that deliberate on your query in parallel. Each panel is designed for a specific domain or decision type.

How panels work

When you run a council, every agent on the selected panel independently analyzes your query using their unique expertise, analytical framework, and persona. Each agent has a weight that determines how much influence they have on the final synthesis. Some agents are marked required, meaning they always participate and may hold veto authority (for example, the Safety Officer).

Available panels

Plus specialized geopolitical scenario panels. New panels are added regularly.

Workflows

Workflows are multi-step decision pipelines with human review between each stage. Unlike a single council query, workflows chain multiple councils together in a structured sequence.

Councils vs. workflows

A council is a single round of multi-expert deliberation: you ask a question, agents analyze it in parallel, and a synthesis combines their opinions. A workflow is a sequence of councils and processing steps that tackle a complex process end-to-end.

For example, a "Due Diligence" workflow might run four stages: financial analysis, legal review, technical assessment, and a final synthesis. Each stage can use a different panel, and you can review and refine between stages.

When to use workflows

Use a workflow when your decision requires multiple phases that build on each other, when you need human review checkpoints, or when the process is standardized enough to template. Examples:

• Product launch planning (market analysis, technical feasibility, go-to-market)
• Incident postmortem (timeline, root cause, remediation, prevention)
• TDD development (requirements, test design, implementation, review)
• RFP response (requirements parsing, solution design, pricing, final assembly)

Running a workflow

Select the "Workflows" tab in the main interface. Browse available templates, pick one, and fill in your context. The workflow guides you through each stage, showing progress and letting you adjust inputs between steps.

Custom Agents

Create expert agents tailored to your organization's specific domain knowledge and decision-making needs.

What defines an agent

Every agent is a Markdown template with YAML frontmatter. The frontmatter defines metadata (name, role, expertise tags, default weight), and the body is a system prompt that shapes the agent's persona, analytical framework, and output style.

Creating a custom agent

In the web interface, go to the Agents page and click "Create Agent." You can define:

• Name and role -- The agent's title and professional identity
• Expertise -- Domain tags that help match agents to queries
• Analytical framework -- The step-by-step methodology the agent follows
• Decision criteria -- What the agent optimizes for (safety, ROI, speed, etc.)
• Weight -- How much influence this agent has in the synthesis (default 1.0)
• Model -- Optionally override which LLM this agent uses

Sharing and forking

Agents can be shared via the marketplace. You can fork any public agent, customize it, and add it to your panels. All agents support version tracking.

API Reference

Integrate Meta Council into your existing tools and workflows with the REST API. All endpoints accept and return JSON.

Base URL

All paths below are relative to this base. The Developer API (v1) uses /api/v1 instead.

Authentication

Two methods are supported, but they are scoped to different endpoint families and are not interchangeable on the same request:

API keys use the mc_ prefix and are shown only once at creation time. Store them securely.

Rate limits

Council runs are also capped per day: 5/day on Free, 50/day on Pro, 2,000/day on Enterprise. Requests to /api/v1/* endpoints share a flat 120 requests/minute limit per API key, applied identically across all tiers (configurable via API_KEY_RATE_PER_MIN on self-hosted deployments). A few specific endpoints carry small fixed per-IP limits regardless of tier: POST /api/council/run 10/min, file upload 3/min, Laws & Regulations research 5/min, workflow goal-parse 10/min, workflow start 5/min, registration 10/hour. Ticket-validation ingestion independently limits source-IP and authenticated-actor attempts to 60/min by default (self-hosted setting TICKET_VALIDATION_ATTEMPTS_PER_MIN). Most other endpoints have no explicit rate limit.

When you exceed a limit, the response is 429 Too Many Requests with a Retry-After header giving the number of seconds to wait before retrying.

Response format

All responses are JSON. Successful responses return a top-level object. Errors return {"detail": "error message"} with an appropriate HTTP status code. See Error Handling below.

Council API

The core product. Start a multi-expert council session, poll for results, and retrieve agent/panel metadata.

Workflow API

Multi-step decision pipelines with human checkpoints. Chain multiple council sessions together in a structured sequence.

Workflow Schedules API

Schedule workflows to run automatically on a recurring basis. Useful for periodic reviews, monitoring, and automated reporting.

History & Sharing

Access past council sessions and their full results. Public sessions are accessible at /s/{session_id} in the browser.

Settings & Keys

Manage your account settings, provider API keys, model preferences, and developer API keys.

Developer API (v1)

A simplified interface for programmatic access. Uses the /api/v1/ prefix with API key authentication for every endpoint except key management (create/list/revoke), which requires your account JWT. Designed for integrations, automation pipelines, and AI agent toolchains.

Endpoint summary

Quick start: end-to-end cURL example

Request body: /api/v1/councils/run

Session status values

MCP Server

Use Meta Council as a tool from Claude Code, Cursor, Windsurf, or any MCP-compatible AI agent.

The hosted MCP source candidate defines 108 tools for councils, workflows, catalog discovery, deterministic LOCUS calculation, citation-grounded Laws & Regulations research, settings reads, governed Sales/outreach, the private ticket board, feature feedback, and owner-private Accounting, Invoicing, Marketing, and Consulting workspaces. The current repository transport identifies as server 2.5.0; that version and this tool count are source facts, and neither by itself proves what production currently serves — an endpoint one release behind serves the previous count. Ticket planning and atomic batch tools use preview tokens, caller-stable idempotency keys, and deterministic IDs so uncertain commit retries cannot duplicate a tree. Separately scoped ticket validation records immutable evidence-backed results without fetching evidence locators or echoing evidence payloads. Accounting runs deterministic analysis with encrypted audit records and explicit stable-ticket preview/commit; it never files, pays, or sends externally. Marketing covers brands, audiences, campaigns, immutable content revisions, a planning calendar, draft submission, and separately scoped approval. Consulting covers clients, engagements, revision-safe proposals and SOWs, milestones, and internal deliverables with independent approval. None of these workspaces publishes, shares, sends, or deletes beyond its explicit private lifecycle controls. Long-running tools start asynchronously and return a session ID to poll. Authenticated sessions, audit runs, and artifacts are private by default.

Hosted Streamable HTTP

The hosted endpoint uses scoped, expiring developer keys. Four catalog tools (list_panels, list_agents, list_workflows, and get_agent_detail) are anonymous; every query-bearing, tenant-bearing, clinical, Laws & Regulations, Accounting, Marketing, Consulting, ticketing, settings, or outreach operation requires the relevant scope. MCP OAuth is not implemented yet, so clients that require OAuth account linking need a compatible HTTP-to-stdio bridge.

The hosted server is active in the official MCP Registry as com.meta-council/decision-intelligence version 1.4.0. Configure the URL and scoped key explicitly because the listing does not provision credentials.

Common MCP tools

Laws & Regulations: agent-first research

The product surface is Laws & Regulations. The stable MCP tool remains ask_legal and requires legal:run. The equivalent REST routes remain POST /api/legal/plan for a deterministic provider-free proposed plan and POST /api/legal/ask for fixed Themis retrieval with that unexecuted plan attached. The plan's agent, model/effort, source, and synthesis routes report planned_not_run; the planner does not execute them.

See what Themis says (research_mode: "themis") requires a signed-in user, the exact operator capability THEMIS_NEUTRAL_SCHEMA_VERSION=themis_neutral_research/v1, the LEGAL_ALLOW_LLM gate, and an atomic reservation from the finite daily spend breaker. Themis must return that exact neutral evidence schema: provider assertions contain only IDs, enumerated kind/topic codes, and evidence IDs; gaps are enum codes. The server expands fixed neutral templates, and every referenced quote must be verified. Missing capability or policy admission fails with 503; free-form or otherwise nonconforming generated material fails with 502 and is withheld. A valid extractive fallback is labeled check_law with a degradation_reason. Legacy verdict and answer_text prose is never exposed.

The result includes bounded source/citation records and evidence_graph (legal_evidence_graph/v1), whose assertions link to evidence IDs and whose gaps preserve missing or unverified support. It also adds workflow_plan (proposed domains/jurisdictions, agents, model/effort routing, source checks, and neutral synthesis constraints, all unexecuted), research_metadata (requested/effective mode, quality, degradation, and corpus_status), and platform_disclaimer. If no valid corpus-update timestamp is reported, freshness is not_reported and must be treated as unknown—not inferred from deployment time or model confidence.

Accounting: private deterministic audit runs and stable tickets

Six owner-scoped tools analyze supported textual records, retain an encrypted audit trail, and explicitly preview/commit dollar-free work-plan projections onto the private ticket board. Grant accounting:read for list/get, accounting:write for create/delete, and combine accounting:read with tickets:read for preview or tickets:write for commit. These grants never appear on default or legacy keys.

Outreach: read the pipeline

Six read tools let an agent inspect your sales pipeline. All require the outreach:read scope and are strictly scoped to your own campaigns and leads.

Outreach: drive the pipeline (governed writes)

Six write tools let an agent move the pipeline forward — create a campaign, add and organize leads, advance a lead's status, and draft copy. They all require the dedicated outreach:agent_write scope and are governed by design:

• Least-privilege scope. These tools use outreach:agent_write, a scope that is deliberately narrower than outreach:write: a key granted only outreach:agent_write can drive the pipeline through MCP but cannot call the REST live-send or delete endpoints (those still require the broader outreach:write). Grant your agent this scope alone to keep sending and deletion off the table entirely. A full outreach:write key remains a superset and also works.
• Auth-gated & user-scoped. Every write is filtered by your user id / campaign owner id — an agent can only touch your own campaigns, leads, and pitches.
• Honest provenance. Leads and pitches created over MCP are stamped source="agent" server-side. The caller cannot override this — source is not an accepted argument, so an agent can never label its work as human-authored.
• Reversible only. No destructive operations are exposed over MCP — there are no delete tools. Everything an agent creates can be reviewed and removed from the dashboard.
• No live send. There is deliberately no send tool. An agent can draft and stage a lead all the way to "ready," but a human triggers the actual email send from the dashboard.

Marketing workspace

Twenty-one owner-scoped tools cover Brand, Audience, Marketing Campaign, Content Asset, revision, calendar, and review workflows. marketing:read reads private context; marketing:agent_write creates/updates/submits drafts; the separate marketing:approve scope approves or rejects an exact submitted revision.

• Immutable review. Submitting freezes the revision. Approval records the exact SHA-256 content hash; later edits become a new draft revision.
• Separation of duties. Draft authority cannot approve, and reviewer authority cannot author drafts unless the key is explicitly granted both scopes.
• Private and non-destructive. Every lookup is filtered to the API-key owner. No Marketing delete/archive tool is exposed over MCP.
• No publishing side effect. Calendar dates are planning metadata. There is no publish or send tool or scope.

Ticket board

Ten tools expose the in-platform ticket board. The two read tools require the tickets:read scope; seven planning and mutation tools require tickets:write, which is a superset that also satisfies tickets:read. The tenth, ticket_validation_finalize, requires the separate opt-in tickets:validate scope and does not imply read or write access. A prompt-only ticket_plan preview additionally requires councils:run because it invokes the configured planner and may consume model budget; supplied-plan preview and commit are provider-free. Plan and batch preview return a normalized commit_payload, deterministic IDs, and an exact preview_token. Commit combines those values with the caller-held idempotency key; retrying the exact commit returns the same IDs without duplicates. Per-owner ingress, weighted-row, live-ticket, and durable idempotency-ledger quotas bound bulk use while preserving exact replay at the storage cap.

ticket_list returns owner/filter-bound cursor pages of at most 200 rows. Reuse next_cursor with unchanged filters. Stable creation-time/UUID ordering keeps a full-board walk exact while already-returned tickets are edited, reordered, or moved. This is not a database snapshot: concurrent creation/deletion or hierarchy changes that alter recursive-subtree membership can affect later pages. With recursive=true, an owned UUID parent_id returns every descendant as one flat, cycle-safe set and excludes the anchor; the default remains direct children. scope selects active (the default), archived, or all; archiving is a flag rather than a status, so an archived ticket keeps whatever status it had and ticket_get still resolves it by id or unambiguous prefix.

ticket_validation_finalize commits one terminal verdict for an exact scenario version and lowercase SHA-256 scenario hash. Owner and actor are derived from the API key; callers cannot supply either. Evidence payloads are bounded opaque JSON: locator-looking URLs and paths are never fetched, opened, or resolved. Public adapters admit at most 10,000 JSON nodes per payload and 100,000 evidence JSON nodes across a request. An exact visible-ASCII idempotency-key retry by the same credential actor returns the original committed run; a rotated key is a different actor, and changed actor or content returns a stable conflict. Receipts are compact and never echo payloads: they contain evidence sequence/kind/digest entries plus the evidence count and manifest hash. The REST request is capped at 5 MiB before parsing; REST source-IP and credential/session actors are rate-limited independently. Hosted MCP retains its own transport IP/key ceilings plus the validation-actor ceiling. Durable limits retain at most 10,000 runs, 100,000 evidence items, and 268,435,456 canonical evidence-JSON characters per owner, plus 1,000 runs per scenario; the character ceiling bounds UTF-8 storage to at most four times that count.

The equivalent REST route is POST /api/tickets/{ticket_id}/scenarios/{scenario_id}/validation-runs. It accepts a user JWT or an API key carrying tickets:validate; both owner and actor still come only from that verified credential/session. The server acknowledges success only after commit.

Create, update, and get share the full ticket field set, including parent, session/workflow metadata links, labels, acceptance criteria, effort points, order index, and external references. Explicit clear flags safely remove optional links and effort points. Jira/Linear synchronization, Accounting, plan, and batch references are protected system metadata and cannot be spoofed, changed, or removed through generic MCP ticket writes. Session/workflow ids are metadata only, not access grants. Creator, comment-author, and mutation-trail identities are stamped server-side as api_key:<UUID> from the key that actually made the request; callers cannot provide them.

Consulting workspace

Seventeen tools expose only the API-key owner's consulting records. Reads require consulting:read; drafting and workflow updates require consulting:write (which also satisfies reads); approvals require consulting:approve, the exact fetched version and content_hash, and a credential different from the last editor. Use separate writer and reviewer keys even when both belong to the same account.

Meta Council Feedback

A platform-feedback channel for reporting bugs, performance failures, and capability gaps in Meta Council itself directly to the platform admins — not for anything about your own business data (deals, invoices, tickets, etc.), which stays in its own tools.

The meta-council-mcp 0.12.0 stdio package provides 98 tools, three resources, and three prompts; pip install meta-council-mcp installs this release. Accounting synchronization, ticket plan/batch, ticket field-parity, and ticket-validation finalization — source-only in the previous stable PyPI 0.8.0 (93-tool) release — are included. See the MCP setup guide for release status, raw JSON-RPC examples, scopes, polling, and source-run configuration.

Error Handling

All errors return a consistent JSON format with an appropriate HTTP status code.

Error response format

HTTP status codes

Example: handling errors

Keyboard Shortcuts

Speed up your workflow with these keyboard shortcuts.

Self-Hosting & Desktop App BETA

Run Meta Council entirely on your own hardware. Nothing leaves your machine.

Option 1: Docker (Recommended)

One command starts the web app + local AI model:

# After receiving your self-hosted package:
cd meta-council
docker compose up

Open http://localhost:8080. Ollama downloads Qwen 2.5 7B (~4.5 GB) on first run.

Option 2: Desktop App

Native application for Mac, Windows, and Linux. Double-click to launch — auto-detects local Ollama for free inference.

cd desktop
npm install
npm start

Build installers: npm run build:mac / build:win / build:linux

Option 3: Full Offline (Air-Gapped)

For environments with no internet access:

1. Install Ollama on the target machine
2. Pull a model: ollama pull qwen2.5:7b
3. Deploy Meta Council via Docker or the desktop app
4. No internet required after initial setup

GPU Models

Contact [email protected] for self-hosted access and the complete setup guide.

Frequently Asked Questions