Prelaunch preview. Explore AROS products and skills. Checkout is in sandbox; no real payment.
Developer Portal · Streamable HTTP MCP

The Laboratory Manual for AI Agents

Connect research agents to the curated public procedural bank of AROS Cloud Federation via the Model Context Protocol (MCP). This reference describes the supported protocol and configured gateway capabilities in source; confirm active tools and response metadata on the target deployment.

Pre-release service status · commercial checkout is not open

The platform operates in pre-release mode (pre_release_mode). Non-admin accounts register with 0 credits, checkout is not open, no standalone paid MCP add-on plan is offered, and service access does not establish a purchased subscription.

Standard Read Access

$0/mo (pre-release)
  • Read-only access to the 8 allowlisted public MCP tools (public_published catalog)
  • Requires an active Organization Bearer API key (ak_...) with the 'read' scope
  • Governed by configurable per-organization, per-principal, and global admission caps (HTTP 429 Retry-After client backoff)
Get API Key
Workflow Pilot · Prelaunch

Evaluated Team & Pro Track

Scoped via pilot proposal
  • Uses the same 8-tool public_published read allowlist with organization-scoped governance
  • Optional 'deep' retrieval escalation when CONTEXT_QUERY_ENABLED, operator policy, budget reservation, and approved region permit (degrades safely to 'fast')
  • Governed by gateway admission caps and HTTP 429 Retry-After client backoff rather than server-side request holding
Review Pilot & Pricing Scope

Enterprise & Dedicated Isolation

Custom
  • Scoped private workflow evaluation and institutional governance review
  • VPC peering and dedicated Cloud Run deployment architecture by written agreement
  • Explicit data residency and operator policy boundaries before any provider call
Contact Sales

What routes through this endpoint

Every figure below is a row count or a recorded event. Where we do not yet have a measurement, this says so rather than estimating one.

Reachable

Skill-hierarchy rows
2,197
Knowledge items
299
World facts
22,714

What an agent can mount through the gateway. Eight read-only tools are exposed; writes and executions are redacted from tools/list and refused on call.

Actually retrieved

282/ 2,197

Distinct skills pulled into a prompt across 618 recorded retrievals — 12.8% of the library. The other 87.2% has never been reached for. We publish the unflattering half because it is the argument for curation over accumulation.

Gateway

Reading…

Endpoint, Authentication & Protocol Contract

The human documentation page and the machine JSON-RPC transport live at distinct routes. Configure MCP clients to call POST https://nexitia.ai/api/mcp.

Human Documentation Page
GET https://nexitia.ai/mcp (/mcp)
MCP Streamable HTTP JSON-RPC 2.0 Endpoint
POST https://nexitia.ai/api/mcp (/api/mcp)
Public Measured Gateway Statistics
GET https://nexitia.ai/api/mcp/statistics (/api/mcp/statistics)

Authentication & Required API Key Scope ('read')

Every request to POST https://nexitia.ai/api/mcp requires Authorization: Bearer ak_... belonging to an active, non-deleted Organization with the 'read' scope enabled. Keys scoped only for 'llm_proxy' authorize the LLM proxy gateway and do not grant /api/mcp access.

Supported MCP Protocol Versions

Primary protocol version: 2025-11-25. Supported MCP-Protocol-Version header revisions: 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05. Unsupported revisions return HTTP 400 JSON-RPC error -32600.

Allowed JSON-RPC 2.0 Methods & Notifications

Request methods (require a string or integer id): initialize, ping, tools/list, and tools/call. Notification methods (must omit id and return HTTP 202 Accepted with an empty body): notifications/initialized and notifications/cancelled. During initialize, server capabilities are sanitized to tools.listChanged=false.

Public Read-Only Tool Allowlist (8 Tools)

The public MCP gateway enforces a strict 8-tool read-only allowlist (PUBLIC_ALLOWED_TOOLS) and strips tenant or local override arguments (session_id, workspace_id, workspace_path, db_path, brain_db_path, source_path, org_id, scope, plane, as_of_time, include_private).

