MCP Execution Model

MCP Execution Model

Runtime Topology

flowchart LR
  UI[Browser] --> BFF[kobi-ai /api/ai/*]
  BFF --> ENG[kobi-agent-service]
  ENG --> TE[tool_executor node]
  TE --> MCP[kobi-mcp-server]
  MCP --> DB[(Supabase)]

Active Tool Families

Current MCP registry includes these families:

• Shared: search_perplexity
• Idea: create_chunk, create_idea, create_research, create_solution, propose_crystallization, reject_with_feedback, propose_deep_research
• Strategy: strategy_item, clear_framework
• Maps: map_location, save_location, heat_zone, air_quality

Interaction tools like confirm, ask_opinion, and select_option are not registered in current MCP code.

Execution Contract

Engine tool executor injects context fields into MCP calls:

• approved: true
• userId
• threadId
• projectId
• agentType

For mutation tools, MCP normalizes/derives:

• actionId
• idempotencyKey

Validation Stack Inside MCP

1. authenticateRequest: requires userId, checks thread ownership when threadId is present.
2. validateToolAccess: enforces agent scope and idea-phase gating (when applicable).
3. enforceMutationContext: for mutating tools, requires approved=true plus scope IDs and idempotency.

HITL Clarification

• Approval interrupt lifecycle is owned by engine (interrupt + /resume).
• MCP tools are execution handlers and do not emit approval-card protocol fields.
• Browser approval decisions are sent via BFF /api/ai/resume and normalized to engine resume payload.

Known Caveats in Current Code

• propose_deep_research is registered, but currently not included in GATED_TOOLS and MUTATING_TOOLS sets in MCP tool registry.
• Engine workflow YAML still lists some non-registered tool names; runtime ultimately depends on MCP list_tools conversion.

Operational Expectations

• Tool calls should be deterministic under retries due to idempotency handling.
• Any missing scope fields on mutating tools should fail fast with validation errors.
• Engine should log tool execution context (userId, threadId, projectId) for traceability.