Model Context Protocol (MCP)

Ecosystem exposes three different MCP-related surfaces. They share the path /mcp but are not interchangeable. Pick the surface that matches your integration.

Protocol reference: MCP specification 2026-07-28 .

Runtime builtin MCP (Java, 0.9.7+)

Built into the Java runtime. Stateless Streamable HTTP-shaped endpoint:

POST {RUNTIME_BASE}/mcp
Content-Type: application/json

Protocol support

• Legacy (2024-11-05 – 2025-11-25): initialize handshake, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, ping
• Modern (2026-07-28): server/discover, per-request _meta, MCP-Protocol-Version / Mcp-Method / Mcp-Name headers, resultType on results, MCP content[] on tools/call, ttlMs + cacheScope on list results
• Streamable HTTP responses: each POST to /mcp returns either application/json or a per-request text/event-stream body (scoped to that request — not a persistent session). Clients must send Accept: application/json, text/event-stream. Prefer SSE by listing text/event-stream first or with a higher q value.
• Change notifications: subscriptions/listen opens a long-lived SSE stream on the POST response (ack + optional keep-alives).
• Deprecated HTTP+SSE (2024-11-05): GET /mcp opens a legacy session stream (when no modern protocol headers); responses are delivered on that stream via POST /mcp/message?sessionId=…. New clients should use Streamable HTTP on POST /mcp only.

When MASTER_KEY is configured, mutating tools (campaignCreate, campaignDelete, generateClass, updateProperties*, learningTrigger) require X-API-KEY or Authorization: Bearer {MASTER_KEY}.

Prompts

Curated agent templates (visible in MCP Playground and prompts/list):

Call prompts/get with name and optional arguments to render a prompt message with substituted values.

For algorithm questions, call askAboutAlgorithms or read ecosystem://algorithms/selection-guide (full ECOSYSTEM_ALGORITHMS.md).

Tools

Scoring & campaigns: listCampaigns, invoke, response, updateProperties, updatePropertiesJson, generateClass, campaignCreate, campaignGet, campaignDelete, configGet, learningTrigger

Runtime ontology (agent grounding): lookupRuntimeConcept, getClosedLoopRecipe, validateInvokeRequest, validateResponseRequest

Algorithm selection: askAboutAlgorithms — recommends approach / sub_approach from natural-language questions using ECOSYSTEM_ALGORITHMS.md

Use ontology tools before invoke / response to validate payloads against the Runtime Closed Loop vocabulary. Dashboard walkthrough: Ontology for agents.

Recommended agent flow (closed loop)

1. Read ontology://runtime/closed-loop (resource) or call getClosedLoopRecipe
2. listCampaigns — resolve campaign
3. validateInvokeRequest — pre-flight InvocationRequest (params must be a JSON string)
4. invoke — save uuid and offer_name from final_result
5. validateResponseRequest — pre-flight ResponseFeedback
6. response — same uuid ties ContactLog and ResponseLog for learning

Optional: lookupRuntimeConcept with query: "InvocationRequest" for concept cards and related MCP tools.

REST ontology API

Headless catalog (same content as MCP resources/tools):

curl -X POST "$RUNTIME/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "invoke",
      "arguments": {
        "campaign": "my_campaign",
        "customer": "customer-123",
        "channel": "app",
        "numberoffers": 3,
        "userid": "mcp-user",
        "params": "{}"
      }
    }
  }'

Example: modern discovery

curl -X POST "$RUNTIME/mcp" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28"
      }
    }
  }'

Closed-loop learning: after invoke, send feedback with response using the returned uuid and offer_name. See API Access.

Browser MCP testers

Remote browser tools such as MCP Playground  and MCP Inspector can connect to a public runtime over HTTPS.

The runtime supports per-request SSE on POST /mcp when the client prefers text/event-stream. Protocol-level sessions (Mcp-Session-Id) were removed in 2026-07-28; legacy clients may still use GET /mcp + POST /mcp/message (deprecated HTTP+SSE).

Read-only tools (tools/list, listCampaigns, ontology validators, invoke, response) work without auth unless Spring --security is enabled on the deployment.

Resources

• ecosystem://campaigns, ecosystem://config
• Dynamic: ecosystem://campaign/{id}, .../config, .../metrics, .../models
• Runtime ontology: ontology://runtime, ontology://runtime/closed-loop, ontology://runtime/examples, ontology://runtime/concept/{localName} (e.g. InvocationRequest)
• Algorithms: ecosystem://algorithms/selection-guide — ECOSYSTEM_ALGORITHMS.md for approach / sub_approach selection

