Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Status: Accepted (Go)
Date: 2026-03-14
Decision Makers: Platform Foundation team
Supersedes: N/A

​
Context

PF-72 Phases 1–3 delivered skill-aware agent execution via ai-skill-execute. Phase 4 adds Model Context Protocol (MCP) server support so agents can call external tools (e.g., Context7 for documentation lookup, Supabase MCP for schema introspection) in a governed way. MCP defines a standard protocol for AI models to interact with external tools. The key question is whether MCP servers can be invoked from Deno-based Supabase Edge Functions and whether the security model (allowlist-only, no PHI) can be enforced.

​
Decision

Go: Integrate allowlisted MCP servers into ai-skill-execute using HTTP transport only.
  • MCP servers that support Streamable HTTP or standard HTTP POST transport are compatible with Deno edge functions.
  • MCP servers that require stdio transport are not compatible (Deno edge functions cannot spawn long-lived child processes).
  • All MCP invocations go through a shared _shared/mcp-client.ts utility with allowlist enforcement, PHI scanning, and retry logic.

​
Alternatives Considered

​
1. stdio-based MCP (e.g., Node MCP Server package)

  • Rejected. Deno edge functions run in an isolate; no child_process.spawn(), no long-lived stdio pipes. The official Supabase MCP Server npm package is Node-only and incompatible.

​
2. No MCP — hardcode external tool integrations

  • Rejected. Hardcoding each external tool (Context7, Supabase) as a custom tool handler in _shared/tool-handlers.ts works but doesn’t scale. MCP provides a standard protocol and tool discovery.

​
3. MCP via mcp-lite on Edge Functions

  • Considered and viable. mcp-lite (npm:mcp-lite@^0.10.0) provides StreamableHttpTransport compatible with Deno. Can be used both for hosting MCP servers on edge functions and as a client. Selected as the recommended client library for HTTP transport.

​
4. Raw HTTP fetch to MCP endpoints

  • Viable fallback. If mcp-lite introduces issues, raw fetch() to MCP HTTP endpoints with JSON-RPC payloads is always possible from Deno edge. Less ergonomic but zero dependencies.

​
MCP Server Evaluations

​
Context7

  • Protocol: HTTP (Streamable HTTP transport via hosted service).
  • Compatibility: ✅ Compatible. Context7 MCP is available as a hosted HTTP service. Edge functions can call it via fetch() or mcp-lite StreamableHttpTransport.
  • Auth: API key or no auth (public documentation lookup).
  • PHI Risk: Low — Context7 serves library documentation only; no patient data involved. PHI scan still applied to outbound requests as defense-in-depth.
  • Conclusion: Compatible. Use for documentation lookup tools in skills.

​
Supabase MCP

Three variants evaluated:
VariantDeno Edge CompatibleNotes
Supabase MCP Server (Node npm)❌Requires Node.js runtime, stdio transport
MCP on Edge Functions (Deno.serve)✅Self-hosted MCP server as another edge function
mcp-lite on Edge Functions✅Lightweight, Fetch API based, npm:mcp-lite@^0.10.0
  • Selected: mcp-lite for client-side invocation of external MCP servers. If Encore hosts its own MCP server later, use Deno.serve() + mcp-lite StreamableHttpTransport.
  • Auth: Service role key for Supabase operations; scoped to read-only operations for agent use.
  • PHI Risk: Medium if querying patient tables — mitigated by PHI scan on responses and restricting to schema/metadata operations only.
  • Conclusion: Compatible via mcp-lite. Restrict to schema introspection and metadata; no direct patient data queries through MCP.

​
Security

  1. Allowlist-only: Only MCP servers listed in MCP_ALLOWLIST env variable may be invoked. No client-supplied MCP endpoints (constitution §4.3.1).
  2. No PHI/PII: All outbound MCP requests and inbound MCP responses are scanned via detectPHI() from _shared/phi-detection.ts. Requests containing PHI are rejected before sending (constitution §4.3.2).
  3. Validate before invoke: The orchestration layer checks skill-requested MCPs against the allowlist before constructing any MCP connection. Non-allowlisted servers are rejected with an error response and logged for audit.
  4. Audit logging: Every MCP invocation (success or failure) is logged with org_id, skill_id, mcp_server, and timestamp. Rejections include reason: 'not_allowlisted'.
  5. Feature flag: MCP_ENABLED defaults to false. MCP logic is entirely skipped when disabled.

​
Consequences

​
Positive

  • Standard protocol for external tool integration; new MCP servers can be added by updating the allowlist and optionally extending mcp-client.ts.
  • Skills declare MCP dependencies via custom_fields.mcp_servers; no schema migration needed.
  • Feature flag provides safe rollback.

​
Negative

  • Runtime dependency on external MCP server availability; mitigated by retry (2x backoff) and fallback (agent continues without failed MCP tool).
  • mcp-lite is a relatively new package; pinned to ^0.10.0 to avoid pre-release TypeScript issues.

​
Neutral

  • No new database tables required for Phase 4 MVP.
  • Allowlist management is platform-wide (env/secrets); org-level opt-out deferred to future enhancement.

​
References