MCP
Ecosystem exposes three MCP-related surfaces. They share the path /mcp but are not interchangeable.
| Surface | Where | Transport | Use for |
|---|---|---|---|
| Workbench MCP | ecosystem-workbench2 :8001 | Streamable HTTP POST /mcp | Deployments, entities, enrichment, public catalog, operator chat |
| Runtime builtin MCP | Java Runtime :8091 | POST /mcp JSON-RPC | invoke / response, campaign admin, runtime ontology |
| Runtime MCP sidecar | ecosystemai/ecosystem-runtime-mcp | FastAPI /mcp | MLFlow refresh, custom FastAPI |
Protocol: MCP specification 2026-07-28 . Runtime detail: MCP Support.
Pointing Cursor at Runtime :8091/mcp will not list Workbench list_api_catalog. Pointing it at Workbench :8001/mcp will not list Runtime invoke. Score campaigns on Runtime MCP or REST /invocations. Operate Workbench on Workbench MCP.
Workbench MCP modes
| Mode | Who | Auth |
|---|---|---|
| In-process | Ecosystem Agent /assistant (tool_profile: operator) | Session JWT inside Workbench. No public API key |
HTTP POST /mcp | Cursor, Claude Code, Agent SDK | One credential: JWT or public key (X-API-Key or Bearer ewb_public_…) |
stdio ecosystem_workbench_mcp | Hermes / desktop | Harness mints JWT; EWB_PUBLIC_API_KEY in env or ~/.herm/mcp/ecosystem-public.env |
Vite :5270 does not proxy /mcp. Clients must hit the backend port (or nginx). MCP_PUBLIC_BASE_URL default http://localhost:8001.
REST info (JWT): GET /api/v1/mcp/ — tool list and connection hints.
Legacy SSE (GET /mcp/sse/, POST /mcp/messages/) was removed on 26 Oct 2026. Use Streamable HTTP POST /mcp only (protocol 2026-07-28).
Cursor (Streamable HTTP)
Public key only:
{
"mcpServers": {
"ecosystem-workbench": {
"url": "http://localhost:8001/mcp",
"headers": {
"X-API-Key": "ewb_public_..."
}
}
}
}Alternatively use "Authorization": "Bearer <user-jwt>" instead of X-API-Key.
Mint the key under Administration → API Keys → Public API Access. For Claude Code, set ANTHROPIC_BASE_URL to the Workbench host root so POST /v1/messages uses the Workbench default LLM.
HTTP MCP tools
Same implementations as in-process MCP. Mutating tools require confirm=true.
| Tool | Purpose |
|---|---|
list_api_catalog | Public API catalog, scopes, accessible flags |
call_endpoint | Any Workbench /api/v1 or /public/v1 path |
entity | CRUD /api/v1/entities/{collection} |
explain_entity | Read-only explain of entity / current form |
update_current_form | Patch open editor (operator Saves) |
list_campaign_channel_catalog | Delivery channels (email, WhatsApp, …) |
get_campaign_channels | Options, selection, send_track |
set_campaign_channel_selection | Assign published options |
list_custom_channel_modules | Custom channel modules |
explain_workbench | Product-guide orientation |
recommend_algorithm | Dynamic Engagement / product approaches |
explain_algorithms | Algorithm catalog |
explain_convergence | Score convergence and priors |
list_deployments | Deployments |
get_deployment_info | One deployment |
get_deployment_schema | Input/output schema |
score_customer | Score via a Workbench deployment |
send_feedback | Feedback for that scoring result (/response semantics) |
date_enrich / mcc_enrich | Queue enrichment jobs |
personality_drift | Queue personality drift |
get_enrichment_job | Poll enrich / drift jobs |
| Outreach | list_outreach_templates, inspect_outreach_campaign, build_outreach_campaign, configure_outreach_campaign, run_outreach_campaign (supports sample_run, test_target_email) |
| Ontology family | list_ontologies, describe_ontology, create/update/delete (confirm), mappings, resolve_ontology_term, generate_ontology_query, query_data_via_ontology |
| Runtime Testing | list_runtime_testing_suites, get_runtime_testing_suite, analyze_runtime_testing, plan_runtime_testing (confirm), start_runtime_testing_run (confirm), list_runtime_testing_runs, get_runtime_testing_run, cancel_runtime_testing_run / close_runtime_testing_run (confirm), compare_runtime_testing_runs, get_runtime_testing_artifact, delete_runtime_testing_suite (confirm) |
| Simulations | start_simulation_run / cancel_simulation_run (confirm), get_simulation_run_status, get_simulation_logs, get_simulation_results, explain_simulation_result |
Resources: ecosystem://deployments, ecosystem://deployment/{name}. Per-deployment snippets: GET /api/v1/deployments/{name}/mcp.
call_endpoint accepts /api/v1/…, /public/v1/…, or relative /campaigns. Prefixes are stripped; the internal client calls private /api/v1. Remaps:
/money-personality/process→/algorithms/money-personality/process/sentimental-equilibrium/process→/algorithms/sentimental-equilibrium/process
score_customer still needs params as a JSON string when it forwards an invocation. Feedback uses the returned uuid and offer_name.
stdio harness
Package sdk/python/ecosystem_workbench_mcp adds typed wrappers on top of the public gateway: catalogs_*, jobs_get, campaigns_*, networks_job*, spend_personality_*, two_tower_*, analytics_*, plus admin bootstrap_credential / rotate_credential / reveal_credential / revoke_credential.
cd sdk/python/ecosystem_workbench_mcp
backend/venv/bin/python -m ecosystem_workbench_mcp verify
backend/venv/bin/python -m ecosystem_workbench_mcp catalogNetworks job tools are documented with the Networks API.
Admin-published tools
Administration → MCP Tools publishes operator-defined tools backed by an entity collection, a saved Custom Pipeline, or a saved Python enrichment script. Definitions are stored in mcp_tools (:McpTool in the platform ontology). MCP Prompts exposes saved prompt templates alongside built-in tools.
Audit
Every HTTP /mcp call appends an immutable row to mcp_access_log (timestamp, category, tool or method, actor, outcome, redacted detail). This log is operator-only and is not exposed through the public API gateway.
Runtime builtin MCP (do not confuse)
POST http://localhost:8091/mcp
Content-Type: application/json
Accept: application/json, text/event-streamScoring tools: listCampaigns, invoke, response, ontology validators, askAboutAlgorithms, campaign admin. Mutating campaign tools may need Runtime MASTER_KEY (X-API-KEY or Bearer). That key is not ewb_public_….
Closed loop:
invoke(or RESTPOST /invocations) — saveuuidandoffer_namefromfinal_resultresponse(or RESTPOST /response) — sameuuid
params is a JSON string, never a nested object.
Sidecar
The Python ecosystem-runtime-mcp image is for custom FastAPI and MLFlow model download. It is not the Java JSON-RPC server and not Workbench MCP.
Related: Agents, Public APIs, Runtime MCP, Ontology for agents.