Metadata-Version: 2.4
Name: meta-council-mcp
Version: 0.8.0
Summary: MCP server for Meta Council — multi-expert AI decision intelligence
Author: Dave Liu
License: MIT
Project-URL: Homepage, https://meta-council.com
Project-URL: Repository, https://github.com/daliu/meta-council
Project-URL: Documentation, https://meta-council.com/static/docs.html
Keywords: mcp,ai,agents,decision-intelligence,meta-council
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.27
Requires-Dist: jsonschema>=4.20

# Meta Council MCP Server

Let any MCP-compatible AI agent convene expert panels on Meta Council.

## Hosted Streamable HTTP

The production MCP resource URL is `https://meta-council.com/mcp` (JSON-RPC 2.0
over stateless [MCP Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)).
No local package or clone is required for the hosted transport:

```bash
# Claude Code
claude mcp add --transport http meta-council https://meta-council.com/mcp \
  --header "Authorization: Bearer mc_your_key_here"
```

Get an `mc_` key at meta-council.com → Settings → Developer API Keys. Only four
catalog tools are anonymous: `list_panels`, `list_agents`, `list_workflows`, and
`get_agent_detail`. Query-bearing tools such as `recommend_panel`, private
artifacts such as `get_visualization`, and every run, settings, clinical,
legal, Accounting, or outreach tool require a key with the relevant scope.

The repository contains the hardened transport described here. Do not treat
documentation or source state as proof that a particular release is deployed;
see [`docs/ENTERPRISE_READINESS.md`](../docs/ENTERPRISE_READINESS.md) for the
production verification gates and current compliance posture.

### Claude Desktop

The hosted endpoint currently authenticates with static scoped API keys; MCP
OAuth protected-resource discovery is not implemented yet. A Claude Desktop
custom connector that requires OAuth will therefore not complete authorization.
Until OAuth is shipped and verified, bridge the HTTP endpoint through
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) in
`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "meta-council": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://meta-council.com/mcp",
                     "--header", "Authorization: Bearer ${MC_API_KEY}"],
            "env": {"MC_API_KEY": "mc_your_key_here"}
        }
    }
}
```

### Other MCP clients

