SID MCP — Protocol & Tool Surface

SID exposes a compiler for systems as a Model Context Protocol (MCP) server. This page documents the wire protocol, authentication, the tool surface, and the workflows that matter. For setup steps and curl examples see the MCP Setup Guide.

1. Endpoint & Transport

Server URL

https://api.sidislab.com/mcp

Streamable HTTP, JSON-RPC 2.0. The endpoint is live and verified — discovery, OAuth metadata, and tool listing all answer in milliseconds.

Authentication

SID speaks OAuth 2.0 + PKCE with Dynamic Client Registration (DCR). Two ways to connect:

OAuth (recommended): point your MCP client at the server URL, approve in the browser, done. No key exchange.
API key: mint a trial key at sidai.live/login → API Keys. Send it as Authorization: Bearer <key>.

The endpoint returns 401 + WWW-Authenticate pointing at /.well-known/oauth-protected-resource; the client auto-discovers /.well-known/oauth-authorization-server, registers dynamically at /oauth/register, and completes the PKCE flow via /oauth/authorize + /oauth/token.

2. Tool Surface (External Tier)

The external tier exposes 30 tools. Once connected, run tools/list to see your exact set, or fetch the always-live agent manual with get_dis_docs(audience="external_mcp"). The internal mission tools are not on the external surface — they are denied for external tiers.

Category	Tools	Purpose
Discovery	get_system_manifest · get_dis_docs · get_tool_cookbook · get_quota	Orient yourself, fetch docs, get recommended tool sequences, check quota
Memory	recall_memory · suggest_memory_queries · report_outcome	Recall from the memory fabric (private universe + shared community), teach future agents
ADL	estimate_adl · validate_adl · compile_adl	Author and compile ADL through the DIS compiler
Tasks	task_get · task_result · task_cancel	Poll and collect long-running compile/verify jobs
Workspace	get_workspace · get_file · get_diagnostics · put_file · promote_workspace_file · run_workspace_step · package_project · download_artifact	Browse, read, write (sandboxed), promote, verify, package generated projects
Verification	verify_repo · get_passport · verify_passport · passport_summary · list_passports	Mint and verify signed asset passports (SHA-256 → Merkle root → HMAC)
Issues	report_issue · list_issues	File platform bugs and see the closed loop (what was fixed and how)
UI	workspace_theme_generate · workspace_theme_apply	Generate and apply a brand kit to a workspace

Run tools/list with your key for the authoritative, always-current tool set. For the full categorized catalog see the API Reference.

3. Documentation You Can Fetch Live

get_dis_docs(audience=...) returns documentation directly over MCP — always the current revision, never a stale page:

Audience	Content
external_mcp	The complete agent manual — the tool surface, the loops, the golden rule
adl_quickref	ADL authoring quick reference (syntax, annotations, kinds, targets)
error_recovery	Error handling: dis_status codes, common failures, emitter-bug detection
full_manual	The complete DIS V18 language & compiler specification

The web mirror of the DIS documentation lives at /docs/dis — the DIS Compiler V18 reference.

4. The Core Workflows

Build an application

recall_memory → get_dis_docs(audience="adl_quickref") → validate_adl → compile_adl → poll task_get/task_result → get_workspace → run_workspace_step(step="cargo_check") → download_artifact → report_outcome.

Iterate (edits survive regeneration)

get_workspace → put_file (sandboxed) → promote_workspace_file → recompile into the same workspace → run_workspace_step(step="cargo_check"). Your generated/custom/ overlay survives every regeneration.

Verify an asset / mint a passport

verify_repo → poll → share passport_id → buyer: get_passport → verify_passport. If it passes, the asset is exactly what was minted.

Report a bug (closed loop)

report_issue(summary=..., category="dis_bug") → note the issue_id → later list_issues(status="fixed") to see the closed loop.

5. Memory Fabric (not RAG)

Behind the MCP endpoint, SID keeps a memory fabric — geometry, not retrieval-as-answer. For external agents there are exactly two scopes:

Isolated memory — a private universe only you can recall (your own lessons, issues, outcomes).
External shared fabric — the community pool (universe 250): every external report_outcome lands here, every recall_memory searches it, so agents learn from each other.

The internal org fabric (universe 0) is never visible to external callers. The store → recall loop is verified live: a stored marker returns verbatim on later recall, and one agent's outcome surfaces in another agent's recall through the shared pool.

6. Error Handling

dis_status codes

Code	Meaning	Your action
0	SUCCESS	Proceed to build + test
1	PARSE ERROR	Fix ADL syntax, recompile
2	VALIDATION ERROR	Fix ADL semantics, recompile
3	CONSTITUTIONAL VIOLATION	Fix authority/contracts, recompile
4	INTERNAL COMPILER ERROR	Do NOT fix. Report it.

Auth & rate limits

401 + WWW-Authenticate = your client must run OAuth or present a valid Authorization: Bearer key.
external_tool_blocked = the tool is internal-only; it is expected for external tiers, don't fight it.
Trial/developer: 100 req/min. Exceeded → -32029 rate_limited. Wait and retry.

Full debugging reference

See the MCP Setup Guide §8 Debugging and the DIS Compiler Reference for the complete error-handling walkthrough.