Skip to content

MCP_INTEGRATIONS.md

Latest commit

 

History

History
194 lines (154 loc) · 10.2 KB

MCP_INTEGRATIONS.md

File metadata and controls

194 lines (154 loc) · 10.2 KB
Raw

Cortex AI Integrations

Local Transport

Cortex exposes two MCP-compatible paths:

  • HTTP JSON-RPC: POST http://127.0.0.1:8766/mcp
  • Stdio proxy: scripts/cortex_mcp_stdio.py

The macOS app starts the local backend automatically. Once Cortex is running, local tools can connect through the stdio proxy.

Authentication

The macOS app uses a local per-install admin token for Cortex REST API calls. Local AI-tool integrations should not use that admin token. New copied or installed MCP configs use a separate scoped cxm_ MCP token.

/mcp accepts:

  • the admin app token for backward compatibility with older local configs;
  • a stored scoped MCP token for current integrations.

Scoped MCP tokens are checked before Connections & Privacy controls. A tool call succeeds only when the token has the needed scope and the matching local privacy control is enabled. Newly generated local MCP tokens include read, write, export, and maintenance; they do not include destructive.

The core tool surface (what an agent sees)

Scoped tokens are advertised a curated CORE surface — one tool per job — instead of the full catalog, so agents pick the right tool on the first try:

  • get_context — the context assembly engine: a token-budgeted, cited pack of constraints, decisions, facts, entity context, procedures, identity, open loops, and recency, shaped by task intent (answer/act/draft/plan/recall). Call this first before doing work. Also available over REST as GET/POST /v1/context (read scope; the identity layer alone requires export scope and degrades to a visible omission record without it).
  • ask_memory — cite-or-abstain answer to a specific question (never an uncited guess).
  • search_memory — keyword/semantic search with retrieval diagnostics.
  • get_entity_context — everything known about one person/project/org/topic + its graph neighborhood.
  • get_person_map — the whole cited image of the person (export scope).
  • remember_this — save one learning (write scope).
  • list_capabilities — discovery: counts, your scopes, the full catalog with required scopes.

Tokens minted with maintenance or destructive scopes additionally see those tool groups. Hiding is never authorization: every legacy tool remains callable via tools/call when the token's scopes allow — the collapse changes only what tools/list advertises. To restore the full legacy list, mint the token with the advertise_full marker scope (advertisement-only, grants nothing) or set CORTEX_MCP_TOOL_SURFACE=full on the backend. The admin app token always sees the full catalog.

MCP source tools can register connected source accounts, sync cited source records, and run due sync for already connected sources:

  • list_source_connectors
  • connect_source_account
  • sync_source_records
  • sync_connected_sources is maintenance-scoped and runs due sync for already connected sources using the locally stored source configuration.

This is the preferred beta path for connected tools and local connector processes. Direct connector tools such as sync_slack, sync_readwise, sync_raindrop, sync_zotero, sync_calendar, sync_linear, sync_jira, and sync_notion feed this same account, cursor, citation, and review contract. When sync_source_records includes a stable external_id, Cortex treats the record as the same source item on future syncs: unchanged content is skipped, changed content replaces the existing record's derived memory, and citations stay attached to the source account.

One-Click Integrations

The macOS app exposes integrations from Connections & Privacy > AI tools. It supports two integration modes:

  • One-click MCP install for clients with stable local JSON config files.
  • Advanced/fallback context-copy handoff for tools that cannot connect through MCP yet.

For direct installs, Cortex creates the parent config directory if needed, backs up an existing config next to the original file, then merges a single mcpServers.cortex entry without removing other servers.

Primary local install targets:

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Cursor: ~/.cursor/mcp.json
  • Windsurf: ~/.codeium/windsurf/mcp_config.json
  • Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Roo Code: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

Fallback targets that still need direct MCP or account sync before they should be treated as primary:

  • VS Code Copilot
  • Claude Code
  • ChatGPT
  • Claude web
  • Gemini
  • Perplexity
  • Microsoft Copilot
  • Grok
  • Poe
  • NotebookLM
  • LM Studio
  • Open WebUI
  • LibreChat
  • AnythingLLM

MCP Config Shape

The app-generated config should be preferred because it points at the bundled stdio proxy inside the installed app.

Packaged app shape:

{
  "mcpServers": {
    "cortex": {
      "command": "python3",
      "args": [
        "/Applications/Cortex.app/Contents/Resources/scripts/cortex_mcp_stdio.py"
      ],
      "env": {
        "CORTEX_BASE_URL": "http://127.0.0.1:8766",
        "CORTEX_API_KEY": "<scoped cxm_ MCP token generated by Cortex>"
      }
    }
  }
}

