> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/protocols-and-integration/mcp-server.md). # MCP Server EDDI exposes its agent conversation and administration capabilities via the **Model Context Protocol (MCP)**, enabling AI assistants (Claude Desktop, IDE plugins, custom MCP clients) to interact with deployed agents and manage the platform programmatically. ## Transport EDDI uses **Streamable HTTP** transport, served by the Quarkus MCP Server extension (`quarkus-mcp-server-http`). | Endpoint | Description | | --------------------------- | ------------------------------------- | | `http://localhost:7070/mcp` | MCP server endpoint (default + admin) | ## Available Tools (74) ### Conversation Tools (11) | Tool | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `list_agents` | List all deployed agents with status, version, and name | | `list_agent_configs` | List all agent configurations (including undeployed) | | `create_conversation` | Start a new conversation with a deployed agent | | `talk_to_agent` | Send a message and get the agent's response | | `chat_with_agent` | Create a conversation and send a message in one call | | `read_conversation` | Read conversation history, memory, and quick replies | | `read_conversation_log` | Read conversation log as formatted text | | `list_conversations` | List all conversations for a specific agent | | `get_agent` | Get an agent's full configuration (packages, name, description) | | `discover_agents` | Discover deployed agents enriched with intent mappings from agent triggers. Best way to find agents by purpose | | `chat_managed` | Send a message using intent-based managed conversations (one conversation per intent+userId, auto-creates on first message) | ### Admin Tools (13) | Tool | Description | | ----------------------- | ------------------------------------------------------------------------------- | | `deploy_agent` | Deploy an agent version to an environment | | `undeploy_agent` | Undeploy an agent from an environment | | `get_deployment_status` | Get deployment status of a specific agent version | | `list_workflows` | List all packages (pipeline configurations) | | `create_agent` | Create a new agent | | `delete_agent` | Delete an agent (with optional cascade) | | `update_agent` | Update an agent's name/description and optionally redeploy | | `read_workflow` | Read a package's full pipeline configuration | | `read_resource` | Read any resource config by type (behavior, langchain, httpcalls, output, etc.) | | `list_agent_triggers` | List all agent triggers (intent→agent mappings) for managed conversations | | `create_agent_trigger` | Create an agent trigger mapping an intent to one or more agent deployments | | `update_agent_trigger` | Update an existing agent trigger | | `delete_agent_trigger` | Delete an agent trigger for a given intent | ### Resource CRUD Tools (5) | Tool | Description | | ---------------------- | ----------------------------------------------------------------------------------- | | `update_resource` | Update any resource config by type and ID. Returns the new version URI | | `create_resource` | Create a new resource. Returns the new resource ID and URI | | `delete_resource` | Delete a resource (soft-delete by default, `permanent=true` for hard delete) | | `apply_agent_changes` | Batch-cascade URI changes through package → agent in ONE pass, optionally redeploy | | `list_agent_resources` | Walk agent → packages → extensions to get a complete resource inventory in one call | ### Diagnostic Tools (2) | Tool | Description | | ------------------ | ------------------------------------------------------------------------------------------ | | `read_agent_logs` | Read server-side pipeline logs (errors, LLM timeouts) filtered by agent/conversation/level | | `read_audit_trail` | Read per-task audit entries with LLM details, timing, cost, and tool calls | ### Setup Tools (2) | Tool | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `setup_agent` | Create a fully working agent in one call: creates behavior rules, LangChain config, optional output/greeting, package, agent, and deploys. Supports built-in tools, quick replies, and sentiment analysis. Default: `anthropic`/`claude-sonnet-4-6` | | `create_api_agent` | Create an agent from an OpenAPI 3.0/3.1 spec. Parses the spec, generates HttpCalls configs (grouped by API tag), creates the full pipeline, and deploys. Supports endpoint filtering, base URL override, and auth header propagation | ### Schedule Management Tools (6) | Tool | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `create_schedule` | Create a new scheduled agent trigger (cron job or heartbeat). For CRON: provide `cronExpression`. For HEARTBEAT: provide `heartbeatIntervalSeconds`. Heartbeats default to persistent conversations | | `list_schedules` | List all scheduled agent triggers with name, type, cron/interval, status, next fire time, and fire count. Optionally filter by agentId | | `read_schedule` | Read a schedule's full configuration including recent fire history (last 10 executions) | | `delete_schedule` | Delete a scheduled agent trigger | | `fire_schedule_now` | Manually trigger a schedule fire immediately. Useful for testing or one-off executions | | `retry_failed_schedule` | Re-queue a dead-lettered schedule for another fire attempt after fixing the cause of failure | ### Group Conversation Tools (11) | Tool | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `describe_discussion_styles` | Rich descriptions of all 6 discussion styles with phase flows, member roles, and use cases | | `list_groups` | List all group configurations with name, style, member count | | `read_group` | Read a group configuration's full details | | `create_group` | Create a group (members, moderator, style, roles, member types, tasks). Supports nested groups via `memberTypes=GROUP` and pre-configured TASK\_FORCE tasks via `tasks` param | | `update_group` | Update a group configuration (full JSON replacement) | | `delete_group` | Delete a group configuration | | `discuss_with_group` | Start a multi-agent discussion on a question. Returns full transcript + synthesized answer | | `read_group_conversation` | Read a group conversation transcript | | `list_group_conversations` | List past group discussions for a group, with state and timestamps | | `start_group_discussion` | Start a discussion asynchronously (returns immediately with groupConversationId). Poll with `read_group_conversation` | | `delete_group_conversation` | Delete a group conversation and cascade-delete all member conversations | See [Group Conversations](/conversations-and-orchestration/group-conversations.md) for full style details, custom phases, and nested groups. ### HITL Tools (9) Resolve Human-in-the-Loop approval gates over MCP — the counterpart to the REST HITL endpoints, at parity for both the regular (1:1) and group surfaces. Authorization mirrors REST exactly (per-conversation owner / `eddi-admin` / `eddi-approver` via the shared `HitlAccessGuard`); decisions are attributed server-side as `mcp:`. Mutating tools honour the `eddi.mcp.hitl.mutations.enabled` kill-switch and return structured errors (`errorCode` ∈ `NOT_FOUND | WRONG_STATE | FORBIDDEN | DISABLED | BAD_REQUEST`). | Tool | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `list_pending_approvals` | List regular (1:1) conversations awaiting approval (owner-scoped; includes RULE and TOOL\_CALL pauses) | | `get_approval_status` | Read a paused conversation's status; summary reports `pauseType`, `detail=full` returns the snapshot incl. any tool-call batch | | `resume_conversation` | Resume with APPROVED/REJECTED (case-insensitive); resolves both RULE and TOOL\_CALL pauses | | `cancel_conversation` | Cancel a paused or running conversation | | `list_group_pending_approvals` | List a group's conversations awaiting approval (owner-scoped) | | `list_all_group_pending_approvals` | Cross-group HITL inbox across all groups (owner-scoped) | | `get_group_approval_status` | Read a paused group discussion's status (summary; `detail=full` returns the whole conversation) | | `approve_group_phase` | Approve/reject a paused phase, with optional `taskApprovals` JSON for TASK granularity; returns the resumed discussion | | `cancel_group_discussion` | Cancel an in-progress or paused group discussion | See [HITL](https://github.com/labsai/EDDI/tree/main/docs/hitl.md#mcp-surface) for the full authority model, the kill-switch, and REST-endpoint parity. ### Memory Tools (8) | Tool | Description | | -------------------------- | ----------------------------------------------------------------------------------------- | | `list_user_memories` | List all persistent memory entries for a user | | `get_visible_memories` | Get memories visible to a specific agent, considering self/group/global visibility scopes | | `search_user_memories` | Search user memories by keyword across keys and values | | `get_memory_by_key` | Get a specific memory entry by key for a user | | `upsert_user_memory` | Create or update a persistent memory entry for a user | | `delete_user_memory` | Delete a specific memory entry by ID | | `delete_all_user_memories` | Delete all memory entries for a user (GDPR-compliant bulk erasure) | | `count_user_memories` | Count total memory entries for a user | See [User Memory](/architecture-and-concepts/user-memory.md) for visibility scoping, recall order, and dream consolidation. ### GDPR Tools (2) | Tool | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | `delete_user_data` | Cascade-delete all user data across all stores (GDPR Art. 17 Right to Erasure). Requires `confirmation='CONFIRM'`. Irreversible | | `export_user_data` | Export all data for a user (GDPR Art. 15/20 Right of Access / Data Portability) | See [GDPR / CCPA Compliance](/security-and-compliance/gdpr-compliance.md) for data erasure, export, and retention details. ### Channel Integration Tools (5) | Tool | Description | | ---------------------------- | -------------------------------------------------------------------------------------------- | | `list_channel_integrations` | List all channel integrations with name, type, and target count | | `read_channel_integration` | Read a channel integration's full configuration | | `create_channel_integration` | Create a new channel integration (Slack, Teams, etc.) with platform config and agent targets | | `update_channel_integration` | Update an existing channel integration | | `delete_channel_integration` | Delete a channel integration (soft or permanent) | See [Slack Integration](/protocols-and-integration/slack-integration.md) for Slack-specific setup and multi-agent thread discussions. ## MCP Resources EDDI also exposes its documentation as MCP **resources**, allowing AI agents to browse and read the docs programmatically. | Resource | Description | | -------------------- | --------------------------------------------------------- | | `eddi://docs/index` | List all available documentation pages | | `eddi://docs/{name}` | Read a specific doc (e.g., `eddi://docs/getting-started`) | Configure the docs path with: `eddi.docs.path` (default: `docs/`, in Docker: `/deployments/docs`). ## Quick Start ### Client Configuration EDDI uses **Streamable HTTP** transport at `http://localhost:7070/mcp`. How you connect depends on your client's transport support. #### Direct HTTP (Streamable HTTP clients) Clients that natively support HTTP transport (e.g., IDE plugins, custom MCP clients) can connect directly: ```json { "mcpServers": { "eddi": { "url": "http://localhost:7070/mcp" } } } ``` #### Antigravity (Google) Add EDDI as an MCP server in your Antigravity settings (`.gemini/config/settings.json` or workspace `.agents/settings.json`): ```json { "mcpServers": { "eddi": { "serverUrl": "http://localhost:7070/mcp" } } } ``` Antigravity connects natively via Streamable HTTP — no bridge required. #### stdio Bridge (Claude Desktop, Cursor, Windsurf, etc.) Many MCP clients — including Claude Desktop's `claude_desktop_config.json` — only support **stdio** transport (spawning a local subprocess). They cannot connect to HTTP endpoints directly. Use [`mcp-remote`](https://github.com/geelen/mcp-remote) to bridge the gap. It runs as a local stdio process and proxies requests to EDDI's HTTP endpoint: ```json { "mcpServers": { "eddi": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:7070/mcp"] } } } ``` **Windows users** — if `npx` is not on your shell PATH, wrap via `cmd`: ```json { "mcpServers": { "eddi": { "command": "cmd", "args": ["/c", "npx", "-y", "mcp-remote", "http://localhost:7070/mcp"] } } } ``` > **What is `mcp-remote`?** An open-source npm package ([github.com/geelen/mcp-remote](https://github.com/geelen/mcp-remote)) that acts as an invisible bridge between stdio-only MCP clients and HTTP-based MCP servers. It handles protocol translation, session management, and authentication. Requires Node.js 18+. ### Example Workflow ``` 1. list_agents → see deployed agents 2. create_conversation(agentId: "my-agent") → get conversationId 3. talk_to_agent(agentId: "my-agent", conversationId: "...", message: "Hello!") → get response 4. read_conversation_log(conversationId: "...") → see full history ``` ### Discovering Agents by Purpose ``` 1. discover_agents() → enriched list with intents per agent 2. list_agent_triggers() → see all intent→agent mappings ``` ### Intent-Based Managed Chat ``` 1. create_agent_trigger(config: {"intent":"support","agentDeployments":[{"agentId":"agent-123"}]}) 2. chat_managed(intent: "support", userId: "user1", message: "Hello!") → auto-creates conversation 3. chat_managed(intent: "support", userId: "user1", message: "I need help") → reuses same conversation ``` ### Inspecting Agent Configuration ``` 1. list_agent_resources(agentId: "my-agent") → complete resource inventory in one call 2. read_resource(resourceType: "langchain", resourceId: "lc-456") → see LLM config details ``` ### Modifying Resources + Cascade ``` 1. read_resource("langchain", "lc-456") → get current config 2. update_resource("langchain", "lc-456", version: 1, config: {...}) → new version 2 3. apply_agent_changes(agentId, agentVersion, [{oldUri: "...?version=1", newUri: "...?version=2"}], redeploy: true) ``` ### Debugging an Agent ``` 1. read_agent_logs(agentId: "my-agent") → see pipeline errors, LLM timeouts 2. read_audit_trail(conversationId: "conv-123") → per-task execution details, LLM tokens, cost ``` ### Scheduling a Cron Job ``` 1. create_schedule(agentId: "my-agent", triggerType: "CRON", cron: "0 9 * * MON-FRI", message: "Daily morning check-in", name: "Weekday Morning Check") → { scheduleId: "sched-1", description: "At 09:00 on every weekday", nextFire: "..." } 2. list_schedules() → see all scheduled triggers with status 3. fire_schedule_now(scheduleId: "sched-1") → test immediately 4. read_schedule(scheduleId: "sched-1") → see full config + fire logs ``` ### Setting Up a Heartbeat ``` 1. create_schedule(agentId: "my-agent", triggerType: "HEARTBEAT", heartbeatIntervalSeconds: 300, name: "Health Heartbeat") → { scheduleId: "hb-1", description: "Every 5 minutes", conversationStrategy: "persistent" } # Heartbeats default to: persistent conversation, "heartbeat" message, drift-proof scheduling 2. read_schedule(scheduleId: "hb-1") → check next fire time and conversation ID 3. retry_failed_schedule(scheduleId: "hb-1") → requeue if dead-lettered ``` ### Running a Multi-Agent Discussion ``` 1. describe_discussion_styles → see all available styles with examples 2. create_group(name: "Architecture Review", memberAgentIds: "expert-1,expert-2", moderatorAgentId: "moderator", style: "PEER_REVIEW") → { groupId: "g1" } 3. discuss_with_group(groupId: "g1", question: "Should we use microservices?") → { transcript: [...], synthesizedAnswer: "Based on all perspectives..." } 4. list_group_conversations(groupId: "g1") → browse past discussions ``` *** ## Tool Reference — Agent Discovery & Managed Conversations EDDI provides **two tiers** of conversation management: | Tier | Tools | Conversations | Use Case | | ------------- | --------------------------------------- | ----------------------------------- | ---------------------------------------- | | **Low-level** | `create_conversation` + `talk_to_agent` | Multiple per user, manually managed | Custom apps, multi-conversation UIs | | **Managed** | `chat_managed` | One per intent+userId, auto-created | Single-window chat, intent-based routing | The managed tier relies on **agent triggers** — mappings from an *intent* string to one or more agent deployments. Use the discovery and trigger tools below to configure and interact with this system. ### `discover_agents` Discover deployed agents with their capabilities. Returns an enriched list of deployed agents, cross-referenced with intent mappings from agent triggers. This is the **best way to find agents by purpose**. **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | -------------- | -------------------------------------------------------- | | `filter` | string | No | `""` | Filter agents by name (case-insensitive substring match) | | `environment` | string | No | `"production"` | Environment: `production`, `production`, or `test` | **Response:** ```json { "count": 80, "agents": [ { "agentId": "692f7fe8...", "name": "Bob Marley 2", "description": "gemini powered Agent", "version": 1, "status": "READY", "environment": "production", "intents": ["bob-marley-2-692f7fe8d6c14292d2b7f70c"] }, { "agentId": "64513b3c...", "name": "Agent Father", "description": "Agent to create Connector Agents...", "version": 110, "status": "READY", "environment": "production" } ] } ``` > **Note:** The `intents` array only appears for agents that have agent triggers configured. Agents without triggers are still returned — they can be interacted with via `chat_with_agent` (low-level tier) but not via `chat_managed`. *** ### `chat_managed` Send a message to an agent using **intent-based managed conversations**. Unlike `chat_with_agent` (which requires a agentId and creates multiple conversations), this tool uses an *intent* to find the right agent and maintains **exactly one conversation per intent+userId** — like a single chat window. The conversation is auto-created on first message and reused on subsequent calls. Requires an agent trigger to be configured for the intent (see `list_agent_triggers` / `create_agent_trigger`). **Parameters:** | Parameter | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------ | | `intent` | string | **Yes** | Intent that maps to an agent trigger. E.g. `"customer_support"` | | `userId` | string | **Yes** | User ID for conversation management (one conversation per intent+userId) | | `message` | string | **Yes** | The user message to send | | `environment` | string | No | Environment: `production` (default), `production`, or `test` | **Response:** ```json { "environment": "production", "conversationId": "69bc8b93...", "agentId": "692f7fe8...", "userId": "user-123", "intent": "bob-marley-2-692f7fe8...", "actions": ["send_message", "unknown"], "conversationState": "READY", "response": { "conversationOutputs": [{ "output": [{ "type": "text", "text": "Hello there! ..." }] }], "conversationSteps": [...] } } ``` **Behavior:** * **First call** with a new intent+userId: creates a new conversation and sends the message * **Subsequent calls** with the same intent+userId: reuses the existing conversation (like continuing in the same chat window) * Returns an error if no agent trigger is configured for the given intent *** ### `list_agent_triggers` List all agent triggers (intent→agent mappings). Returns all configured intents with their agent deployments. Agent triggers enable intent-based conversation management via `chat_managed`. **Parameters:** None. **Response:** ```json { "count": 48, "triggers": [ { "intent": "customer_support", "agentDeployments": [ { "environment": "production", "agentId": "6544db9b...", "initialContext": {} } ] } ] } ``` > **Tip:** Each trigger can map to **multiple agent deployments** — useful for A/B testing or environment-specific routing. *** ### `create_agent_trigger` Create an agent trigger that maps an intent to one or more agents. Once created, the intent can be used with `chat_managed` to talk to the agent. **Parameters:** | Parameter | Type | Required | Description | | --------- | ------------- | -------- | --------------------------------------------- | | `config` | string (JSON) | **Yes** | Full trigger configuration (see schema below) | **Config schema:** ```json { "intent": "customer_support", "agentDeployments": [ { "agentId": "64513b3c...", "environment": "production", "initialContext": { "language": { "type": "string", "value": "en" } } } ] } ``` | Field | Type | Required | Description | | ----------------------------------- | ------ | -------- | ---------------------------------------------------------------------------------- | | `intent` | string | **Yes** | Unique intent identifier. Convention: `slug-agentId` (e.g. `support-agent-abc123`) | | `agentDeployments` | array | **Yes** | List of agent deployments this intent routes to | | `agentDeployments[].agentId` | string | **Yes** | The agent ID to route messages to | | `agentDeployments[].environment` | string | No | Deployment environment (default: `production`) | | `agentDeployments[].initialContext` | object | No | Key-value pairs injected into the conversation context on creation | **Response:** ```json { "intent": "customer_support", "status": 200, "action": "created" } ``` *** ### `update_agent_trigger` Update an existing agent trigger. Changes the agent deployments for a given intent (e.g., to point to a new agent version, add A/B routing, or change the initial context). **Parameters:** | Parameter | Type | Required | Description | | --------- | ------------- | -------- | -------------------------------------------------------------------------- | | `intent` | string | **Yes** | The intent to update | | `config` | string (JSON) | **Yes** | Full updated trigger configuration (same schema as `create_agent_trigger`) | **Response:** ```json { "intent": "customer_support", "status": 200, "action": "updated" } ``` *** ### `delete_agent_trigger` Delete an agent trigger for a given intent. After deletion, `chat_managed` calls with this intent will return an error. Existing conversations are **not** deleted — they become orphaned but can still be read. **Parameters:** | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------- | | `intent` | string | **Yes** | The intent to delete | **Response:** ```json { "intent": "customer_support", "status": 200, "action": "deleted" } ``` *** ### End-to-End Example: Setting Up Managed Chat ``` # 1. Create an agent (using setup_agent or the Manager UI) setup_agent(name: "Support Agent", systemPrompt: "You are a helpful support agent...", ...) → { agentId: "abc123", version: 1, status: "deployed" } # 2. Create a trigger mapping an intent to this agent create_agent_trigger(config: { "intent": "customer_support", "agentDeployments": [{ "agentId": "abc123", "environment": "production" }] }) # 3. Chat using the intent — conversation auto-created chat_managed(intent: "customer_support", userId: "user-1", message: "I need help with billing") → { conversationId: "conv-789", response: { output: "I'd be happy to help..." } } # 4. Continue the same conversation (same conversationId reused) chat_managed(intent: "customer_support", userId: "user-1", message: "Can you check order #1234?") → { conversationId: "conv-789", response: { output: "Let me look that up..." } } # 5. Different user gets their own conversation chat_managed(intent: "customer_support", userId: "user-2", message: "Hello") → { conversationId: "conv-999", response: { output: "Welcome! How can I help?" } } # 6. Discover what's available discover_agents(filter: "Support") → shows the agent with its intent ``` ## Configuration In `application.properties`: ```properties # MCP Server — Streamable HTTP at /mcp quarkus.mcp-server.http.root-path=/mcp # Documentation path for MCP resources (default: docs/) eddi.docs.path=docs ``` ## Tool Filtering EDDI uses a **whitelist-based `ToolFilter`** (`McpToolFilter.java`) to control which tools are exposed via MCP. **Why?** EDDI's langchain4j integration registers internal agent tools (calculator, datetime, websearch, etc.) that are meant ONLY for agent pipeline execution — not for external MCP clients. The `ToolFilter` SPI only sees a tool's *name* (not its declaring class or annotation type), so the whitelist is by name. It currently exposes all 74 intended tools — conversation, admin/resource/schedule/channel, setup, group, **HITL approvals** (`McpHitlTools`), **persistent user memory** (`McpMemoryTools`), and **GDPR/CCPA** (`McpGdprTools`). To add a new MCP tool: add its name to the `MCP_TOOLS` set in `McpToolFilter.java`. A quarkus-MCP `@Tool` has no other invocation path, so a tool that is *not* whitelisted is unreachable dead code. `McpToolFilterTest.test_allMcpToolMethods_areWhitelisted()` auto-discovers every `@Tool` in the `engine.mcp` package and fails the build if any is missing from the whitelist — so forgetting this step is caught by CI. ## Authentication & Authorization * The MCP endpoint inherits EDDI's existing OIDC/Keycloak authentication * When auth is enabled (`quarkus.oidc.tenant-enabled=true`), MCP clients must provide valid tokens * Authorization is enforced **in-code**, not via `@RolesAllowed`: most tools call `requireRole(identity, authEnabled, "")` (`McpToolUtils`), and the HITL tools use the shared `HitlAccessGuard` (per-conversation owner / `eddi-admin` / `eddi-approver`). When `authorization.enabled=false` (the default dev posture) `requireRole` is a no-op — production is guarded by `AuthStartupGuard`, which fails startup if OIDC is disabled. * **Future**: Per-agent MCP access control via agent configuration for multi-tenant SaaS ### Role Mapping These are the **actual Keycloak role strings** the tools check (not aliases). Roles are additive in intent — grant an editor/admin the read scope too. For exact per-tool roles see the code (`requireRole` calls) and the per-category sections above (HITL / Memory / GDPR). | Role | Scope | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eddi-viewer` | Read-only + running conversations: `list_*`, `read_*`, `get_*`, `discover_agents`, `chat_with_agent`/`talk_to_agent`/`chat_managed`, `read_agent_logs`/`read_audit_trail`, and the memory **read** tools (`list_user_memories`, `get_visible_memories`, `search_user_memories`, `get_memory_by_key`, `count_user_memories`) | | `eddi-editor` | Viewer + authoring: `setup_agent`, `create_api_agent`, group create/update, resource create/update, trigger/schedule/channel authoring | | `eddi-admin` | Editor + destructive/deployment ops: `deploy_agent`/`undeploy_agent`, `delete_*`, resource delete, and the **memory writes** (`upsert_user_memory`, `delete_user_memory`, `delete_all_user_memories`) + **GDPR** tools (`delete_user_data`, `export_user_data`) | | `eddi-approver` | Decide HITL approvals (with the conversation owner and `eddi-admin`): `resume_conversation`, `approve_group_phase`, `cancel_*`, `*_pending_approvals`, `*_approval_status` — see [HITL](https://github.com/labsai/EDDI/tree/main/docs/hitl.md#who-may-decide) | ## Sentiment Monitoring Agents created with `enableSentimentAnalysis=true` (via `setup_agent` or `create_api_agent`) include sentiment data in every LLM response. The sentiment object includes: `score` (-1.0 to +1.0), `trend`, `emotions`, `intent`, `urgency`, `confidence`, and `topicTags`. This data is stored in conversation memory and can be: * Read via `read_conversation` (in the conversation snapshot) * Aggregated for monitoring dashboards (Manager UI log panel) * Used for alerting (e.g., negative sentiment spike triggers notification) ## Architecture ``` ┌──────────────┐ ┌──────────────────────┐ │ MCP Client │────▶│ quarkus-mcp-server │ │ (Claude,IDE) │◀────│ Streamable HTTP /mcp │ └──────────────┘ └──────────┬───────────┘ │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ McpConv. │ │ McpAdmin │ │ McpSetup │ │ Tools │ │ Tools │ │ Tools │ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │ │ │ ┌─────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐ │ REST API │ │ REST API │ │ REST API │ │ endpoints │ │ endpoints │ │ + OpenAPI │ └────────────┘ └────────────┘ └────────────┘ ┌──────────────────────────────────────────┐ │ McpDocResources │ │ @Resource / @ResourceTemplate │ │ eddi://docs/{name} (filesystem I/O) │ └──────────────────────────────────────────┘ ``` ## MCP Client — Agents as MCP Consumers In addition to acting as an MCP server, EDDI agents can also **consume external MCP servers** as tool providers. This enables agents to call tools exposed by other MCP-compatible services during conversations. ### Configuration External MCP servers are configured as **`mcpcalls` workflow extensions** — a first-class, versioned configuration resource (the MCP equivalent of `httpcalls`). There is **no** inline MCP server array on the LLM task. **Step 1 — create an `mcpcalls` configuration** (`POST /mcpcallsstore/mcpcalls`), one per MCP server: ```json { "mcpServerUrl": "http://localhost:7070/mcp", "name": "eddi-docs", "transport": "http", "apiKey": "${vault:mcp-api-key}", "timeoutMs": 30000, "toolsWhitelist": ["read_docs", "list_docs"], "toolsBlacklist": [] } ``` | Field | Type | Required | Default | Description | | ---------------- | --------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `mcpServerUrl` | string | **Yes** | — | MCP server URL | | `name` | string | No | — | Human-readable name for logging | | `transport` | string | No | `"http"` | Informational only today — `McpToolProviderManager` always connects via Streamable HTTP | | `apiKey` | string | No | — | API key, sent as `Authorization: Bearer `. Resolved through global variables and `${vault:key}` references | | `timeoutMs` | long | No | `30000` | Connection and request timeout in milliseconds | | `toolsWhitelist` | string\[] | No | — | If non-empty, only these tool names are exposed (names as returned by the server's `tools/list`) | | `toolsBlacklist` | string\[] | No | — | Tool names to exclude. Applied *after* the whitelist | | `mcpCalls` | object\[] | No | — | Deterministic, action-triggered tool bindings (see *Pipeline mode* below). Omit for agent-mode-only servers | **Step 2 — add an `mcpcalls` step to the agent's workflow**, before the LLM step: ```json { "workflowSteps": [ { "type": "eddi://ai.labs.parser", "config": { "uri": "eddi://ai.labs.parser/parserstore/parsers/?version=1" } }, { "type": "eddi://ai.labs.behavior", "config": { "uri": "eddi://ai.labs.rules/rulestore/rulesets/?version=1" } }, { "type": "eddi://ai.labs.mcpcalls", "config": { "uri": "eddi://ai.labs.mcpcalls/mcpcallsstore/mcpcalls/?version=1" } }, { "type": "eddi://ai.labs.llm", "config": { "uri": "eddi://ai.labs.llm/llmstore/llms/?version=1" } } ] } ``` A workflow may contain any number of `mcpcalls` steps — one per MCP server. ### Two Modes, One Configuration * **Agent mode** — `AgentOrchestrator.discoverMcpCallTools()` traverses the agent → workflow → every `mcpcalls` step at execution time, connects to each server, applies that config's whitelist/blacklist, and hands the surviving tools to the LLM. The LLM calls them reactively. Controlled by `enableMcpCallTools` on the LLM task (`langchain.json`), **default `true`** — no per-server opt-in is needed: ```json { "tasks": [ { "type": "anthropic", "enableMcpCallTools": false } ] } ``` * **Pipeline mode** — `McpCallsTask` (`eddi://ai.labs.mcpcalls`, pipeline position `Parser → Rules → HttpCalls → McpCalls → LLM → Output`) matches behavior-rule actions against `mcpCalls[].actions` and invokes the named tool deterministically, with **no LLM involved**. Only active when `mcpCalls` is non-empty. Both modes read the same `mcpcalls` configuration; they are not mutually exclusive. ### Using `setup_agent` with MCP Servers ``` setup_agent( agentName: "My Agent", systemPrompt: "You are helpful", mcpServerUrls: "http://localhost:7070/mcp, https://tools.example.com/mcp", ... ) ``` The `mcpServerUrls` parameter accepts a comma-separated list of URLs. For each URL, `AgentSetupService` creates one `mcpcalls` configuration (`transport: "http"`, `timeoutMs: 30000`, no whitelist/blacklist, no `mcpCalls` bindings — i.e. agent-mode only) and inserts a matching `eddi://ai.labs.mcpcalls` step into the generated workflow ahead of the LLM step. Nothing is written inline into the LLM configuration. ### Architecture ``` ┌──────────────┐ ┌──────────────────────┐ │ User sends │────▶│ LlmTask │ │ message │ │ (EDDI pipeline) │ └──────────────┘ └──────────┬────────────┘ │ ┌───────────┼───────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Built-in │ │ Custom │ │ MCP │ │ Tools │ │ Tools │ │ Tools │ │(calc,dt) │ │(HttpCall)│ │(external)│ └──────────┘ └──────────┘ └────┬─────┘ │ ┌───────────┼───────────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ MCP Server 1 │ │ MCP Server 2 │ │ (EDDI docs) │ │ (3rd party) │ └──────────────┘ └──────────────┘ ``` ### Key Behaviors * **Graceful degradation**: Failed MCP connections log warnings but never kill the pipeline * **Connection caching**: `McpToolProviderManager` reuses connections across conversation turns * **Budget/rate-limiting**: MCP tools are subject to the same `ToolExecutionService` controls as built-in tools * **Vault references**: API keys support `${vault:key}` syntax via `SecretResolver` * **Clean shutdown**: All MCP clients are closed on application shutdown via `@PreDestroy`