REST API and MCP server

Cortex exposes two surfaces to its consumers. Both provide access to the same domain logic; they differ in protocol, authentication and intended audience.

---

REST API (port 9096)

The REST API is an HTTP/JSON interface for programmatic access: scripts, CI pipelines, custom services, the web UI.

Authentication

Two authentication methods are supported, checked in order:

1. Bearer JWT (Supabase) — for human users logged in through the UI. The JWT carries the user’s email and role.
2. X-API-Key header — for scripts, services and automated access. The API key is set via the CORTEX_API_KEY environment variable.

If neither is provided, the request is rejected with 401.

Main route groups

Route group	Purpose	Min role
/api/atoms	Read atom catalogue	reader
/api/catalogue/blocs	Read bloc catalogue	reader
/api/profils	Read HYOS profiles	reader
/api/blocs	Write blocs (ingestion)	producteur
/api/profils/ingest	Write profiles (ingestion)	producteur
/api/governance/*	Governance rules and audit trail	reader (read) / admin (write)
/api/memory/*	Per-project memory (read/write)	contributor
/api/workspace/*	Project, mission, ODM, task lifecycle	contributor
/api/library/*	Document library	contributor
/api/search	Full-text + faceted search	reader
/api/account/*	User profile, provider credentials	JWT required
/health	Health check	none

Response format

All responses follow a consistent envelope:

{
  "ok": true,
  "data": { ... }
}

Or on error:

{
  "ok": false,
  "error": { "message": "...", "code": "SOME_CODE" }
}

---

MCP server (port 3001)

The Model Context Protocol server is designed for LLM clients: Claude.ai, ChatGPT Custom Connectors, Cursor, or any MCP-compatible tool.

Authentication

The MCP server supports two authentication methods:

1. OAuth 2.0 — for production LLM clients. The server implements the full OAuth authorization flow with a PostgreSQL-backed provider. Discovery is available at /.well-known/oauth-authorization-server.
2. X-API-Key header — for local development and testing.

Transport

The MCP server uses StreamableHTTP transport (HTTP-based, not SSE). This is the standard MCP transport for server deployments.

Tool naming

All MCP tools are prefixed with hcm_ (the internal engine name). Examples:

MCP tool	Purpose	Min role
hcm_status	Health check	reader
hcm_search_atoms	Search atoms by text	reader
hcm_get_atom	Get one atom by id	reader
hcm_get_node	Get one graph node	reader
hcm_get_edges	Get edges for a node	reader
hcm_context	Get project context	reader
hcm_faceted_search	Faceted catalogue search	reader
hcm_traverse	Traverse the graph	reader
hcm_subgraph	Extract a subgraph	reader
hcm_graph_query	Run a SELECT query	reader
hcm_impact	Impact analysis	reader
hcm_draft	Draft workspace artefact	contributor
hcm_deposit	Deposit memory entry	contributor
hcm_ingest_bloc	Ingest a bloc	producteur
hcm_ingest_profil	Ingest a profile	producteur
hcm_delete_document	Delete a document	contributor

RBAC enforcement

Every tool call is checked against a minimum role requirement (TOOL_MIN_ROLES) before the handler executes. If the session role is insufficient, the call is rejected. The role hierarchy is: reader < contributor < producteur < admin.

CORS

The MCP server’s CORS policy defaults to allowing https://claude.ai and https://chatgpt.com. Override via the MCP_CORS_ORIGINS environment variable (comma-separated list of allowed origins).

---

When to use which

Scenario	Use
LLM agent reading profiles at session start	MCP server
LLM agent depositing memory after a session	MCP server
CI pipeline ingesting blocs from a Git repo	REST API
Web UI browsing the catalogue	REST API
Custom service checking project drift	REST API
Claude.ai user exploring the catalogue via tool calls	MCP server
Batch script importing 100 profiles	REST API
Health monitoring	REST API (/health) or MCP server (/health)

Both surfaces are backed by the same domain services. There is no feature available on one surface that is architecturally impossible on the other — the difference is in protocol, authentication method and ergonomics for the consumer.

---

What next?

• Understand authentication in depth: 07-security-and-data
• Deploy Cortex: 08-deployment