Metadata-Version: 2.4
Name: meta-council-mcp
Version: 0.3.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

# 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, 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 (source-only / development)

The repository also ships a source-run stdio adapter (`mcp/server.py`) with 32
tools, including configuration and outreach writes, plus three resources and
three prompts. It calls the Meta Council REST API; it does not replace the Meta
Council backend.

```bash
pip install mcp
export META_COUNCIL_API_KEY="mc_your_key_here"   # meta-council.com > Settings > Developer API Keys
claude mcp add meta-council -- python /path/to/meta-council/mcp/server.py
```

> **Note:** `meta-council-mcp` is not published on PyPI. `pip install mcp`
> installs the upstream MCP SDK dependency, not Meta Council. Use the hosted
> endpoint or run this repository's adapter from source.

Claude Desktop with the stdio server:

```json
{
    "mcpServers": {
        "meta-council": {
            "command": "python",
            "args": ["/path/to/meta-council/mcp/server.py"],
            "env": {
                "META_COUNCIL_API_KEY": "mc_your_key_here"
            }
        }
    }
}
```

## 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 a 20-tool read/run surface: council
execution (`run_council`, `get_session`, `get_visualization`), discovery
(`list_panels`, `list_agents`, `recommend_panel`, `get_agent_detail`),
workflows (`list_workflows`, `run_workflow`, `get_workflow_session`,
`advance_workflow`), LOCUS (`score_locus_case`, `locus_determine_from_scores`),
`get_settings`, and outreach reads (`list_outreach_campaigns`,
`search_outreach_leads`, `outreach_analytics`, `campaign_pipeline_stats`,
`list_campaign_triggers`, `list_campaign_replies`). Configuration writes and
outreach writes (sending, campaign/lead CRUD) stay on the stdio server above.

### 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 |
| `settings:read` | `get_settings` |
| `outreach:read` | Hosted outreach reporting tools |

`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 32-tool stdio adapter. The hosted endpoint exposes
the 20-tool subset listed above; in particular, configuration writes and
outreach mutations are stdio-only.

**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.

**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. |

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, clinical, and outreach operations 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"
```
