@agent-core

Routes

routes/*.ts — agent-core's feature-gated HTTP routes by group, the conversation inbox and stop, and connecting external MCP servers (mcp.connect).

A client — the chat UI, a skill script, the neuralis CLI — reaches agent-core through routes under /api/packages/@neuralis/agent-core/<pattern>. The route dispatcher derives the user, project and optional agent from the verified session, never from client values, and enforces each route's declared feature before the handler runs: a caller without it gets 403, with no data and no existence oracle. Several routes check a stronger feature inside the handler for the operations that need it. A skill script authenticates with the per-stream session ticket and never sends identity in a header; external MCP clients use the MCP endpoint instead of these routes. A model calls the tools.

Route groups

PatternFeatureWhat it reaches
streamcore.executeStart or continue an agent stream (SSE).
conversations/*core.executeConversation CRUD and messages; edit, undo, rewind, retry; titles; the summarize family (POST …/summarize, …/summarize/cancel, …/summarize/status); history-mode and compact_history show-full toggles; a live guard-profile switch; POST …/stop; the evidence record (GET …/evidence); delegate-run transcripts and their stop / follow-up controls; the inbox; forks (POST …/fork also needs core.conversation.fork).
interactions/*core.executeList, answer, approve and deny pending questions and approvals. Approving an MCP-app call also re-checks the view lease, write access and mcp.apps.
shells/*core.executeList, read and kill your own background shells. Reading is per user across your agents; killing is per agent (403 shell_stop_forbidden from another agent's chat).
context-window, composer-adopt, composer-configcore.executeContext occupancy (behind a read policy); moving pre-conversation attachments into the conversation; the composer paste caps.
environments/programscore.executeWhich programs the container and your usable online devices have installed — from metadata only, never run.
agents/*, agent-contextcore.agents · core.observeAgent CRUD, team catalog, batch create, resync (agent-update rights; an identity reset needs full agent-management — see team), hosted MCP API keys, the agent picture; the read-only setup snapshot (unknown and unauthorized ids share one 404).
devices/*core.agents (+ device.own, platform.users in-handler)List devices (scope=mine, project, platform), a revoke's impact, rename, pair, revoke, and remove a revoked device (?purge=1). Pairing and revoking are a person's acts. See devices.
usage, codex-usage, models, files/*, tools/*, packages/*core.observeUsage events, the Codex subscription snapshot (one live refresh per open, never polled), the model list, resolved file contributions, the tool catalog, the package overview and loader diagnostics.
logscore.observe (+ core.logs / platform.audit)An agent's run log needs core.logs; the platform-global system and package logs need platform.audit.
cli/session, cli/launch-context, companion/origin, oauth/codex/*core.observe (+ write-tier checks in-handler)The CLI's session and launch context, and the Codex subscription sign-in (start, relay, import, status, disconnect) at the scope your rights allow.
connectors/*core.observe · core.connectorsRead the project's connectors; every change needs core.connectors. See below.
mcp-servers/*, mcp-oauth/*, mcp-apps/*core.observe · mcp.connect · mcp.sidecar · mcp.appsExternal MCP servers (below) and the MCP Apps render surface.
prompt-polishcore.prompt-polishOne-shot composer draft rewrite.
workflow/*workflow.read (+ workflow.write, workflow.dispatch)Workflow CRUD, dispatch, templates, the calendar range, runs and their event logs, per-trigger edits, and a live feed. A private or foreign entry answers 404. Webhook keys and signing secrets are issued to a person only. See workflows.
channels/*workflow.read (+ channels.connect, channels.manage, workflow.write)Channel connections, pairings, peer links and workflow bindings. Creating a connection answers a person only. See channels.
git-connect/*, self-credentials/*git.connect · credentials.selfYour own git remotes and your own credentials, always in your own user scope; values are never echoed. See credentials.
terminal/sources/*, terminal/sessions/*, terminal/healthterminal.local (+ terminal.unconfined, terminal.device, terminal.supervise, core.execute in-handler)The terminal: selectable tabs, the managed session lifecycle, health.

The features and their default grants are listed on the package overview.

Conversations

Messaging another agent's conversation. POST …/conversations/<id>/inbox?agentId=<target> with { "message": "…", "delivery": "settle" } answers 202 { "queued": true, "id": "msg_…" }. The message lands as a report card naming the sender — always the caller's own session — and the receiver continues as the sender, never as the conversation's owner. The caller needs write access to the conversation and read access to the agent. settle (the default) delivers at the start of the next turn; immediate asks a running turn to take it at its next step, and falls back to the end of the turn — never dropping it — when that turn belongs to someone else, its text can leave the platform through a channel, it runs under a weaker guard, it is on its wrap-up step, or it has taken its per-turn ceiling. The brakes answer 429 (inbox_hops_exceeded, inbox_full, inbox_rate_limited). GET …/inbox lists what is undelivered, and DELETE …/inbox/<msgId> lets the sender withdraw a message before delivery (409 while it is being delivered). A background subagent run has its own inbox at …/delegates/<runId>/inbox, settle-only.

Reading a transcript incrementally. GET …/conversations/<id>/messages?sinceSeq=42 returns the rows from 42 inclusive, because parallel tool results merge into an existing row that keeps its number. Anything but decimal digits answers 400 invalid_since_seq. The same parameter works on delegate transcripts.

Stopping the turn a conversation is running. POST …/conversations/<id>/stop reaches a turn nobody holds a browser connection for — a background report, an inbox message, a workflow run. The caller needs write access and either owns the turn or holds admin strength (403 stream_stop_forbidden otherwise); with nothing running it answers "stopped": false. The partial answer is persisted, and a workflow turn also closes its run. Work in flight stops with the turn: a container shell command, a subagent, and a command on a device too — the device is sent a cancel and ends the command's whole process tree, unless it runs a CLI too old to cancel, which the result says, and then the command finishes under its own timeout. An external MCP call is cancelled on the wire, and a tool that cannot be stopped finishes with its result dropped. A background shell and a background subagent are exempt by design; each has its own stop.

Summarizing. A manual summarize refused mid-stream answers 409 (stream_active / pending_interaction); an unusable pinned summary model 400 summary_model_unavailable; a run past its total deadline 504 summary_timeout; an answer the validator rejected twice 422 summary_invalid_output.

MCP servers

Agents connect out to external MCP servers over streamable HTTP (spec revision 2025-11-25: negotiated protocol version, optional session id, resumable notifications, request cancellation). Add a server in the chat config panel's Connected MCP section or the agent's MCP configuration, or let the agent do it with the connect tool or the mcp-servers skill; its tools join the agent's catalog. Connecting your own servers needs mcp.connect (managers and members by default).

  • OAuth. Protected servers use standard discovery and PKCE: Authorize (or the agent's connect authorize lane) produces a consent link a person opens. Tokens are stored in your own user scope and resolved scope-exactly, so one member never rides another's authorization. A server without dynamic registration takes a static client id/secret through mcp-oauth/*, and DELETE mcp-oauth/<server> revokes your own sign-in for that server.
  • Custom headers. Non-secret headers (x-api-version: 2026-01) live in the agent's configuration. A secret header is declared by name, which creates an empty slot; its value goes into a write-only field on the server row and is stored in your own scope, read only at connect time, never returned by a listing and never written to the audit trail (which records names only). A server with an unfilled slot is not connected at all and shows as unavailable. An imported mcp.json follows the same rule: header names become slots, values are never imported. The names the platform sets itself (authorization, content-type, accept, the MCP session and protocol-version headers, hop-by-hop names) are refused when you add them.
  • Command-based (stdio) servers — the npx/uvx kind — import as dormant: Neuralis never spawns a child process on the host. A holder of mcp.sidecar (no grant below the admin tier) can activate one in a managed sidecar container: hardened, resource-capped, no privileges, loopback-only, behind a token-guarded bridge, isolated per user or shared per project by the server's scope, and reaped when idle. Its secret environment values live in the credential store and are injected only at start.
  • Guarantees on every connection. Outbound URLs are SSRF-validated and DNS-pinned, OAuth discovery and token endpoints included; no Neuralis identity or internal metadata is ever sent to an external server; in-host stdio servers are refused; capabilities a server did not declare are never called.

mcp-servers/* lists servers (header slot names, never values; unavailable marked), adds and removes them, activates a sidecar, and sets or revokes your own header and sidecar-environment values — always in your own scope, with no scope parameter.

Connectors

A connector turns an external service into callable tools: an OpenAPI connector generates one tool per operation of an OpenAPI 3.x spec, and an MCP connector bridges a remote server over http or streamable-http. Every request — the spec fetch and each call — is SSRF-guarded and pinned to a validated public address; a local (stdio) server is never started inside the platform.

Connectors are project-scoped. A caller sees its own project's connectors plus the platform-wide ones a package declared, never another project's, on any surface; an id from another project answers the same 404 as an unknown one; and a project's own connector wins over a platform one of the same name. Reading (list, health, generated tools) is core.observe and returns display fields only. Every change — create, configure, connect, disconnect, enable, disable, delete — needs core.connectors, which has no grant below the admin tier, and a connector created there is always a remote endpoint. Filesystem sources are a different thing, owned by brain-core. How a connector gets its secrets is on credentials.

Package API

Another package calls agent-core in-process through its typed AgentCoreApi (how to obtain it: package-system routes). Among its members:

MemberWhat it gives the caller
agentStore / agentServiceRead and manage agents.
usageStoreToken and cost usage events and summaries.
verifyAgentAccess(userId, projectId, agentId)The ownership/access check for an agent.
getActiveStreams()A snapshot of the currently running streams.
listMcpServers(session) / listConnectorInstances()Dashboard-grade MCP and connector signal for the session.

Skill session tickets are verified by a separate session-ticket-verifier service, not through this API. Internal MCP calls between packages are forbidden — the tool surface is for models and external clients.

Tools over MCP

agent-core exposes four tools on the platform's MCP endpoint for external clients: web_search, web_fetch, connect, and the connector branch of execute. Local shell execution and skill activation still need a stream; every other agent-core tool is reached only inside one.

On this page