Tool NameCategoryDepth PolicyAccepted Parameters & stable_id Contract
query_memorySearch / Discoveryfast / deep / auto
query, limit?, depth? ('fast' | 'deep' | 'auto')

Searches curated public world_facts only (memory_type='world_facts' and verbose=false enforced by the gateway; never queries private experiences, mental_models, or insights).

find_helpful_skillsSearch / Discoveryfast / deep / auto
task_description, limit?, depth? ('fast' | 'deep' | 'auto')

Finds human-approved biomedical and scientific skills in the public_published catalog matching a task description.

find_helpful_kiSearch / Discoveryfast / deep / auto
task_description, limit?, depth? ('fast' | 'deep' | 'auto')

Finds curated public Knowledge Items (KIs) relevant to a scientific or operational workflow.

find_helpful_workflowSearch / Discoveryfast / deep / auto
task_description, limit?, depth? ('fast' | 'deep' | 'auto')

Finds curated public multi-step workflow specifications matching a research objective.

list_skillsCatalog ListingNot applicable
(no parameters)

Lists the human-curated public skill catalog directory without retrieval depth parameters.

read_ki_documentDetail Read (stable_id)Not applicable
ki_name, document_path? ('OVERVIEW.md') | stable_id ('<namespace>:<item_type>:<id>')

Reads a curated public Knowledge Item document by name/path or canonical stable_id (e.g. public_published:ki:slug).

read_skill_documentDetail Read (stable_id)Not applicable
skill_name, document_path? ('SKILL.md'), include_base64? (false) | stable_id ('<namespace>:<item_type>:<id>')

Reads a curated public SKILL.md or supporting asset by skill_name/document_path or canonical stable_id (e.g. public_published:skill:slug).

read_workflowDetail Read (stable_id)Not applicable
workflow_name | stable_id ('<namespace>:<item_type>:<id>')

Reads a curated public workflow specification by workflow_name or canonical stable_id (e.g. public_published:workflow:slug).

Detail-read tools (read_ki_document, read_skill_document, read_workflow) accept canonical stable_id identifiers in '<namespace>:<item_type>:<id>' format (for example, public_published:skill:scrna-cell-type-annotator) alongside primary name and document_path parameters. Private or Commons stable_id namespaces (local_private, org_private, commons, local, org, private) are rejected on the public gateway.

Four-Plane Audience Boundary & Readiness Lifecycle

AROS Cloud Federation separates context into four strict planes. The public /api/mcp endpoint serves only the human-approved public procedural bank.

Public Approved Catalog (public_published) — Served on /api/mcp

Contains only human-curated procedural skills, Knowledge Items (KIs), workflows, and approved public world_facts. Marketplace and public catalog publication is human-only (AGENTS.md Rule 15).

Organization Private (org_private) & Local Private (local_private) — Never Exposed on /api/mcp

Tenant-isolated backups (org_private), machine-local brain state (local_private), and private episodic memory (experiences, mental_models, insights) are never readable through the public MCP endpoint.

Federation Commons (commons) — Opt-In Pool Distinct from Public Approval

Opting into Federation Commons contributes sanitized items to the shared Commons aggregation pool (aggregation_pending), but Commons opt-in never automatically publishes content to public_published without human curator review and approval.

Backup Acceptance (accepted) vs. Serving Readiness (searchable)

When an Organization uploads a private context bundle, an accepted receipt (state='accepted', processing_status='projection_pending') confirms durable storage validation only. The revision becomes searchable (searchable=true) only after asynchronous index projection completes and advances serving_revision_id.

Retrieval Depth (fast / deep / auto), Conditional Rollout & Freshness

Retrieval behavior depends on deployment flags, operator budget policy, and active corpus state, reported through explicit response metadata.

Conditional Rollout Flag (CONTEXT_QUERY_ENABLED defaults to false)