Cursor, Windsurf, and anything else that speaks MCP over HTTP: URL
`https://meta-council.com/mcp`, header `Authorization: Bearer mc_your_key_here`.
Clients that only speak stdio can use the same `mcp-remote` bridge as above.
The hosted server is published in the official
[MCP Registry](https://registry.modelcontextprotocol.io/?q=com.meta-council%2Fdecision-intelligence)
as `com.meta-council/decision-intelligence` version `1.3.0`. Configure the URL
and scoped key explicitly because the Registry listing does not provision
credentials.

## stdio adapter (`pip install meta-council-mcp`)

For clients that prefer a local stdio server over the hosted HTTP endpoint, the
adapter is published on PyPI as
[`meta-council-mcp`](https://pypi.org/project/meta-council-mcp/). It exposes 93
tools — including Legal research, configuration, and legacy outreach
operations, plus mirrors of the hosted Accounting, Marketing, ticket-board,
Consulting, feedback, and Sales-CRM deal/task/analytics/recommendation/health
tools (the admin-only `list_feedback` stays hosted-only) — together with three
resources and three prompts. It calls the
Meta Council REST API at `META_COUNCIL_URL` (default `https://meta-council.com`);
it does not replace the Meta Council backend.

```bash
pip install meta-council-mcp
export META_COUNCIL_API_KEY="mc_your_key_here"   # meta-council.com > Settings > Developer API Keys
claude mcp add meta-council -- meta-council-mcp
```

`pip install meta-council-mcp` puts a `meta-council-mcp` console script (entry
point `meta_council_mcp.server:main`) on your PATH — no clone required. To run
from a source checkout instead (e.g. for development), point Python at
`mcp/server.py`, kept byte-identical to the packaged `meta_council_mcp/server.py`:

```bash
claude mcp add meta-council -- python /path/to/meta-council/mcp/server.py
```

> **Note:** install `meta-council-mcp`, not `mcp` — the latter is only the
> upstream MCP SDK, not Meta Council. The adapter still needs an `mc_` key in
> `META_COUNCIL_API_KEY`; set `META_COUNCIL_URL` only to target a non-default
> deployment.

Claude Desktop with the stdio server (after `pip install meta-council-mcp`):

```json
{
    "mcpServers": {
        "meta-council": {
            "command": "meta-council-mcp",
            "env": {
                "META_COUNCIL_API_KEY": "mc_your_key_here"
            }
        }
    }
}
```

If Claude Desktop can't find `meta-council-mcp` (GUI apps don't always inherit
your shell PATH), use the absolute path from `which meta-council-mcp` as the
`command`.

## Hosted transport details (raw JSON-RPC)

Any server-to-server client that can send an HTTP POST can talk to Meta Council
directly—no MCP client library is required. Browser clients additionally need
an explicitly allowed Origin and compatible CORS response handling:

```
POST https://meta-council.com/mcp
Content-Type: application/json
Accept: application/json
Authorization: Bearer mc_your_key_here      # see below
```

Standard MCP methods are supported: `initialize`, `tools/list`, `tools/call`,
`ping`. The server negotiates MCP `2025-11-25`, `2025-06-18`, or `2025-03-26`.
Send the negotiated version in `MCP-Protocol-Version` on requests after
initialization. The implementation is stateless: it returns one JSON response per
POST and does not issue an `MCP-Session-Id` or expose a standalone SSE stream.

Auth uses an `mc_` API key in `Authorization: Bearer ...` (preferred) or
`X-API-Key`. New keys have explicit scopes and an expiry (90 days by default,
configurable from 1–365 days); the raw key is shown only once. Create narrow
keys and rotate them before expiry.

Initialize:

```bash
curl -s https://meta-council.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
```

List the tools:

```bash
curl -s https://meta-council.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

Call an anonymous catalog tool:

```bash
curl -s https://meta-council.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"list_panels","arguments":{}}}'
```

Start a council (requires `councils:run`):

```bash
curl -s https://meta-council.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H 'Authorization: Bearer mc_your_key_here' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call",
       "params":{"name":"run_council","arguments":{"query":"...","panel":"auto"}}}'
