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
- 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)
Evaluated Team & Pro Track
- 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
Enterprise & Dedicated Isolation
- 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
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
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.
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 Name | Category | Depth Policy | Accepted Parameters & stable_id Contract |
|---|---|---|---|
| query_memory | Search / Discovery | fast / 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_skills | Search / Discovery | fast / 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_ki | Search / Discovery | fast / deep / auto | task_description, limit?, depth? ('fast' | 'deep' | 'auto') Finds curated public Knowledge Items (KIs) relevant to a scientific or operational workflow. |
| find_helpful_workflow | Search / Discovery | fast / deep / auto | task_description, limit?, depth? ('fast' | 'deep' | 'auto') Finds curated public multi-step workflow specifications matching a research objective. |
| list_skills | Catalog Listing | Not applicable | (no parameters) Lists the human-curated public skill catalog directory without retrieval depth parameters. |
| read_ki_document | Detail 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_document | Detail 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_workflow | Detail 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.
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"
}
}
}
}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": {}
}'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.