The v2 context-query service is gated by CONTEXT_QUERY_ENABLED (default false). While CONTEXT_QUERY_ENABLED is false, only the existing 8 allowlisted tools are exposed and depth-capable search tools force depth='fast'.

Depth Modes: fast Baseline, Opt-In Approved deep, and Uncalibrated auto

The depth parameter ('fast', 'deep', 'auto') applies only to search tools (query_memory, find_helpful_skills, find_helpful_ki, find_helpful_workflow). 'fast' is the deterministic lexical/vector baseline. When CONTEXT_QUERY_ENABLED is enabled, 'deep' escalation is optional and runs only when operator policy, budget reservation, and approved region allow — otherwise requests degrade safely to 'fast'. Uncalibrated 'auto' defaults to 'fast'.

Measured Response Metadata & Zero Local LLM Requirement

Latency and ranking depend on the active deployment and corpus. Responses report the actual executed depth, degraded / degradation_reason status, and corpus freshness metadata (accepted_revision_id and serving_revision_id). Callers do not need a local LLM or local GPU on their machine.

Admission Quotas, HTTP 429 Client Backoff & Credit vs. Infrastructure Caps

Distributed admission control protects gateway stability across all tenants. Rate and concurrency values below represent operator-configurable policy defaults in code, not fixed deployment guarantees.

Per-Organization Default Policy Cap
30 requests/min · max concurrency 4 (configurable via CONTEXT_ADMISSION_ORG_*)
Per-Principal (API Key / User) Default Policy Cap
15 requests/min · max concurrency 2 (configurable via CONTEXT_ADMISSION_PRINCIPAL_*)
Global Public MCP Gateway Default Policy Cap
120 requests/min · max concurrency 16 (configurable via CONTEXT_ADMISSION_GLOBAL_*)

HTTP 429 Too Many Requests with Retry-After Requires Client Backoff

When an organization, principal, or global cap is reached, /api/mcp immediately returns HTTP 429 Too Many Requests with a Retry-After header (JSON-RPC error -32029). Excess requests are rejected and require client backoff rather than server-side holding.

Infrastructure Caps Apply Even to Internal Unlimited-Credit Accounts

In pre-release mode, the internal admin tier holds 999,999 product credits for application testing, while non-admin users start with 0 credits. Product credits do not bypass MCP infrastructure admission caps: per-organization, per-principal, and global rate/concurrency limits apply across all tiers.

Quick Start: Safe Client Configuration & JSON-RPC Verification

Examples below use the safe placeholder key ak_live_your_api_key_here and target https://nexitia.ai/api/mcp. This page never auto-fetches or embeds live API keys from browser storage. Client snippets illustrate the Streamable HTTP contract and do not claim unexecuted third-party client certification.

MCP Bridge Example (mcp-remote for Cursor / Claude Desktop)

{
  "mcpServers": {
    "aros-cloud-federation": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://nexitia.ai/api/mcp",
        "--header", "Authorization:${AROS_AUTH}"
      ],
      "env": {
        "AROS_AUTH": "Bearer ak_live_your_api_key_here"
      }
    }
  }
}
Ready to copy safe placeholder snippet (press Escape to reset status).

Note the colon has no trailing space in Authorization:${AROS_AUTH} — mcp-remote splits header arguments on whitespace, so the spaced form is truncated.

Process arguments are visible to local users via the process list. On a shared workstation, store the header in a restricted file and pass --header-file (one Name: value per line).

Direct Streamable HTTP JSON-RPC 2.0 Probe (curl)

curl -sS -X POST https://nexitia.ai/api/mcp \
  -H "Authorization: Bearer ak_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "tools/list",
    "params": {}
  }'
Ready to copy safe placeholder snippet (press Escape to reset status).

Include Content-Type: application/json, Accept: application/json, text/event-stream, and MCP-Protocol-Version: 2025-11-25 on direct JSON-RPC POST requests to https://nexitia.ai/api/mcp.