Workbench MCP server

Operator-facing guide (credentials, dual auth, full tool list, public vs private APIs): Public APIs, Agents & MCP.

The Workbench backend exposes deployments, enrichment, catalog escape-hatch (call_endpoint), and related tools. See also Claude Agent for Operator vs Campaign Management vs external attach.

Dual auth (required for HTTP /mcp): Authorization: Bearer <user-jwt> and X-API-Key: ewb_public_... (same as the public API gateway).

Configure the public base URL with MCP_PUBLIC_BASE_URL (default http://localhost:8001). The Vite UI port (5270) does not proxy /mcp in local dev — point clients at the backend port or nginx.

Three Workbench MCP modes

External attach does not require Workbench’s in-image Agent SDK bundled CLI — the client brings its own. In-app Operator readiness (GET /api/v1/claude-agent/status) does require the bundled binary (Debian slim image).

Cursor configuration (Streamable HTTP)

{
  "mcpServers": {
    "ecosystem-workbench": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer <user-jwt>",
        "X-API-Key": "ewb_public_..."
      }
    }
  }
}

Tools

list_api_catalog, call_endpoint, list_campaign_channel_catalog, get_campaign_channels, set_campaign_channel_selection, list_custom_channel_modules, list_deployments, get_deployment_info, score_customer, send_feedback, Networks jobs (networks_job, networks_job_status, networks_job_events, networks_job_result, networks_cancel_job — see Networks Jobs & API), enrichment helpers (date_enrich, mcc_enrich, …), and related catalog tools.

Campaign delivery channels (email, WhatsApp, WhatsApp Local, SMS, push, Python, webhook, web robot, CSV) are listed by list_campaign_channel_catalog. Assign published options with set_campaign_channel_selection (confirm=true). Do not confuse these with runtime scoring channel (app / web / api).

call_endpoint path rules

Accepts /api/v1/..., /public/v1/..., or relative paths (e.g. /campaigns). Prefixes are stripped; the internal client calls private /api/v1. Known remaps:

• /money-personality/process → /algorithms/money-personality/process
• /sentimental-equilibrium/process → /algorithms/sentimental-equilibrium/process

Mutating methods require confirm=true.

Resources

• ecosystem://deployments
• ecosystem://deployment/{name}

Per-deployment MCP snippets: GET /api/v1/deployments/{name}/mcp.

Runtime MCP sidecar (Python image)

Separate container for custom FastAPI APIs and MLFlow model download — not the JSON-RPC builtin server above.

ecosystem-runtime-mcp:
  image: ecosystemai/ecosystem-runtime-mcp:arm64
  environment:
    RUNTIME_URL: "http://ecosystem-runtime-backend:8081"
    PORT: 8092
    MLFLOW_TRACKING_URI: "http://mlflow:8085"
    RUNTIME_CONFIG: "/data/config/runtime_config.json"
    MONGO_CONNECT: ${MONGO_CONNECT_STRING}
  ports:
    - "8092:8092"

Environment variables

Custom APIs

Author Python APIRouter modules and compile them from the Workbench deployment API tab. Template:

from fastapi import APIRouter, Body
from .custom_api_super import invocations, response
from ..type_models import Invocation, Response
 
router = APIRouter()
 
@router.post("/myCustomInvocationsName", tags=["Predictors"])
async def my_custom_invocations(
    customer: str = Body(...),
    params: str = Body(...),
):
    body = Invocation(customer=customer, params=params)
    return await invocations(body)

See MLFlow integration for model refresh via the sidecar.

Client compatibility

stdio harness: the ecosystem_workbench_mcp Python package exposes Workbench public APIs over stdio for local agent hosts (Hermes, Cursor command config). That is separate from the HTTP /mcp servers above.

Which surface should I use?

• Score runtime campaigns from an agent → Runtime builtin MCP (invoke + response)
• Score Workbench deployments / run enrichment / catalog via call_endpoint → Workbench MCP server
• In-app Operator or Campaign Management Claude turns → Claude Agent
• MLFlow model pull + custom Python APIs → Runtime MCP sidecar
• Local agent with full Workbench API → ecosystem_workbench_mcp stdio SDK