```

`run_council`, `run_workflow`, and `score_locus_case` return a session ID
immediately by default. Poll with `get_session` or `get_workflow_session`. A
caller may request `wait_seconds` from 0–90, but should still handle a running
response and poll; long proxy-held requests are not the default.

The hosted HTTP transport exposes 89 tools spanning councils, discovery,
workflows, LOCUS, citation-grounded Legal research, settings reads, governed
Sales/outreach operations, the private ticket board, feature feedback, and the
owner-private Accounting, Marketing, and Consulting workspaces. Accounting performs
deterministic analysis and stores encrypted audit runs; it never files, pays,
or sends records externally. Marketing covers brands, audiences,
campaigns, immutable content revisions, the planning calendar, draft
submission, and separately scoped review; it exposes no publish, send,
archive, or delete operation. Live outreach sends and destructive
campaign/deal deletes remain outside hosted MCP.
Consulting covers clients,
engagements, revision-safe proposals/SOWs, idempotent stable milestones, and
internal deliverables. It deliberately has no publish, share, send, or delete
tool. Approval requires both the exact version/hash returned by a read and a
credential different from the one that last edited that snapshot. Use separate
writer and reviewer keys even when both keys belong to the same account.

### API-key scopes used by hosted MCP

| Scope | Hosted operations |
|---|---|
| `catalog:read` | `recommend_panel` |
| `councils:read` | `get_session`, `get_visualization` |
| `councils:run` | `run_council` |
| `workflows:read` | `get_workflow_session` |
| `workflows:run` | `run_workflow` |
| `workflows:approve` | `advance_workflow` |
| `clinical:run` | LOCUS tools |
| `legal:run` | `ask_legal` |
| `accounting:read` | `list_accounting_runs`, `get_accounting_run` |
| `accounting:write` | `create_accounting_run`, `delete_accounting_run` |
| `settings:read` | `get_settings` |
| `outreach:read` | Hosted outreach reporting tools |
| `outreach:agent_write` | Governed campaign, lead, pitch, deal, activity, and draft writes (no live send or delete) |
| `tickets:read` | `ticket_list`, `ticket_get` |
| `tickets:write` | Ticket create/update/comment/claim; also satisfies ticket reads |
| `feedback:write` | `submit_feedback` |
| `feedback:admin` | Admin-only feedback listing and triage |
| `marketing:read` | List/get owned brands, audiences, campaigns, assets, and calendar |
| `marketing:agent_write` | Create/update owned Marketing context and drafts; revise/submit content (also satisfies reads) |
| `marketing:approve` | Approve/reject an exact submitted revision (also satisfies reads; cannot draft or publish) |
| `consulting:read` | List/get the caller's private consulting workspace |
| `consulting:write` | Create/update consulting drafts and submit deliverables for review; also satisfies consulting reads |
| `consulting:approve` | Approve and lock an exact SOW/proposal revision or submitted deliverable using caller-supplied version/hash evidence; does not imply write |

`list_panels`, `list_agents`, `list_workflows`, and `get_agent_detail` are
anonymous catalog reads. Legacy keys created before scopes were introduced must
be rotated; they retain compatibility access until revoked.

## Source-run stdio tool surface

The tables below describe the 93-tool stdio adapter. It includes Legal
research, local configuration, and legacy outreach operations plus mirrors of
the hosted Accounting, Marketing, Consulting, ticket-board, submit-feedback, and Sales-CRM
deal/task/analytics/recommendation/health tools. Mirrored tools forward to the
hosted transport with the same names and Bearer key, so their auth, scopes,
and rendering match the hosted behavior.

**Councils**
| Tool | Description |
|------|-------------|
| `convene_council` | Submit a question to a panel of AI experts. Returns synthesis with executive summary, risk matrix, and action plan. |
| `list_panels` | Browse all expert panels (biotech, finance, software, crisis, LOCUS, etc.) |
| `list_agents` | Browse 290+ expert agents, filterable by domain |
| `get_session` | Retrieve results from a previous council session |
| `recommend_panel` | Get the best panel recommendation for your query |
| `get_visualization` | Fetch a result chart by `artifact_id` — the spec JSON, plus the SVG markup with `include_svg: true`. Requires the owning API key. |

**Workflows (composable multi-step pipelines)**
| Tool | Description |
|------|-------------|
| `list_workflows` | Browse available workflow pipelines (each step can run on its own model/provider). |
| `run_workflow` | Run a pipeline end-to-end; returns each step's model + output and the final synthesis. |
| `get_workflow_session` | Poll a running workflow for step-by-step progress. |
| `advance_workflow` | Approve/reject a human checkpoint to advance a paused workflow. |

**LOCUS (behavioral-health level-of-care automation)**
| Tool | Description |
|------|-------------|
| `score_locus_case` | Convene the LOCUS panel on an anonymized adult case; returns a deterministic Level-of-Care determination (composite + override floors applied in code) plus narrative. |
| `locus_determine_from_scores` | Instant, no-LLM determination from six dimension ratings you already have (1-5 each). |

See `docs/locus_integration.md` for the full LOCUS guide.

**Legal research**
| Tool | Description |
|------|-------------|
| `ask_legal` | Citation-grounded U.S. federal/California research through Themis. Requires `legal:run`; the server owns the service credential and generation-mode decision. Informational, not legal advice. |

**Accounting (private deterministic audit runs)**
| Tool | Description |
|------|-------------|
| `create_accounting_run` | Analyze 1–50 textual `.txt`, `.md`, `.text`, `.eml`, `.csv`, `.ofx`, `.qfx`, or `.qif` records and create an encrypted owner-scoped run. Requires `accounting:write`. |
| `list_accounting_runs` | List the caller's audit metadata only; input and results are omitted. Requires `accounting:read`. |
| `get_accounting_run` | Return one owned run's deterministic estimates, disclaimer, engine revision, and timestamps. Decrypted input is opt-in. Requires `accounting:read`. |
| `delete_accounting_run` | Permanently delete one audit run owned by the caller. Requires `accounting:write`. |

Accounting output is an estimate for professional review. These tools do not
file a return, move money, or send records to an external accounting service.
Read/write scopes are independent and are never added to default or legacy
keys; explicitly grant both to an agent that needs the full lifecycle.

**Configuration**
| Tool | Description |
|------|-------------|
| `get_settings` | Current model preference + configured provider/tool keys. |
| `configure_model` | Set your preferred LLM model. |
| `configure_provider_key` | Add an LLM provider API key (anthropic, openai, google, …). |
| `configure_tool_key` | Add a premium-tool API key (alpha_vantage, tavily, …). |
| `get_agent_detail` | Full detail on one agent (role, model, tools). |

**Outreach (sales-pipeline management)**
| Tool | Description |
|------|-------------|
| `list_outreach_campaigns` / `create_outreach_campaign` / `update_outreach_campaign` / `delete_outreach_campaign` | Campaign CRUD. |
| `search_outreach_leads` / `update_lead_status` / `edit_outreach_email` | Lead management. |
| `assign_leads_to_campaign` / `send_outreach_batch` / `campaign_pipeline_stats` | Run a campaign. |
| `list_campaign_triggers` / `create_campaign_trigger` / `delete_campaign_trigger` | Automation rules. |
| `list_campaign_replies` / `outreach_analytics` | Replies + analytics. |

**Ticket board & feedback (mirrors of the hosted transport)**
| Tool | Description |
|------|-------------|
| `ticket_list` / `ticket_get` | Find work on the caller's board; full detail incl. acceptance criteria + activity trail. Requires `tickets:read`. |
| `ticket_create` / `ticket_update` / `ticket_comment` / `ticket_claim` | Create (with effort/action-type recommendations + subtickets), edit/move (audit-logged), comment, and claim-to-in_progress in one step. Requires `tickets:write`. |
| `submit_feedback` | Write-only product feedback to the platform admins (`feedback:write`). The admin-only `list_feedback` is deliberately hosted-only. |

**Sales CRM — deals, tasks, analytics & health (mirrors of the hosted transport)**
| Tool | Description |
|------|-------------|
| `list_deals` / `get_deal` | List the caller's deals with a weighted pipeline forecast (open/weighted/won); fetch one deal with its full activity timeline. Requires `outreach:read`. |
| `get_sales_analytics` / `get_sales_recommendations` | Pipeline analytics (probability-weighted forecast, per-stage $ rollup, win rate, sales-cycle days, open-deal aging) and prioritized next-best actions (leads to convert, stale deals to follow up, overdue tasks — each with a rationale + the exact governed tool to run next). Read-only; both require `outreach:read`. |
| `get_deal_health` | Deterministically score and rank the caller's open deals as healthy/watch/at-risk with reasons. Read-only; requires `outreach:read`. |
| `create_deal` / `update_deal` / `convert_lead_to_deal` | Create a deal, advance its stage (auto-stamps the close date on won/lost), or convert an owned lead into a deal. Requires `outreach:agent_write`. |
| `log_deal_activity` / `list_sales_tasks` / `complete_sales_task` | Log a note/call/meeting/email or a due-dated follow-up task on a deal or lead, list open tasks bucketed overdue/today/upcoming, and close one. `log_deal_activity`/`complete_sales_task` require `outreach:agent_write`; `list_sales_tasks` requires `outreach:read`. No deletes are exposed over MCP. |

**Marketing workspace (mirrors of the hosted transport)**
| Tool | Description |
|------|-------------|
| `list_marketing_brands` / `get_marketing_brand` / `create_marketing_brand` / `update_marketing_brand` | Owner-private brand voice, positioning, and guidelines. Reads require `marketing:read`; writes require `marketing:agent_write`. |
| `list_marketing_audiences` / `get_marketing_audience` / `create_marketing_audience` / `update_marketing_audience` | Reusable owner-private audience definitions. |
| `list_marketing_campaigns` / `get_marketing_campaign` / `create_marketing_campaign` / `update_marketing_campaign` | Content campaigns, separate from Sales outreach campaigns. Campaign status never publishes content. |
| `list_content_assets` / `get_content_asset` / `get_content_calendar` | Read immutable revision lineage, exact review hashes, and planned dates (`marketing:read`). |
| `create_content_asset` / `update_content_asset` / `create_content_asset_revision` / `submit_content_asset` | Governed draft/revise/submit flow (`marketing:agent_write`). Submitted revisions freeze. |
| `approve_content_asset` / `reject_content_asset` | Separate reviewer authority (`marketing:approve`). Approval records the exact content hash; it does not publish or send. |

**Consulting workspace (mirrors of the hosted transport)**
| Tool | Description |
|------|-------------|
| `list_consulting_clients` / `create_consulting_client` / `update_consulting_client` | Manage client records private to the API-key owner. Reads require `consulting:read`; writes require `consulting:write`. |
| `list_consulting_engagements` / `get_consulting_engagement` / `create_consulting_engagement` / `update_consulting_engagement` | Manage engagements and inspect their full internal workspace, including nullable Sales/Accounting refs. |
| `create_consulting_document_revision` / `update_consulting_document_revision` / `approve_consulting_document_revision` | Draft revision-safe proposals/SOWs and separately approve one exact immutable revision. Approval requires `consulting:approve`, the fetched `version`/`content_hash`, and a different credential from the last editor. |
| `initialize_consulting_milestones` / `update_consulting_milestone` | Idempotently initialize stable milestone IDs/external refs and advance owned milestones with `expected_version` compare-and-swap protection. |
| `create_consulting_deliverable` / `update_consulting_deliverable` / `submit_consulting_deliverable` / `reopen_consulting_deliverable` / `approve_consulting_deliverable` | Draft and review internal deliverables. Approval supplies the fetched `version`/`content_hash` and uses a reviewer credential distinct from the last editor; it never publishes or sends. |

All changes flow through the same backend as the web UI, so they appear live in the dashboard.

**Resources & Prompts**

Beyond tools, the server exposes 3 MCP **resources** for browsing — `council://panels`, `council://workflows`, `council://agents` — and 3 **prompt** templates for common council / LOCUS / workflow flows.

