MCP & Headless

NeuralScio includes a real non-UI launch path for automation and agent workflows. The desktop application can start in headless mode, expose MCP over stdio for local tooling, and expose MCP over the network stack for HTTP and SSE clients.

When To Use MCP & Headless

Use MCP and headless mode when you want to:

run the research workflow from a local agent or script
connect another process over stdio, HTTP, or SSE
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 models, when enabled after Public Alpha billing, use NeuralScio account credits
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 current public MCP surface is designed for tool execution and diagnostics. It does not yet 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-port 6177

Optional flags:

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

Supported Transports

NeuralScio's MCP server supports:

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 the network transport 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

can require an access token
can require TLS for remote exposure
supports CORS configuration for browser-based clients
defaults should be treated conservatively

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-port 6177. 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