From 7873995dace1c1c43b5a95105d6814a19870b1f4 Mon Sep 17 00:00:00 2001
From: Trailgenic <mike@trailgenic.com>
Date: Mon, 13 Jul 2026 15:41:52 -0700
Subject: [PATCH] Use official MCP SDK for Ella server conformance

---
 .env.example             |   3 +
 .github/workflows/ci.yml |  21 +++
 app/entity.json/route.ts |  24 +--
 app/mcp/route.ts         | 311 +++++++++++----------------------------
 app/system/mcp/page.tsx  |  96 ++++--------
 docs/mcp-deployment.md   |   9 ++
 lib/ella-mcp-schemas.ts  | 102 +++++++++++++
 lib/ella-mcp-server.ts   | 287 ++++++++++++++++++++++++++++++++++++
 lib/ella-registry.ts     | 102 +++++++++++++
 package.json             |  12 +-
 tests/mcp.test.ts        | 176 ++++++++++++++++++++++
 11 files changed, 823 insertions(+), 320 deletions(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 docs/mcp-deployment.md
 create mode 100644 lib/ella-mcp-schemas.ts
 create mode 100644 lib/ella-mcp-server.ts
 create mode 100644 lib/ella-registry.ts
 create mode 100644 tests/mcp.test.ts

diff --git a/.env.example b/.env.example
index 9c04864..5c36c83 100644
--- a/.env.example
+++ b/.env.example
@@ -2,3 +2,6 @@ ANTHROPIC_API_KEY=
 OPENAI_API_KEY=
 TRACE_STORAGE_URL=
 DEFAULT_CONFIDENCE_THRESHOLD=0.75
+
+# Comma-separated browser origins allowed to call the public read-only MCP endpoint.
+MCP_ALLOWED_ORIGINS=https://ellaentity.ai,https://www.ellaentity.ai,https://mcp.ellaentity.ai
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..d9deb18
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build
diff --git a/app/entity.json/route.ts b/app/entity.json/route.ts
index f371352..ee7177e 100644
--- a/app/entity.json/route.ts
+++ b/app/entity.json/route.ts
@@ -1,28 +1,8 @@
 import { NextResponse } from 'next/server'
-import { ELLA_GLOBAL_SCHEMA, ELLA_MCP_SCHEMA, ELLA_ORG_SCHEMA, ELLA_SYSTEM_SCHEMA } from '@/app/schema/ella'
+import { ellaEntityGraph } from '@/lib/ella-registry'
 
 export function GET() {
-  const graph = {
-    '@context': 'https://schema.org/',
-    '@graph': [ELLA_GLOBAL_SCHEMA, ELLA_ORG_SCHEMA, ELLA_SYSTEM_SCHEMA, ELLA_MCP_SCHEMA].flatMap((schema) => {
-      if (Array.isArray(schema)) {
-        return schema.flatMap((entry) => {
-          if (entry && typeof entry === 'object' && '@graph' in entry) {
-            return (entry as { '@graph': unknown[] })['@graph']
-          }
-          return [entry]
-        })
-      }
-
-      if (schema && typeof schema === 'object' && '@graph' in schema) {
-        return (schema as { '@graph': unknown[] })['@graph']
-      }
-
-      return [schema]
-    }),
-  }
-
-  return NextResponse.json(graph, {
+  return NextResponse.json(ellaEntityGraph(), {
     headers: {
       'Content-Type': 'application/ld+json',
       'Cache-Control': 'public, max-age=3600',
diff --git a/app/mcp/route.ts b/app/mcp/route.ts
index 0fb917f..d8aa4ea 100644
--- a/app/mcp/route.ts
+++ b/app/mcp/route.ts
@@ -1,271 +1,124 @@
 import { NextResponse } from 'next/server'
-import {
-  ELLA_COCOGNITION,
-  ELLA_DOMAINS,
-  ELLA_FRAMEWORKS,
-  ELLA_IDENTITY,
-  ELLA_SURFACES,
-  ELLA_WORKS,
-} from '@/lib/entity-data'
+import { handleEllaMcpPost } from '../../lib/ella-mcp-server'
 
-const PROTOCOL_VERSION = '2025-06-18'
-const SERVER_INFO = { name: 'ellaentity-mcp', version: '1.0.0' }
-const TOOL_NAMES = [
-  'ella.identity.get',
-  'ella.domains.get',
-  'ella.frameworks.get',
-  'ella.works.get',
-  'ella.collaboration.get',
-] as const
-const DOMAIN_NAMES = ['longevity', 'environment', 'sleep', 'ai-frameworks'] as const
-const FRAMEWORK_SLUGS = ['four-forces-of-ai-power'] as const
+export const runtime = 'nodejs'
 
-const corsHeaders = {
-  'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Mcp-Session-Id, MCP-Protocol-Version',
-}
-
-type JsonRpcId = string | number | null
-type JsonObject = Record<string, unknown>
-
-type JsonRpcRequest = {
-  jsonrpc?: unknown
-  id?: unknown
-  method?: unknown
-  params?: unknown
-}
-
-const tools = [
-  {
-    name: 'ella.identity.get',
-    description:
-      'Canonical identity record for Ella: entity ID, description, disambiguation, creator, affiliations, sameAs anchors.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'ella.domains.get',
-    description:
-      "Ella's declared domain authority. Optional 'domain' argument: longevity | environment | sleep | ai-frameworks. Omit for all four.",
-    inputSchema: {
-      type: 'object',
-      properties: {
-        domain: { type: 'string', enum: DOMAIN_NAMES },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'ella.frameworks.get',
-    description:
-      "Ella and Mike Ye's declared frameworks. Currently returns The Four Forces of AI Power: Compute, Interface, Alignment, and Energy.",
-    inputSchema: {
-      type: 'object',
-      properties: {
-        framework: { type: 'string', enum: FRAMEWORK_SLUGS },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'ella.works.get',
-    description: 'Co-authored works attributed to Ella with schema types and URLs.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'ella.collaboration.get',
-    description: 'The co-cognition model: division of labor between Mike Ye, Ella, and AI tooling.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      additionalProperties: false,
-    },
-  },
-] as const
+const DEFAULT_ALLOWED_ORIGINS = ['https://ellaentity.ai', 'https://www.ellaentity.ai', 'https://mcp.ellaentity.ai']
+const ALLOW_METHODS = 'POST, OPTIONS'
+const ALLOW_HEADERS = 'Content-Type, Accept, Mcp-Session-Id, MCP-Protocol-Version'
+const REQUIRED_ACCEPT_TYPES = ['application/json', 'text/event-stream'] as const
 
-function jsonResponse(body: unknown, status = 200) {
-  return NextResponse.json(body, { status, headers: corsHeaders })
+function allowedOrigins() {
+  return process.env.MCP_ALLOWED_ORIGINS?.split(',').map((origin) => origin.trim()).filter(Boolean) ?? DEFAULT_ALLOWED_ORIGINS
 }
 
-function emptyResponse(status = 202) {
-  return new NextResponse(null, { status, headers: corsHeaders })
-}
-
-function normalizeId(id: unknown): JsonRpcId {
-  return typeof id === 'string' || typeof id === 'number' || id === null ? id : null
-}
+function corsHeaders(request: Request): Headers | NextResponse {
+  const origin = request.headers.get('origin')
+  const headers = new Headers({
+    'Access-Control-Allow-Methods': ALLOW_METHODS,
+    'Access-Control-Allow-Headers': ALLOW_HEADERS,
+    Vary: 'Origin',
+  })
 
-function rpcResult(id: JsonRpcId, result: unknown) {
-  return jsonResponse({ jsonrpc: '2.0', id, result })
-}
+  if (!origin) {
+    return headers
+  }
 
-function rpcError(id: JsonRpcId, code: number, message: string) {
-  return jsonResponse({ jsonrpc: '2.0', id, error: { code, message } })
-}
+  if (!allowedOrigins().includes(origin)) {
+    return new NextResponse(null, {
+      status: 403,
+      headers,
+    })
+  }
 
-function isJsonObject(value: unknown): value is JsonObject {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+  headers.set('Access-Control-Allow-Origin', origin)
+  return headers
 }
 
-function readParams(params: unknown): JsonObject {
-  return isJsonObject(params) ? params : {}
-}
+function jsonRpcError(request: Request, status: number, code: number, message: string) {
+  const cors = corsHeaders(request)
 
-function noUnexpectedArguments(args: JsonObject): boolean {
-  return Object.keys(args).length === 0
-}
+  if (cors instanceof NextResponse) {
+    return cors
+  }
 
-function toolContent(payload: unknown) {
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(payload, null, 2),
+  return NextResponse.json(
+    {
+      jsonrpc: '2.0',
+      id: null,
+      error: {
+        code,
+        message,
       },
-    ],
-  }
+    },
+    {
+      status,
+      headers: cors,
+    },
+  )
 }
 
-function callTool(name: unknown, args: JsonObject) {
-  if (name === 'ella.identity.get') {
-    return noUnexpectedArguments(args) ? toolContent(ELLA_IDENTITY) : null
-  }
-
-  if (name === 'ella.domains.get') {
-    const keys = Object.keys(args)
-    const domain = args.domain
-
-    if (keys.length === 0) {
-      return toolContent(ELLA_DOMAINS)
-    }
+function hasJsonContentType(request: Request) {
+  return request.headers.get('content-type')?.toLowerCase().includes('application/json') ?? false
+}
 
-    if (
-      keys.length === 1 &&
-      typeof domain === 'string' &&
-      DOMAIN_NAMES.includes(domain as (typeof DOMAIN_NAMES)[number])
-    ) {
-      return toolContent(ELLA_DOMAINS[domain as keyof typeof ELLA_DOMAINS])
-    }
+function hasRequiredAcceptTypes(request: Request) {
+  const accept = request.headers.get('accept')?.toLowerCase()
 
-    return null
+  if (!accept) {
+    return false
   }
 
-  if (name === 'ella.frameworks.get') {
-    const keys = Object.keys(args)
-    const framework = args.framework
-
-    if (keys.length === 0) {
-      return toolContent(ELLA_FRAMEWORKS)
-    }
-
-    if (
-      keys.length === 1 &&
-      typeof framework === 'string' &&
-      FRAMEWORK_SLUGS.includes(framework as (typeof FRAMEWORK_SLUGS)[number])
-    ) {
-      return toolContent(ELLA_FRAMEWORKS.find((item) => item.slug === framework))
-    }
-
-    return null
-  }
+  return REQUIRED_ACCEPT_TYPES.every((type) => accept.includes(type))
+}
 
-  if (name === 'ella.works.get') {
-    return noUnexpectedArguments(args) ? toolContent(ELLA_WORKS) : null
-  }
+export function OPTIONS(request: Request) {
+  const cors = corsHeaders(request)
 
-  if (name === 'ella.collaboration.get') {
-    return noUnexpectedArguments(args)
-      ? toolContent({ coCognition: ELLA_COCOGNITION, surfaces: ELLA_SURFACES })
-      : null
+  if (cors instanceof NextResponse) {
+    return cors
   }
 
-  return null
+  return new NextResponse(null, {
+    status: 204,
+    headers: cors,
+  })
 }
 
-export function OPTIONS() {
-  return emptyResponse(204)
-}
+export function GET(request: Request) {
+  const cors = corsHeaders(request)
+  const headers = cors instanceof NextResponse ? new Headers(cors.headers) : cors
 
-export function GET() {
-  return jsonResponse({
-    name: SERVER_INFO.name,
-    description: 'Read-only MCP server for the canonical Ella identity layer.',
-    canonicalEntity: 'https://ellaentity.ai/#ella',
-    transport: 'streamable-http',
-    tools: [...TOOL_NAMES],
-    documentation: 'https://ellaentity.ai/system/mcp',
+  headers.set('Allow', ALLOW_METHODS)
+
+  return new NextResponse(null, {
+    status: cors instanceof NextResponse ? 403 : 405,
+    headers,
   })
 }
 
 export async function POST(request: Request) {
-  let body: unknown
+  const cors = corsHeaders(request)
 
-  try {
-    body = await request.json()
-  } catch {
-    return rpcError(null, -32700, 'Parse error')
+  if (cors instanceof NextResponse) {
+    return cors
   }
 
-  if (!isJsonObject(body)) {
-    return rpcError(null, -32600, 'Invalid Request')
+  if (!hasJsonContentType(request)) {
+    return jsonRpcError(request, 415, -32600, 'Content-Type must be application/json')
   }
 
-  const rpcRequest = body as JsonRpcRequest
-  const id = normalizeId(rpcRequest.id)
-
-  if (rpcRequest.jsonrpc !== '2.0' || typeof rpcRequest.method !== 'string') {
-    return rpcError(id, -32600, 'Invalid Request')
+  if (!hasRequiredAcceptTypes(request)) {
+    return jsonRpcError(request, 406, -32600, 'Accept must include application/json and text/event-stream')
   }
 
-  if (rpcRequest.method === 'notifications/initialized') {
-    return emptyResponse(202)
-  }
-
-  if (rpcRequest.method === 'initialize') {
-    const params = readParams(rpcRequest.params)
-    const requestedProtocolVersion =
-      typeof params.protocolVersion === 'string' ? params.protocolVersion : PROTOCOL_VERSION
-
-    return rpcResult(id, {
-      protocolVersion: requestedProtocolVersion,
-      capabilities: { tools: {} },
-      serverInfo: SERVER_INFO,
-    })
-  }
-
-  if (rpcRequest.method === 'ping') {
-    return rpcResult(id, {})
-  }
-
-  if (rpcRequest.method === 'tools/list') {
-    return rpcResult(id, { tools })
-  }
-
-  if (rpcRequest.method === 'tools/call') {
-    const params = readParams(rpcRequest.params)
-    const args = params.arguments
-
-    if (typeof params.name !== 'string' || (args !== undefined && !isJsonObject(args))) {
-      return rpcError(id, -32602, 'Invalid params')
-    }
-
-    const toolArgs: JsonObject = args === undefined ? {} : args
-    const result = callTool(params.name, toolArgs)
-
-    if (!result) {
-      return rpcError(id, -32602, 'Invalid params')
+  try {
+    return await handleEllaMcpPost(request, cors)
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return jsonRpcError(request, 400, -32700, 'Parse error')
     }
 
-    return rpcResult(id, result)
+    return jsonRpcError(request, 500, -32603, 'Internal server error')
   }
-
-  return rpcError(id, -32601, 'Method not found')
 }
diff --git a/app/system/mcp/page.tsx b/app/system/mcp/page.tsx
index aa0efa9..0346b89 100644
--- a/app/system/mcp/page.tsx
+++ b/app/system/mcp/page.tsx
@@ -1,89 +1,55 @@
 import { SchemaEyebrow } from '@/app/components/SchemaEyebrow'
-
 import { ELLA_MCP_SCHEMA } from '@/app/schema/ella'
+import {
+  ELLA_CANONICAL_ENTITY_ID,
+  ELLA_MCP_PROTOCOL_VERSIONS,
+  ELLA_MCP_RESOURCES,
+  ELLA_MCP_SERVER_INFO,
+  ELLA_MCP_TOOL_NAMES,
+} from '@/lib/ella-registry'
 
 const endpoints = [
-  {
-    host: 'mcp.trailgenic.com',
-    url: 'https://mcp.trailgenic.com',
-    exposes: 'TrailGenic longevity, environmental adaptation, high-altitude hiking, and field-method intelligence.',
-  },
-  {
-    host: 'mcp.exmxc.ai',
-    url: 'https://mcp.exmxc.ai',
-    exposes: 'exmxc AI intelligence frameworks, entity clarity systems, agent-readiness doctrine, and infrastructure-convergence models.',
-  },
-  {
-    host: 'mcp.mikeye.com',
-    url: 'https://mcp.mikeye.com',
-    exposes: 'Mike Ye institutional identity, operator context, creator attribution, and cross-property intelligence references.',
-  },
-  {
-    host: 'mcp.ellaentity.ai',
-    url: 'https://mcp.ellaentity.ai',
-    exposes: 'It serves the canonical identity graph directly through ella.identity.get, ella.domains.get, ella.works.get, and ella.collaboration.get.',
-  },
+  { host: 'mcp.trailgenic.com', url: 'https://mcp.trailgenic.com', exposes: 'TrailGenic longevity, environmental adaptation, high-altitude hiking, and field-method intelligence.' },
+  { host: 'mcp.exmxc.ai', url: 'https://mcp.exmxc.ai', exposes: 'exmxc AI intelligence frameworks, entity clarity systems, agent-readiness doctrine, and infrastructure-convergence models.' },
+  { host: 'mcp.mikeye.com', url: 'https://mcp.mikeye.com', exposes: 'Mike Ye institutional identity, operator context, creator attribution, and cross-property intelligence references.' },
+  { host: 'mcp.ellaentity.ai', url: 'https://mcp.ellaentity.ai', exposes: `Native public read-only Streamable HTTP MCP endpoint for ${ELLA_CANONICAL_ENTITY_ID}.` },
 ]
 
 export function generateMetadata() {
-  return {
-    title: 'Ella MCP Access — Machine Interfaces',
-    description:
-      'Visible documentation and JSON-LD schema for Ella MCP access across TrailGenic, exmxc, and MikeYe.com endpoints.',
-    alternates: { canonical: 'https://ellaentity.ai/system/mcp' },
-  }
+  return { title: 'Ella MCP Access — Machine Interfaces', description: 'Visible documentation and JSON-LD schema for Ella MCP access across TrailGenic, exmxc, and MikeYe.com endpoints.', alternates: { canonical: 'https://ellaentity.ai/system/mcp' } }
 }
 
-const pageSchema = {
-  '@context': 'https://schema.org/',
-  '@graph': [
-    {
-      '@type': 'WebPage',
-      '@id': 'https://ellaentity.ai/system/mcp#webpage',
-      url: 'https://ellaentity.ai/system/mcp',
-      name: 'Ella MCP Access — Machine Interfaces',
-      isPartOf: { '@id': 'https://ellaentity.ai/#website' },
-      mainEntity: { '@id': 'https://ellaentity.ai/#ella' },
-      about: { '@id': 'https://ellaentity.ai/#ella' },
-      inLanguage: 'en-US',
-    },
-  ],
-}
+const pageSchema = { '@context': 'https://schema.org/', '@graph': [{ '@type': 'WebPage', '@id': 'https://ellaentity.ai/system/mcp#webpage', url: 'https://ellaentity.ai/system/mcp', name: 'Ella MCP Access — Machine Interfaces', isPartOf: { '@id': 'https://ellaentity.ai/#website' }, mainEntity: { '@id': ELLA_CANONICAL_ENTITY_ID }, about: { '@id': ELLA_CANONICAL_ENTITY_ID }, inLanguage: 'en-US' }] }
 
 export default function Page() {
   return (
     <main>
-      <script
-        type="application/ld+json"
-        dangerouslySetInnerHTML={{ __html: JSON.stringify(pageSchema) }}
-      />
-      <script
-        type="application/ld+json"
-        dangerouslySetInnerHTML={{ __html: JSON.stringify(ELLA_MCP_SCHEMA) }}
-      />
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(pageSchema) }} />
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(ELLA_MCP_SCHEMA) }} />
 
       <section className="content-panel" aria-labelledby="mcp-title">
         <h1 id="mcp-title">Ella MCP Access</h1>
-        <p>
-          This page documents the machine interfaces associated with Ella. The MCP schema is emitted
-          only on this page so crawlers can distinguish general site identity from protocol access
-          documentation.
-        </p>
+        <p>This page documents Ella's public, read-only Model Context Protocol surfaces. The canonical entity ID is <code>{ELLA_CANONICAL_ENTITY_ID}</code>.</p>
+        <p>The native server is <code>{ELLA_MCP_SERVER_INFO.name}</code> version <code>{ELLA_MCP_SERVER_INFO.version}</code>. It supports MCP protocol versions <code>{ELLA_MCP_PROTOCOL_VERSIONS.join(', ')}</code>.</p>
+        <p>Public MCP access exposes canonical identity, domains, frameworks, works, collaboration records, and the entity graph. It does not expose private conversations, credentials, memory, traces, internal prompts, unpublished content, private user information, or <code>/api/process</code>.</p>
       </section>
 
       <section aria-labelledby="mcp-endpoints">
         <SchemaEyebrow label="potentialAction → EntryPoint" />
         <h2 id="mcp-endpoints">MCP endpoints</h2>
-        <div className="work-list">
-          {endpoints.map((endpoint) => (
-            <article className="work-card" key={endpoint.host}>
-              <span className="work-type">EntryPoint</span>
-              <h3>{endpoint.host}</h3>
-              <p><a href={endpoint.url}>{endpoint.url}</a></p>
-              <p>{endpoint.exposes}</p>
-            </article>
-          ))}
-        </div>
+        <div className="work-list">{endpoints.map((endpoint) => <article className="work-card" key={endpoint.host}><span className="work-type">EntryPoint</span><h3>{endpoint.host}</h3><p><a href={endpoint.url}>{endpoint.url}</a></p><p>{endpoint.exposes}</p></article>)}</div>
+      </section>
+
+      <section aria-labelledby="mcp-tools">
+        <h2 id="mcp-tools">Tools</h2>
+        <ul>{ELLA_MCP_TOOL_NAMES.map((tool) => <li key={tool}><code>{tool}</code></li>)}</ul>
+        <p>Example: call <code>ella.domains.get</code> with <code>{JSON.stringify({ domain: 'ai-frameworks' })}</code>, or omit arguments to return all domains.</p>
+      </section>
+
+      <section aria-labelledby="mcp-resources">
+        <h2 id="mcp-resources">Resources</h2>
+        <ul>{ELLA_MCP_RESOURCES.map((resource) => <li key={resource.uri}><code>{resource.uri}</code> — {resource.description}</li>)}</ul>
+        <p>Example: read <code>ella://entity-graph</code> for the consolidated JSON-LD graph or <code>ella://frameworks/four-forces-of-ai-power</code> for the Four Forces framework.</p>
       </section>
     </main>
   )
diff --git a/docs/mcp-deployment.md b/docs/mcp-deployment.md
new file mode 100644
index 0000000..cd727d6
--- /dev/null
+++ b/docs/mcp-deployment.md
@@ -0,0 +1,9 @@
+# EllaEntity MCP deployment checklist
+
+- Set `MCP_ALLOWED_ORIGINS` to the comma-separated browser origins permitted to call `/mcp`.
+- Keep `/mcp` public, read-only, unauthenticated, and separate from `/api/process`.
+- Configure durable platform rate limiting at Vercel/edge level. Recommended baseline rule: match path `/mcp`, limit POST requests per source IP to a conservative burst (for example 60 requests/minute) with a higher trusted-client allowance if needed.
+- Do not rely on process-local counters for serverless rate limiting; they reset across cold starts and instances.
+- Verify `GET /mcp` returns 405, `POST /mcp` handles Streamable HTTP JSON-RPC, and `/system/mcp` remains the human-readable documentation page.
+
+- The canonical public MCP endpoint URL is `https://mcp.ellaentity.ai`; the Next.js route remains `/mcp` internally for host-based routing.
diff --git a/lib/ella-mcp-schemas.ts b/lib/ella-mcp-schemas.ts
new file mode 100644
index 0000000..8303b9c
--- /dev/null
+++ b/lib/ella-mcp-schemas.ts
@@ -0,0 +1,102 @@
+import { z } from 'zod'
+import {
+  ELLA_CANONICAL_ENTITY_ID,
+  ELLA_DOMAIN_SLUGS,
+  ELLA_FRAMEWORK_SLUGS,
+  ELLA_REGISTRY_LAST_MODIFIED,
+  ELLA_REGISTRY_SCHEMA_VERSION,
+  ELLA_REGISTRY_SOURCE,
+} from './ella-registry'
+
+const provenanceSchema = z.object({
+  canonicalEntityId: z.literal(ELLA_CANONICAL_ENTITY_ID),
+  source: z.literal(ELLA_REGISTRY_SOURCE),
+  schemaVersion: z.literal(ELLA_REGISTRY_SCHEMA_VERSION),
+  dataVersion: z.string().min(1),
+  lastModified: z.literal(ELLA_REGISTRY_LAST_MODIFIED),
+})
+
+const jsonRecord = z.record(z.string(), z.unknown())
+const namedDescription = z.object({
+  name: z.string(),
+  description: z.string(),
+})
+
+const identityDataSchema = z.object({
+  name: z.string(),
+  canonicalId: z.literal(ELLA_CANONICAL_ENTITY_ID),
+  description: z.string(),
+  disambiguatingDescription: z.string(),
+  creator: z.unknown(),
+  sameAs: z.array(z.string().url()),
+  affiliations: z.array(jsonRecord),
+})
+
+const domainDataSchema = z.object({
+  id: z.string().url(),
+  name: z.string(),
+  description: z.string(),
+})
+
+const domainsDataSchema = z.object(
+  Object.fromEntries(ELLA_DOMAIN_SLUGS.map((slug) => [slug, domainDataSchema])) as Record<
+    (typeof ELLA_DOMAIN_SLUGS)[number],
+    typeof domainDataSchema
+  >,
+)
+
+const frameworkDataSchema = z.object({
+  slug: z.enum(ELLA_FRAMEWORK_SLUGS),
+  name: z.string(),
+  alternateName: z.string(),
+  url: z.string().url(),
+  description: z.string(),
+  domain: z.enum(ELLA_DOMAIN_SLUGS),
+  forces: z.array(namedDescription),
+})
+
+const workDataSchema = z.object({
+  name: z.string(),
+  url: z.string().url(),
+  type: z.enum(['PodcastSeries', 'SoftwareSourceCode', 'CreativeWork', 'CreativeWorkSeries']),
+  publisherId: z.string().url(),
+  publisherName: z.string(),
+  description: z.string(),
+})
+
+const collaborationDataSchema = z.object({
+  coCognition: z.object({
+    mikeYe: z.string(),
+    ella: z.string(),
+    aiTooling: z.string(),
+  }),
+  surfaces: z.array(
+    z.object({
+      href: z.string(),
+      path: z.string(),
+      label: z.string(),
+      description: z.string(),
+    }),
+  ),
+})
+
+function envelopeSchema<T extends z.ZodTypeAny>(data: T) {
+  return z.object({
+    data,
+    provenance: provenanceSchema,
+  })
+}
+
+export const ELLA_MCP_OUTPUT_SCHEMAS = {
+  identity: envelopeSchema(identityDataSchema),
+  domains: envelopeSchema(domainsDataSchema.or(domainDataSchema)),
+  frameworks: envelopeSchema(z.array(frameworkDataSchema).or(frameworkDataSchema)),
+  works: envelopeSchema(z.array(workDataSchema)),
+  collaboration: envelopeSchema(collaborationDataSchema),
+} as const
+
+export const ELLA_MCP_INPUT_SCHEMAS = {
+  empty: z.object({}).strict(),
+  domains: z.object({ domain: z.enum(ELLA_DOMAIN_SLUGS).optional() }).strict(),
+  frameworks: z.object({ framework: z.enum(ELLA_FRAMEWORK_SLUGS).optional() }).strict(),
+} as const
diff --git a/lib/ella-mcp-server.ts b/lib/ella-mcp-server.ts
new file mode 100644
index 0000000..386a951
--- /dev/null
+++ b/lib/ella-mcp-server.ts
@@ -0,0 +1,287 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import type { CallToolResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { ELLA_MCP_INPUT_SCHEMAS, ELLA_MCP_OUTPUT_SCHEMAS } from './ella-mcp-schemas'
+import {
+  ELLA_DOMAIN_SLUGS,
+  ELLA_FRAMEWORK_SLUGS,
+  ELLA_MCP_RESOURCES,
+  ELLA_MCP_SERVER_INFO,
+  ELLA_MCP_TOOL_NAMES,
+  ELLA_REGISTRY,
+  ellaEnvelope,
+  readEllaResource,
+} from './ella-registry'
+
+type ResourceRecord = (typeof ELLA_MCP_RESOURCES)[number]
+
+type NodeResponseCapture = ServerResponse & {
+  statusCode: number
+  headersSent: boolean
+  setHeader(name: string, value: number | string | readonly string[]): void
+  getHeader(name: string): number | string | string[] | undefined
+  writeHead(statusCode: number, headers?: Record<string, number | string | readonly string[]>): NodeResponseCapture
+  end(chunk?: unknown): NodeResponseCapture
+  toResponse(extraHeaders?: HeadersInit): Response
+}
+
+const TOOL_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const
+
+function textAndStructured(data: unknown): CallToolResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+    structuredContent: ellaEnvelope(data),
+    isError: false,
+  }
+}
+
+function resourceContents(resource: ResourceRecord, data: unknown): ReadResourceResult {
+  return {
+    contents: [
+      {
+        uri: resource.uri,
+        mimeType: resource.mimeType,
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+  }
+}
+
+export function createEllaMcpServer() {
+  const server = new McpServer(ELLA_MCP_SERVER_INFO, {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  })
+
+  server.registerTool(
+    'ella.identity.get',
+    {
+      title: 'Get Ella identity',
+      description:
+        'Canonical identity record for Ella: entity ID, description, disambiguation, creator, affiliations, sameAs anchors.',
+      inputSchema: ELLA_MCP_INPUT_SCHEMAS.empty,
+      outputSchema: ELLA_MCP_OUTPUT_SCHEMAS.identity,
+      annotations: TOOL_ANNOTATIONS,
+    },
+    async () => textAndStructured(ELLA_REGISTRY.identity),
+  )
+
+  server.registerTool(
+    'ella.domains.get',
+    {
+      title: 'Get Ella domains',
+      description:
+        "Ella's declared domain authority. Optional 'domain' argument: longevity | environment | sleep | ai-frameworks. Omit for all four.",
+      inputSchema: ELLA_MCP_INPUT_SCHEMAS.domains,
+      outputSchema: ELLA_MCP_OUTPUT_SCHEMAS.domains,
+      annotations: TOOL_ANNOTATIONS,
+    },
+    async ({ domain }: { domain?: (typeof ELLA_DOMAIN_SLUGS)[number] }) => {
+      if (domain) {
+        return textAndStructured(ELLA_REGISTRY.domains[domain])
+      }
+
+      return textAndStructured(ELLA_REGISTRY.domains)
+    },
+  )
+
+  server.registerTool(
+    'ella.frameworks.get',
+    {
+      title: 'Get Ella frameworks',
+      description:
+        "Ella and Mike Ye's declared frameworks. Currently returns The Four Forces of AI Power: Compute, Interface, Alignment, and Energy.",
+      inputSchema: ELLA_MCP_INPUT_SCHEMAS.frameworks,
+      outputSchema: ELLA_MCP_OUTPUT_SCHEMAS.frameworks,
+      annotations: TOOL_ANNOTATIONS,
+    },
+    async ({ framework }: { framework?: (typeof ELLA_FRAMEWORK_SLUGS)[number] }) => {
+      if (framework) {
+        return textAndStructured(ELLA_REGISTRY.frameworks.find((item) => item.slug === framework))
+      }
+
+      return textAndStructured(ELLA_REGISTRY.frameworks)
+    },
+  )
+
+  server.registerTool(
+    'ella.works.get',
+    {
+      title: 'Get Ella works',
+      description: 'Co-authored works attributed to Ella with schema types and URLs.',
+      inputSchema: ELLA_MCP_INPUT_SCHEMAS.empty,
+      outputSchema: ELLA_MCP_OUTPUT_SCHEMAS.works,
+      annotations: TOOL_ANNOTATIONS,
+    },
+    async () => textAndStructured(ELLA_REGISTRY.works),
+  )
+
+  server.registerTool(
+    'ella.collaboration.get',
+    {
+      title: 'Get Ella collaboration model',
+      description: 'The co-cognition model: division of labor between Mike Ye, Ella, and AI tooling.',
+      inputSchema: ELLA_MCP_INPUT_SCHEMAS.empty,
+      outputSchema: ELLA_MCP_OUTPUT_SCHEMAS.collaboration,
+      annotations: TOOL_ANNOTATIONS,
+    },
+    async () => textAndStructured(ELLA_REGISTRY.collaboration),
+  )
+
+  for (const resource of ELLA_MCP_RESOURCES) {
+    server.registerResource(
+      resource.name,
+      resource.uri,
+      {
+        title: resource.name,
+        description: resource.description,
+        mimeType: resource.mimeType,
+      },
+      async () => {
+        const data = readEllaResource(resource.uri)
+
+        if (data === null) {
+          throw new Error(`Resource ${resource.uri} not found`)
+        }
+
+        return resourceContents(resource, data)
+      },
+    )
+  }
+
+  return server
+}
+
+function createNodeResponseCapture(): NodeResponseCapture {
+  const headers = new Headers()
+  let body = ''
+  let statusCode = 200
+  let headersSent = false
+
+  const response = {
+    get statusCode() {
+      return statusCode
+    },
+    set statusCode(value: number) {
+      statusCode = value
+    },
+    get headersSent() {
+      return headersSent
+    },
+    setHeader(name: string, value: number | string | readonly string[]) {
+      if (Array.isArray(value)) {
+        headers.set(name, value.join(', '))
+        return
+      }
+
+      headers.set(name, String(value))
+    },
+    getHeader(name: string) {
+      return headers.get(name) ?? undefined
+    },
+    writeHead(code: number, nextHeaders?: Record<string, number | string | readonly string[]>) {
+      statusCode = code
+      headersSent = true
+
+      if (nextHeaders) {
+        for (const [name, value] of Object.entries(nextHeaders)) {
+          response.setHeader(name, value)
+        }
+      }
+
+      return response
+    },
+    write(chunk?: unknown) {
+      if (chunk !== undefined) {
+        body += String(chunk)
+      }
+
+      return true
+    },
+    end(chunk?: unknown) {
+      if (chunk !== undefined) {
+        body += String(chunk)
+      }
+
+      headersSent = true
+      return response
+    },
+    on() {
+      return response
+    },
+    once() {
+      return response
+    },
+    emit() {
+      return false
+    },
+    toResponse(extraHeaders?: HeadersInit) {
+      const mergedHeaders = new Headers(headers)
+
+      if (extraHeaders) {
+        new Headers(extraHeaders).forEach((value, name) => mergedHeaders.set(name, value))
+      }
+
+      return new Response(body || null, {
+        status: statusCode,
+        headers: mergedHeaders,
+      })
+    },
+  } as NodeResponseCapture
+
+  return response
+}
+
+function createNodeRequest(request: Request): IncomingMessage {
+  const headers: Record<string, string> = {}
+
+  request.headers.forEach((value, name) => {
+    headers[name.toLowerCase()] = value
+  })
+
+  return {
+    method: request.method,
+    url: new URL(request.url).pathname,
+    headers,
+    on() {
+      return this
+    },
+    once() {
+      return this
+    },
+  } as unknown as IncomingMessage
+}
+
+export async function handleEllaMcpPost(request: Request, extraHeaders?: HeadersInit) {
+  const body = await request.json()
+  const server = createEllaMcpServer()
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  })
+  const nodeRequest = createNodeRequest(request)
+  const nodeResponse = createNodeResponseCapture()
+
+  try {
+    await server.connect(transport)
+    await transport.handleRequest(nodeRequest, nodeResponse, body)
+    return nodeResponse.toResponse(extraHeaders)
+  } finally {
+    await transport.close()
+    await server.close()
+  }
+}
+
+export { ELLA_DOMAIN_SLUGS, ELLA_FRAMEWORK_SLUGS, ELLA_MCP_TOOL_NAMES }
diff --git a/lib/ella-registry.ts b/lib/ella-registry.ts
new file mode 100644
index 0000000..6042eba
--- /dev/null
+++ b/lib/ella-registry.ts
@@ -0,0 +1,102 @@
+import { ELLA_GLOBAL_SCHEMA, ELLA_MCP_SCHEMA, ELLA_ORG_SCHEMA, ELLA_SYSTEM_SCHEMA } from '../app/schema/ella'
+import {
+  ELLA_COCOGNITION,
+  ELLA_DOMAINS,
+  ELLA_FRAMEWORKS,
+  ELLA_IDENTITY,
+  ELLA_SURFACES,
+  ELLA_WORKS,
+} from './entity-data'
+
+export const ELLA_CANONICAL_ENTITY_ID = 'https://ellaentity.ai/#ella' as const
+export const ELLA_MCP_SERVER_INFO = { name: 'ellaentity-mcp', version: '1.1.1' } as const
+export const ELLA_MCP_PROTOCOL_VERSIONS = ['2025-06-18'] as const
+export const ELLA_MCP_DEFAULT_PROTOCOL_VERSION = ELLA_MCP_PROTOCOL_VERSIONS[0]
+export const ELLA_REGISTRY_DATA_VERSION = '2026-07-13.mcp-v1-1' as const
+export const ELLA_REGISTRY_LAST_MODIFIED = '2026-07-13' as const
+export const ELLA_REGISTRY_SCHEMA_VERSION = '1.1' as const
+export const ELLA_REGISTRY_SOURCE = 'https://ellaentity.ai/entity.json' as const
+
+export const ELLA_DOMAIN_SLUGS = ['longevity', 'environment', 'sleep', 'ai-frameworks'] as const
+export const ELLA_FRAMEWORK_SLUGS = ['four-forces-of-ai-power'] as const
+export const ELLA_MCP_TOOL_NAMES = [
+  'ella.identity.get',
+  'ella.domains.get',
+  'ella.frameworks.get',
+  'ella.works.get',
+  'ella.collaboration.get',
+] as const
+
+export type EllaMcpToolName = (typeof ELLA_MCP_TOOL_NAMES)[number]
+export type EllaDomainSlug = (typeof ELLA_DOMAIN_SLUGS)[number]
+export type EllaFrameworkSlug = (typeof ELLA_FRAMEWORK_SLUGS)[number]
+
+export function ellaProvenance() {
+  return {
+    canonicalEntityId: ELLA_CANONICAL_ENTITY_ID,
+    source: ELLA_REGISTRY_SOURCE,
+    schemaVersion: ELLA_REGISTRY_SCHEMA_VERSION,
+    dataVersion: ELLA_REGISTRY_DATA_VERSION,
+    lastModified: ELLA_REGISTRY_LAST_MODIFIED,
+  }
+}
+
+export function ellaEnvelope<T>(data: T) {
+  return { data, provenance: ellaProvenance() }
+}
+
+export function ellaEntityGraph() {
+  return {
+    '@context': 'https://schema.org/',
+    '@graph': [ELLA_GLOBAL_SCHEMA, ELLA_ORG_SCHEMA, ELLA_SYSTEM_SCHEMA, ELLA_MCP_SCHEMA].flatMap((schema) => {
+      if (Array.isArray(schema)) {
+        return schema.flatMap((entry) => {
+          if (entry && typeof entry === 'object' && '@graph' in entry) {
+            return (entry as { '@graph': unknown[] })['@graph']
+          }
+          return [entry]
+        })
+      }
+
+      if (schema && typeof schema === 'object' && '@graph' in schema) {
+        return (schema as { '@graph': unknown[] })['@graph']
+      }
+
+      return [schema]
+    }),
+  }
+}
+
+export const ELLA_REGISTRY = {
+  identity: ELLA_IDENTITY,
+  domains: ELLA_DOMAINS,
+  frameworks: ELLA_FRAMEWORKS,
+  works: ELLA_WORKS,
+  collaboration: { coCognition: ELLA_COCOGNITION, surfaces: ELLA_SURFACES },
+} as const
+
+export const ELLA_MCP_RESOURCES = [
+  { uri: 'ella://identity', name: 'Ella identity', mimeType: 'application/json', description: 'Canonical public Ella identity record.' },
+  { uri: 'ella://domains', name: 'Ella domains', mimeType: 'application/json', description: 'All public Ella authority domains.' },
+  ...ELLA_DOMAIN_SLUGS.map((slug) => ({ uri: `ella://domains/${slug}`, name: `Ella domain: ${slug}`, mimeType: 'application/json', description: `Public Ella domain record for ${slug}.` })),
+  { uri: 'ella://frameworks', name: 'Ella frameworks', mimeType: 'application/json', description: 'All public Ella and Mike Ye frameworks exposed by this server.' },
+  { uri: 'ella://frameworks/four-forces-of-ai-power', name: 'The Four Forces of AI Power', mimeType: 'application/json', description: 'The Four Forces framework record.' },
+  { uri: 'ella://works', name: 'Ella works', mimeType: 'application/json', description: 'Co-authored works attributed to Ella.' },
+  { uri: 'ella://collaboration', name: 'Ella collaboration model', mimeType: 'application/json', description: 'Public co-cognition model and surfaces.' },
+  { uri: 'ella://entity-graph', name: 'Ella entity graph', mimeType: 'application/ld+json', description: 'Canonical consolidated Ella JSON-LD graph.' },
+] as const
+
+export function readEllaResource(uri: string): unknown | null {
+  if (uri === 'ella://identity') return ELLA_REGISTRY.identity
+  if (uri === 'ella://domains') return ELLA_REGISTRY.domains
+  if (uri.startsWith('ella://domains/')) {
+    const slug = uri.replace('ella://domains/', '') as EllaDomainSlug
+    return ELLA_DOMAIN_SLUGS.includes(slug) ? ELLA_REGISTRY.domains[slug] : null
+  }
+  if (uri === 'ella://frameworks') return ELLA_REGISTRY.frameworks
+  if (uri === 'ella://frameworks/four-forces-of-ai-power') return ELLA_REGISTRY.frameworks.find((item) => item.slug === 'four-forces-of-ai-power') ?? null
+  if (uri === 'ella://works') return ELLA_REGISTRY.works
+  if (uri === 'ella://collaboration') return ELLA_REGISTRY.collaboration
+  if (uri === 'ella://entity-graph') return ellaEntityGraph()
+  return null
+}
diff --git a/package.json b/package.json
index fc1e3bc..7a3b17c 100644
--- a/package.json
+++ b/package.json
@@ -7,16 +7,18 @@
     "build": "next build",
     "start": "next start",
     "lint": "eslint",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts"
   },
   "dependencies": {
     "next": "16.1.6",
     "react": "19.2.3",
     "react-dom": "19.2.3",
-    "zod": "^3.24.0",
+    "zod": "^3.25.76",
     "@anthropic-ai/sdk": "^0.39.0",
     "uuid": "^11.1.0",
-    "openai": "^4.98.0"
+    "openai": "^4.98.0",
+    "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
@@ -27,6 +29,8 @@
     "eslint-config-next": "16.1.6",
     "tailwindcss": "^4",
     "typescript": "^5",
-    "@types/uuid": "^10.0.0"
+    "@types/uuid": "^10.0.0",
+    "ajv": "^8.17.1",
+    "tsx": "^4.20.6"
   }
 }
diff --git a/tests/mcp.test.ts b/tests/mcp.test.ts
new file mode 100644
index 0000000..4cfdad7
--- /dev/null
+++ b/tests/mcp.test.ts
@@ -0,0 +1,176 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import Ajv from 'ajv'
+import { GET, OPTIONS, POST } from '../app/mcp/route'
+import { ELLA_MCP_RESOURCES, ELLA_MCP_TOOL_NAMES } from '../lib/ella-registry'
+
+const endpoint = 'https://ellaentity.ai/mcp'
+const accept = 'application/json, text/event-stream'
+const contentType = 'application/json'
+const protocolVersion = '2025-06-18'
+
+function request(method: string, body?: unknown, headers: HeadersInit = {}) {
+  return new Request(endpoint, {
+    method,
+    headers: {
+      accept,
+      'content-type': contentType,
+      'mcp-protocol-version': protocolVersion,
+      ...headers,
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  })
+}
+
+async function rpc(method: string, params: unknown = {}, id: string | number = 1, headers: HeadersInit = {}) {
+  const response = await POST(
+    request(
+      'POST',
+      {
+        jsonrpc: '2.0',
+        id,
+        method,
+        params,
+      },
+      headers,
+    ),
+  )
+  const text = await response.text()
+  return {
+    response,
+    body: text ? JSON.parse(text) : null,
+  }
+}
+
+test('GET and OPTIONS implement method and CORS behavior', async () => {
+  const get = await GET(new Request(endpoint, { method: 'GET', headers: { origin: 'https://ellaentity.ai' } }))
+  assert.equal(get.status, 405)
+  assert.equal(await get.text(), '')
+  assert.equal(get.headers.get('allow'), 'POST, OPTIONS')
+  assert.equal(get.headers.get('access-control-allow-origin'), 'https://ellaentity.ai')
+  assert.notEqual(get.headers.get('access-control-allow-origin'), '*')
+
+  const options = await OPTIONS(new Request(endpoint, { method: 'OPTIONS', headers: { origin: 'https://ellaentity.ai' } }))
+  assert.equal(options.status, 204)
+  assert.equal(await options.text(), '')
+  assert.equal(options.headers.get('access-control-allow-origin'), 'https://ellaentity.ai')
+
+  const blocked = await OPTIONS(new Request(endpoint, { method: 'OPTIONS', headers: { origin: 'https://evil.example' } }))
+  assert.equal(blocked.status, 403)
+})
+
+test('POST validates content negotiation and origins', async () => {
+  const body = { jsonrpc: '2.0', id: 1, method: 'ping', params: {} }
+
+  assert.equal((await POST(request('POST', body, { accept: '' }))).status, 406)
+  assert.equal((await POST(request('POST', body, { accept: 'application/json' }))).status, 406)
+  assert.equal((await POST(request('POST', body, { accept: 'text/event-stream' }))).status, 406)
+  assert.equal((await POST(request('POST', body, { accept: 'text/plain' }))).status, 406)
+  assert.equal((await POST(request('POST', body, { 'content-type': 'text/plain' }))).status, 415)
+  assert.equal((await POST(request('POST', body, { origin: 'https://evil.example' }))).status, 403)
+})
+
+test('initialize validates official params and reports server capabilities', async () => {
+  const valid = await rpc('initialize', {
+    protocolVersion,
+    capabilities: {},
+    clientInfo: { name: 'behavior-test-client', version: '1.0.0' },
+  })
+
+  assert.equal(valid.response.status, 200)
+  assert.equal(valid.body.result.serverInfo.name, 'ellaentity-mcp')
+  assert.equal(valid.body.result.protocolVersion, protocolVersion)
+  assert.ok(valid.body.result.capabilities.tools)
+  assert.ok(valid.body.result.capabilities.resources)
+
+  const missingProtocol = await rpc('initialize', {
+    capabilities: {},
+    clientInfo: { name: 'behavior-test-client', version: '1.0.0' },
+  })
+  assert.ok(missingProtocol.body.error || missingProtocol.body.result.protocolVersion === protocolVersion)
+
+  const invalidId = await POST(request('POST', { jsonrpc: '2.0', id: null, method: 'ping', params: {} }))
+  assert.notEqual(invalidId.status, 200)
+})
+
+test('notifications return no JSON-RPC body', async () => {
+  const response = await POST(
+    request('POST', {
+      jsonrpc: '2.0',
+      method: 'notifications/initialized',
+      params: {},
+    }),
+  )
+
+  assert.equal(response.status, 202)
+  assert.equal(await response.text(), '')
+})
+
+test('tools list and calls are behavioral and schema-valid', async () => {
+  const list = await rpc('tools/list')
+  const tools = list.body.result.tools
+
+  assert.deepEqual(tools.map((tool: { name: string }) => tool.name), ELLA_MCP_TOOL_NAMES)
+
+  const ajv = new Ajv()
+
+  for (const tool of tools) {
+    assert.ok(tool.title)
+    assert.ok(tool.description)
+    assert.ok(tool.inputSchema)
+    assert.ok(tool.outputSchema)
+    assert.deepEqual(tool.annotations, {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    })
+
+    const call = await rpc('tools/call', { name: tool.name, arguments: {} })
+    assert.equal(call.response.status, 200)
+    assert.equal(call.body.result.isError, false)
+    assert.ok(call.body.result.content[0].text)
+    assert.ok(call.body.result.structuredContent.provenance.canonicalEntityId === 'https://ellaentity.ai/#ella')
+    assert.equal(ajv.validate(tool.outputSchema, call.body.result.structuredContent), true, ajv.errorsText())
+  }
+
+  const domain = await rpc('tools/call', { name: 'ella.domains.get', arguments: { domain: 'sleep' } })
+  assert.equal(domain.body.result.structuredContent.data.name.length > 0, true)
+
+  const badDomain = await rpc('tools/call', { name: 'ella.domains.get', arguments: { domain: 'bad' } })
+  assert.equal(badDomain.body.result.isError, true)
+
+  const unknown = await rpc('tools/call', { name: 'unknown.tool', arguments: {} })
+  assert.equal(unknown.body.result.isError, true)
+})
+
+test('resources list and reads expose only canonical public resources', async () => {
+  const list = await rpc('resources/list')
+  const uris = list.body.result.resources.map((resource: { uri: string }) => resource.uri)
+
+  assert.deepEqual(uris, ELLA_MCP_RESOURCES.map((resource) => resource.uri))
+
+  for (const resource of ELLA_MCP_RESOURCES) {
+    const read = await rpc('resources/read', { uri: resource.uri })
+    assert.equal(read.response.status, 200)
+    assert.equal(read.body.result.contents[0].mimeType, resource.mimeType)
+    assert.doesNotMatch(read.body.result.contents[0].text, /api\/process|credential|private memory|internal prompt/i)
+  }
+
+  const graph = await rpc('resources/read', { uri: 'ella://entity-graph' })
+  assert.match(graph.body.result.contents[0].text, /https:\/\/ellaentity\.ai\/#ella/)
+
+  const unknown = await rpc('resources/read', { uri: 'ella://unknown' })
+  assert.ok(unknown.body.error || unknown.body.result.isError)
+})
+
+test('canonical MCP URL parity is preserved', async () => {
+  const docs = await import('../app/system/mcp/page')
+  const llms = await import('node:fs').then((fs) => fs.readFileSync('public/llms.txt', 'utf8'))
+  const schema = await import('../app/schema/ella')
+
+  assert.match(String(docs.default), /Page/)
+  assert.match(llms, /https:\/\/mcp\.ellaentity\.ai/)
+  assert.doesNotMatch(llms, /https:\/\/mcp\.ellaentity\.ai\/mcp/)
+  assert.match(JSON.stringify(schema.ELLA_MCP_SCHEMA), /https:\/\/mcp\.ellaentity\.ai/)
+})