Development repo shape:

{
  "mcpServers": {
    "cortex": {
      "command": "python3",
      "args": [
        "/absolute/path/to/cortex-app/scripts/cortex_mcp_stdio.py"
      ],
      "env": {
        "CORTEX_BASE_URL": "http://127.0.0.1:8766",
        "CORTEX_API_KEY": "<scoped cxm_ MCP token generated by Cortex>"
      }
    }
  }
}

Advanced Context-Copy Fallback

Browser assistants do not all expose a stable local MCP config. For those, Cortex can copy scoped chat context as an advanced/fallback handoff with instructions:

  • search/use pasted Cortex memory before asking the user to repeat context
  • treat saved decisions and follow-ups as high-priority
  • ask focused follow-ups when context is missing or stale
  • preserve the user's local-first privacy constraints

Tool Surface

  • remember_this: save text into Cortex memory
  • search_memory: search active memories, optionally filtered by kind or memory layer (semantic, episodic, style, decision, preference, negative, procedural)
  • get_recent_context: retrieve recent active memories
  • get_memory_graph: retrieve the active graph
  • get_daily_review: retrieve today's pending memory candidates, follow-ups, decisions, topics, and recommended actions
  • build_context_pack: build an advanced/fallback context-copy payload for ChatGPT, Claude, Cursor, or another assistant when direct connection is not available
  • get_personal_profile: retrieve a cited profile grouped by memory layer, coverage, source health, follow-ups, and limitations
  • get_agent_adaptation: retrieve cited operating instructions that adapt an AI assistant to the user's preferences, style, decisions, limits, and current memory coverage
  • get_decisions: retrieve saved decisions
  • get_open_questions: retrieve open questions and tasks
  • list_memory_topics: list active topics
  • list_memory_entities: list active people, projects, organizations, and topics
  • get_about_person: retrieve memories involving a person
  • get_about_entity: retrieve memories involving any named entity
  • get_product_loop: retrieve the connect/sync, review, ask loop state
  • get_memory_stats: retrieve counts and top context
  • get_memory_inbox: retrieve pending memory candidates
  • approve_memory_capture: approve a pending memory candidate
  • archive_memory_capture: archive a memory candidate and remove it from active retrieval
  • delete_memory_capture: permanently delete a memory candidate and its derived memories/tasks from the current local memory folder and index
  • get_memory_diagnostics: inspect storage health
  • get_reliability_report: inspect health contract, storage checks, backup state, and recommended recovery actions
  • get_support_bundle: generate a sanitized operational support bundle without raw source text or memory content
  • create_memory_backup: create a full local memory folder backup
  • restore_latest_memory_backup: restore memory records from the latest local backup and rebuild the local search index
  • delete_memory_backups: delete local backup archives
  • delete_all_user_data: delete the current user's local memory folder/index data; includes backup archives by default
  • repair_memory_storage: create a backup, clean stale derived index rows, and rebuild search
  • rebuild_memory_search: rebuild full-text search
  • rebuild_index_from_vault: rebuild the SQLite search index from user-owned memory files
  • export_memory: export memory as Markdown or JSON

Diagnostics and reliability reports require the MCP token maintenance scope and the Connections & Privacy maintenance control, because they include local operational paths and repair context.

  • forget_memory: permanently delete one memory by ID from the current local memory folder and index

Product Rule

Connected AI tools should search before asking users to repeat context, cite source memory text when making claims, and use archive/delete/forget tools only when the user explicitly asks to remove memory.

Reliability Notes

  • Direct installers never delete an existing config file.
  • Existing JSON must parse as an object before Cortex writes to it.
  • Every changed config gets a timestamped .cortex-backup-* copy.
  • Users can rerun Install as Repair to refresh the Python path, local API URL, or token.
  • Browser integrations use context-copy fallback until the target service exposes a safe local config or remote OAuth/MCP flow.
  • MCP maintenance tools still respect Connections & Privacy controls.
  • The app and MCP clients can verify the backend through health_contract >= 3, the reliability-hardening feature flag, and the operational-readiness feature flag.
  • build_context_pack records use in the loop because fallback context-copy still means Cortex memory was used in an AI workflow.
  • get_agent_adaptation records use in the loop because agent instructions are a higher-privilege AI workflow and should be visible in review/audit surfaces.
  • get_support_bundle is intended for support triage; users should still review the JSON before sharing it.