Cortex MCP

Early-stage work in progress. Cortex has a functional core scaffold, but it is not production-ready. Provider coverage, durable background execution, security hardening, and end-to-end validation are still incomplete.

Cortex MCP explores a practical systems problem: how can an agent submit expensive or long-running AI work once, route it deliberately, inspect its progress, and retrieve evidence about what happened?

The project is a local-first job broker with MCP and HTTP interfaces. Its design focuses on reliable orchestration, observable state transitions, cost-aware routing, provider independence, and human control. Privacy-by-design is an important boundary throughout the system, but it complements rather than replaces the broader engineering work.

This public repository contains only source code, documentation, tests, and synthetic examples. It does not contain private prompts, credentials, household data, live review artifacts, or deployment configuration.

What exists today

The Cortex scaffold currently includes:

• job and attempt lifecycle models;
• a SQLite registry using write-ahead logging;
• configurable provider abstractions;
• synchronous fan-out and ordered fallback behavior;
• an Anthropic adapter with message and batch-oriented paths;
• an OpenAI-compatible synchronous adapter;
• conservative pre-submit cost ceilings with fail-closed pricing;
• MCP tools for submission, status, results, cancellation, and briefings;
• a loopback-oriented HTTP surface for submission, status, and briefings; and
• a scheduler entry point that can poll submitted work and dispatch queued jobs.

These components demonstrate the intended architecture. They have not yet been proven as a dependable unattended service.

What is not finished

• The native Gemini adapter is a stub.
• OpenAI Batch API support is not implemented.
• Webhook registration and delivery are not implemented.
• Pricing entries must be verified before relying on cost estimates.
• Validation has a bounded first pass; idempotency, crash recovery, richer cancellation, and provider provenance need further work.
• The HTTP surface lacks production authentication, authorization, TLS, rate limiting, and replay protection.
• No recurring service deployment is included or claimed.
• Cortex does not autonomously modify Home Assistant or any other external system.

See the roadmap for the staged plan and threat model for the current security boundaries.

Architecture at a glance

flowchart LR
    A["MCP or HTTP caller"] --> B["Cortex broker"]
    B --> C["Cost guard and routing"]
    C --> D["Provider adapter"]
    D --> E["Remote or local model"]
    B <--> F["SQLite job registry"]
    B --> G["JSONL result artifacts"]
    H["Scheduler entry point"] --> B

The registry is the system of record for job and attempt metadata. Larger model outputs are stored as local JSON Lines artifacts. Provider adapters translate a common job shape into provider-specific calls. MCP and HTTP are alternate interfaces over the same broker concepts.

The detailed design is documented in docs/architecture.md.

Smart Home Review application

applications/smart_home_review is a more developed experimental application in this repository. It turns a bounded, read-only subset of Home Assistant configuration, trace summaries, and state history into a versioned evidence package for later review.

Its public demonstration:

• uses synthetic devices and events;
• has 28 regression tests covering the offline pipeline and collector;
• validates evidence against versioned schemas;
• preserves model agreement and disagreement;
• generates an advisory synthetic report; and
• keeps model submission, scheduling, and autonomous changes disabled.

The live collector has been validated manually and privately, but no live household evidence belongs in this repository. The application remains experimental and read-only.

Local scaffold setup

Python 3.11 or newer is recommended.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp config.example.toml config.toml

Review every provider, model, endpoint, price, and data-directory setting in config.toml before running anything. Store API keys only in the environment variables named by that file. The example intentionally omits cloud prices; verify and add them before using a cloud target.

To start the MCP process:

python -m cortex.server

To start the optional HTTP scaffold:

python -m cortex.http_api

Keep the HTTP listener on a trusted loopback interface. The current shared-token requirement is not sufficient protection for an internet-facing service.

Run the synthetic application tests

cd applications/smart_home_review
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m unittest discover -s tests -v
python -m smart_home_review demo

The demo performs no model-provider or Home Assistant network requests.

Engineering principles

• Visible state: job and attempt transitions should be inspectable.
• Evidence over confidence: important conclusions should link back to structured inputs and explicit validation.
• Fail closed on cost and privacy: unknown pricing or unreviewed sensitive data should block submission.
• Provider independence: orchestration policy should not be tied to one model vendor.
• Human authority: generated recommendations remain advisory until a person reviews and approves them.
• Honest maturity: scaffolding, experiments, and production-ready systems are labeled differently.

Documentation

• Architecture
• Threat model
• Testing and validation
• Roadmap
• Security policy
• Contributing

License

Licensed under the MIT License.