> ## 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.

# ADR-003: PF-72 Phase 4 — MCP Integration Go/No-Go

> 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 extern…

**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:

| Variant                            | Deno Edge Compatible | Notes                                              |
| ---------------------------------- | -------------------- | -------------------------------------------------- |
| 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

* [PF-72 Phase 4 Expansion Spec](https://github.com/Encore-OS/encoreos/blob/development/specs/pf/specs/PF-72-PHASE-4-EXPANSION.md)
* [PF-72 Integration Doc](/architecture/integrations/agent-sdk-integration-integration)
* [Constitution §4.3](https://github.com/Encore-OS/encoreos/blob/development/constitution.md) — AI integration security
* [mcp-lite](https://github.com/fiberplane/mcp-lite) — Deno-compatible MCP client
* [Supabase MCP guide](https://supabase.com/docs/guides/functions/examples/mcp-server-mcp-lite)