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
| Pattern | Feature | What it reaches |
|---|---|---|
stream | core.execute | Start or continue an agent stream (SSE). |
conversations/* | core.execute | Conversation 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.execute | List, 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.execute | List, 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-config | core.execute | Context occupancy (behind a read policy); moving pre-conversation attachments into the conversation; the composer paste caps. |
environments/programs | core.execute | Which programs the container and your usable online devices have installed — from metadata only, never run. |
agents/*, agent-context | core.agents · core.observe | Agent 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.observe | Usage 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. |
logs | core.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.connectors | Read the project's connectors; every change needs core.connectors. See below. |
mcp-servers/*, mcp-oauth/*, mcp-apps/* | core.observe · mcp.connect · mcp.sidecar · mcp.apps | External MCP servers (below) and the MCP Apps render surface. |
prompt-polish | core.prompt-polish | One-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.self | Your own git remotes and your own credentials, always in your own user scope; values are never echoed. See credentials. |
terminal/sources/*, terminal/sessions/*, terminal/health | terminal.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
connectauthorize 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 throughmcp-oauth/*, andDELETE 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 importedmcp.jsonfollows 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/uvxkind — import as dormant: Neuralis never spawns a child process on the host. A holder ofmcp.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:
| Member | What it gives the caller |
|---|---|
agentStore / agentService | Read and manage agents. |
usageStore | Token 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.
Team
team[] — the Admin team member agent-core ships, and how a provisioned agent's living identity files evolve and reset under agent-management rights.
App surfaces
app.surfaces[] — the Chat, Calendar (workflow.read) and Terminal (terminal.local) widgets agent-core contributes, with MCP App cards and Tool Access.