## Visualizations

Results ship with charts automatically — nothing to render, no extra calls. When
a council completes, the server draws dark-themed SVG charts (per-agent consensus
confidence; for LOCUS, dimension ratings with override-floor flags) and stores
them alongside the result. Tool responses list them under **Visuals**, and the raw
API/session JSON carries refs like:

```json
{
    "artifact_id": "9f3c…32-hex…a1",
    "svg_url": "/api/viz/9f3c….svg",
    "spec_url": "/api/viz/9f3c….json"
}
```

- **`svg_url`** — an artifact URL. Artifacts created by authenticated hosted MCP
  runs are private by default and require the owning identity; an artifact ID is
  not a bearer capability. Browser clients should fetch it with an
  `Authorization` header and render the returned blob rather than placing a key
  in a query string.
- **`spec_url`** — the chart's underlying data as JSON, for agents that want the
  numbers rather than the picture. The same owner check applies.
- **`get_visualization`** — fetches both by `artifact_id`; pass
  `include_svg: true` to receive the SVG markup inline. It requires
  `councils:read` and verifies the artifact owner.

The same charts appear on the session page at meta-council.com.

## Example Usage (from Claude Code)

> "Convene the biotech panel to analyze whether we should proceed with our Phase IIb trial given the marginal endpoint miss."

The hosted transport calls `run_council`; the source-run stdio adapter calls
`convene_council`. Both return the council result through their respective
asynchronous/polling flow.

> "Score this LOCUS case using synthetic or properly de-identified data. What level of care?"

Claude calls `score_locus_case` and returns the deterministic level (e.g. "Level 5 — Medically Monitored Residential") with the override audit trail.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `META_COUNCIL_API_KEY` | (none) | Your API key from meta-council.com. Only the four catalog tools can work without it; runs, recommendations, session/artifact reads, settings, regulated-domain tools, and every private workspace operation require an appropriately scoped key. |
| `META_COUNCIL_URL` | `https://meta-council.com` | Server URL (for self-hosted) |

## Self-Hosted

Point to your own Meta Council instance:

```bash
export META_COUNCIL_URL="http://localhost:8080"
export META_COUNCIL_API_KEY="mc_your_local_key"
```
