MCP & Headless

Review the experimental local MCP integration and its configuration boundaries.

Status: Experimental. Available tools and transports depend on the current desktop build and configuration. Local source support alone does not establish a hosted MCP service or public availability.

Builds that include and configure the experimental headless path can expose MCP over stdio for local tooling or use configured HTTP and SSE network transports. This documents desktop integration points, not a hosted service or a production availability guarantee.

When To Use MCP & Headless

Use MCP and headless mode when you want to:

  • run the research workflow from a local agent or script when MCP is enabled
  • connect another process over local stdio or configured HTTP/SSE transports
  • reuse the same search, library, and AI surfaces without opening the full desktop window
  • validate or automate workflows in repeatable local setups

What An External AI Can Do

An external MCP client can connect to NeuralScio and call the same tool-backed research surfaces that the desktop app exposes to its own assistant. The external AI does not need to scrape the UI.

Common tool families include:

| Tool family | Examples | | --- | --- | | Search and paper navigation | search_papers, select_article, open_article_by_id, get_current_article, get_article_content | | Local library and RAG | search_local_library, ask_document, rag_index_status, rag_index_document, rag_retrieve_elements | | Research workspace | get_research_workspace, set_research_focus, record_claim, record_evidence, record_claim_review, record_gap, record_next_step | | Agents and portfolio review | start_portfolio_review, start_epistemic_review, get_epistemic_review_status, stop_epistemic_review | | Research memory | get_local_research_memory_overview, list_promotion_drafts, propose_promotion, review_promotion_draft, list_curated_memory_entries, load_curated_memory_entry | | Paper-to-Code | inspect_paper_repository, generate_code_plan, compare_implementations, export_code_plan | | Diagnostics | get_research_gold_path_diagnostics, get_scientific_workflow_observability, get_recent_diagnostics, export_diagnostic_bundle |

The exact list comes from the MCP tools/list method at runtime.

AI Model Choice

MCP is the control channel. The AI model still comes from the NeuralScio AI settings.

Before an MCP-driven research run, choose the route in Settings -> AI:

  • managed cloud AI is not active during Public Alpha; future availability and timing are not published
  • your own provider API keys
  • local models through Ollama or the native GGUF / llama.cpp worker

After that, an MCP client can start workflows such as start_portfolio_review with branch_execution_mode=model_backed. The model-backed branch uses the currently selected backend.

The MCP surface is experimental and configuration-dependent. It does not expose a user-facing tool that switches the active AI provider or model during a live run.

Launch Commands

Headless launch path

The desktop app parses command-line flags and switches to HeadlessBootstrap when headless mode is requested.

Implemented entry points include:

  • --headless
  • --mcp-stdio
  • --mcp-enabled
  • --mcp-host <host>
  • --mcp-port <port>
  • --mcp-token <token>

Important behavior:

  • --mcp-stdio implicitly enables headless mode
  • --headless --mcp-stdio is also valid
  • headless mode starts HeadlessInstance, not the normal desktop window path

Local agent or CLI integration over stdio

NeuralScio --mcp-stdio

This is the cleanest local machine-to-machine path because it:

  • avoids opening the full GUI flow
  • starts the headless bootstrap path directly
  • exposes MCP over stdin/stdout

Headless network MCP

NeuralScio --headless --mcp-enabled --mcp-host 127.0.0.1 --mcp-port 6177 --mcp-token YOUR_TOKEN

The network server requires a token by default. Use a locally generated token and keep the listener on loopback unless you have explicitly reviewed the current remote-access and TLS settings.

Supported Transports

When included and enabled, the MCP server provides these configured transports:

  • stdio transport for local process-to-process integration
  • HTTP transport on the configured /mcp endpoint
  • SSE session support on /mcp/sse
  • health endpoint on /mcp/health

Config Prerequisites

Required config keys

The MCP server reads settings from the mcp/* namespace.

Important keys include:

  • mcp/enabled
  • mcp/stdio_enabled
  • mcp/host
  • mcp/port
  • mcp/require_token
  • mcp/tls_enabled
  • mcp/cors_enabled
  • mcp/activity_log_enabled

Important nuance: stdio still respects config

Headless startup writes mcp/enabled = true before trying to start MCP, but stdio mode still checks mcp/stdio_enabled.

That means this can still block stdio startup:

  • mcp/stdio_enabled = false

GUI settings and headless behavior

The desktop settings layer includes MCP controls. Those settings still matter when you later launch the app in headless mode, because the MCP server loads the same stored config.

Message Framing

The stdio path supports two input styles:

  • newline-delimited JSON messages
  • Content-Length framed messages in LSP-style format

Responses are written to standard output.

Common Automation Scenarios

Agent access to the research workflow

Use MCP when you want an AI agent or script to work with the same research surfaces instead of scraping a GUI manually.

Examples:

  • let an agent query the saved library
  • inspect current article text or metadata
  • call tool-backed AI workflows already exposed by the app
  • use the desktop stack inside repeatable local automation

Technical integrations

Use a configured network transport only when the current build and security settings permit it, for example when you need:

  • a local HTTP endpoint for another process
  • SSE responses for long-lived MCP sessions
  • token and TLS controls for stricter environments

Security Boundary

Stdio

  • best for same-machine tooling
  • no network exposure
  • avoids remote-access concerns entirely

Network MCP

  • requires a token by default
  • remote binding is disabled by default; non-loopback bindings require TLS
  • supports CORS configuration for browser-based clients
  • settings can be changed, so verify effective configuration before use

Quick Validation

Validate stdio startup

  1. Ensure mcp/stdio_enabled=true in your effective settings.
  2. Run NeuralScio --mcp-stdio.
  3. Confirm the process stays alive and responds on stdout.

Validate network startup

  1. Ensure MCP is enabled.
  2. Run NeuralScio --headless --mcp-enabled --mcp-host 127.0.0.1 --mcp-port 6177 --mcp-token YOUR_TOKEN with a locally generated token.
  3. Check the health endpoint:
curl http://127.0.0.1:6177/mcp/health

Troubleshooting

--mcp-stdio does nothing useful

Check these first:

  1. mcp/stdio_enabled may be disabled.
  2. The process may be launched from an environment that is not reading stdout correctly.
  3. The client may be sending a framing format the server does not accept.

Network MCP does not start

Check these first:

  1. mcp/enabled must be true.
  2. The port may already be in use.
  3. mcp/require_token=true without a configured token can block HTTP startup.
  4. TLS requirements can block remote startup when certificates are missing.

Old wording says stdio launches the GUI

That wording is obsolete.

Current behavior is:

  • --mcp-stdio sets headless = true
  • the app enters HeadlessBootstrap
  • HeadlessInstance starts the MCP stdio server path

Practical Positioning

NeuralScio is still a desktop research product first. Experimental MCP and headless mode can make parts of the workflow usable from scripts and local automation when the current build and configuration enable them.