MCP reference

The local stdio server is run with nauro serve --stdio. Claude Code and other MCP clients spawn this process and talk over stdin and stdout. The --stdio flag is a hidden no-op kept for backward compatibility, since stdio is the only supported local transport (the former local FastAPI HTTP transport was retired).

There is no --project flag on the local server. It resolves the project from the cwd’s .nauro/config.json.

On startup the stdio server syncs best-effort before accepting tool calls, then runs mcp.run(transport="stdio"): a generation replica refreshes its installed generation from the server, and a legacy cloud project pulls latest from the remote. Refresh and pull failures are logged and the server starts with local state.

The server is a FastMCP("nauro", ...) instance at log_level="WARNING"; its instructions are MCP_INSTRUCTIONS_STATIC with the approval boundary restated for local and legacy projects and, for generation-backed projects, the decision reference instructions (prepare the draft, obtain approval, then submit its saved reference). Every local read tool has a renderer in nauro_core.renderers.RENDERERS and returns a CallToolResult with a single TextContent block carrying the renderer output; a missing or raising renderer falls back to a JSON dump of the envelope. On a local or legacy project flag_question and update_state answer with a flat status string and propose_decision returns the result envelope; on a generation replica the typed writes (flag_question, update_state, update_stack, share_context) return the replica write result, marked isError unless its status is committed or discovered.

The hosted endpoint is https://mcp.nauro.ai/mcp. Add it as an MCP connector in your tool’s settings to reach a cloud-synced project from surfaces without a local copy (for example claude.ai web) or from another machine.

The hosted path requires nauro auth login, then a one-time nauro link --cloud to promote the local project, then nauro sync. The hosted server implementation lives in a private repository but consumes the same ALL_TOOLS registry and operations kernel.

The local FastMCP server and the remote HTTP server read tool metadata from the same nauro_core.mcp_tools registry. The local server derives input schemas from Python type hints and consumes title, description, and annotations; the remote (JSON-RPC) server consumes the whole ToolSpec entry directly. The local server also registers update_stack and share_context from the hosted-only specs in the same module, with a description that names the generation replica they write through.

# Local stdio server (spawned by the MCP client; runnable directly)
$ nauro serve --stdio

Source: packages/nauro/src/nauro/cli/commands/serve.py; packages/nauro/src/nauro/mcp/stdio_server.py; packages/nauro/README.md; README.md.

Every tool is closed-world (openWorldHint: False). It operates only on the local or remote Nauro store.

Writes are non-destructive (destructiveHint: False). The source comment states writes are additive and nothing is ever deleted.

Read tools carry _READ_ANNOTATIONS = {readOnlyHint: True, openWorldHint: False} plus idempotentHint: True. Write tools carry _WRITE_ANNOTATIONS = {readOnlyHint: False, destructiveHint: False, openWorldHint: False} plus idempotentHint: False, except create_project, whose operation_id replays the original outcome and so carries idempotentHint: True.

_READ_ANNOTATIONS  = {"readOnlyHint": True,  "openWorldHint": False}
_WRITE_ANNOTATIONS = {"readOnlyHint": False, "destructiveHint": False, "openWorldHint": False}

Source: packages/nauro-core/src/nauro_core/mcp_tools.py.

nauro adopt (or nauro setup claude-code) writes the entry into the repo’s project-scope .mcp.json under mcpServers["nauro"]. The entry shape is {"command": "<validated absolute path to nauro>", "args": ["serve", "--stdio"]} when a durable install is available. Setup probes candidates, prefers durable absolute installs, warns before recording a fragile working path, and uses bare nauro only as the warned terminal fallback.

Cursor is wired once per user, not per repo: nauro setup cursor writes the user-global ~/.cursor/mcp.json with {"type": "stdio", "command": "<validated absolute path to nauro>", "args": ["serve", "--stdio"]}, removes an owned legacy entry from <repo>/.cursor/mcp.json, and fails when no durable absolute nauro executable can be validated. Codex is also user-global: nauro setup codex writes [mcp_servers.nauro] in ~/.codex/config.toml with command, args = ["serve", "--stdio"], and startup_timeout_sec = 20; the timeout is a floor, so an entry whose startup budget already meets it, through startup_timeout_sec or the startup_timeout_ms alias, keeps its own value.

The JSON connector below is the Claude Code entry; the Cursor entry adds "type": "stdio". The TOML entry that follows is what Codex reads.

{
  "mcpServers": {
    "nauro": {
      "command": "<validated absolute path to nauro>",
      "args": ["serve", "--stdio"]
    }
  }
}

[mcp_servers.nauro]
command = "<validated absolute path to nauro>"
args = ["serve", "--stdio"]
startup_timeout_sec = 20

The hosted remote connector is registered under a name distinct from the local nauro stdio server, as in the Codex example below.

Hosted failure modes split by cause. Exhausting the monthly free-tier allowance (5,000 tools/call per account) is a tool-level result, not a transport error: the call returns HTTP 200 with isError and a message carrying the reset date, so the model can relay it in conversation, and successful calls near the threshold carry an appended remaining-allowance note. The per-user burst rate limiter is separate and does return HTTP 429 (transient; retry). Details under plans and limits.

$ codex mcp add nauro-cloud --url https://mcp.nauro.ai/mcp

# pin the OAuth callback port in ~/.codex/config.toml (Codex 0.131.0+)
mcp_oauth_callback_port = 8765

Source: packages/nauro/src/nauro/cli/commands/setup.py; packages/nauro/src/nauro/cli/integrations/json_mcp.py; packages/nauro/src/nauro/cli/integrations/cursor.py; packages/nauro/src/nauro/cli/integrations/codex_config.py; README.md.

The counts: 11 tools are shared (ALL_TOOLS: 8 read, 3 write); the local stdio server registers 12 (7 read, 5 write), dropping list_projects and adding update_stack and share_context; the hosted endpoint serves 14 (HOSTED_TOOLS), adding create_project as well. Each entry below gives the tool name, READ or WRITE kind, where it is served, a one-line purpose, input parameters (type, required or optional plus default), and return shape. Schemas are from mcp_tools.py (input_schema); return shapes from the kernel *Result Pydantic models.

Every tool except list_projects and create_project accepts an optional project_id (string), used by the remote surface to disambiguate when a user has multiple projects; local installs auto-resolve from cwd. list_projects takes an empty object schema; create_project takes name and operation_id only.

The local stdio surface also accepts an internal cwd (string) parameter for store resolution; it is not part of the published input schema, and MCP clients never need to pass it.

On a generation replica the local typed writes (flag_question, update_state, update_stack, share_context) take a request_mode: submit (the default) creates and saves an immutable attempt, discover lists this connection’s saved attempts, recover looks up a saved operation_id and payload_digest, and retry resends the original payload only after an absent lookup within its 24-hour horizon. The two reference fields are required for recover and retry and refused on submit and discover, and reference modes cannot carry content. On a local or legacy project flag_question and update_state reject these fields, and update_stack and share_context return status: blocked with error_code: generation_required whatever the arguments.

Returns project context at the requested detail level (L0 concise, L1 working set, L2 full dump).

L0 is the concise orientation payload: project summary, current state, top open questions, and the last 10 decisions. L1 is a bounded working set, and L2 is the full dump. On mature stores, L2 can reach hundreds of thousands of tokens, so agents should start with L0 and pull exact decisions on demand.

Inputs:

• level (string enum L0|L1|L2, optional, default L0). Detail level. The kernel also accepts int 0|1|2.
• project_id (string, optional).

Returns GetContextResult: content (markdown payload string) on success, or error (kind="rejected", invalid level) otherwise. L0 appends a *Last synced: ...* trailer when present; L2 appends a ## Snapshot Diff (...) block; empty or no-decision stores get a NO_CONTEXT_YET body. The envelope adds store and project identity.

Returns the raw markdown of any file in the project store (a low-level escape hatch).

Inputs:

• path (string, required). Path relative to store root, e.g. project.md, decisions/001-initial-architecture.md.
• project_id (string, optional).

Returns GetRawFileResult: content (file text) on success, or error (kind="error") on a miss. The adapter rejects path traversal with Invalid path: <path>, and on a miss adds an available_files list (capped at 20, excludes snapshots/).

Browse the full decision history (beyond the last 10 in get_context, or with the include-superseded filter).

Inputs:

• limit (integer, optional, default 20). Max decisions returned.
• include_superseded (boolean, optional, default false).
• project_id (string, optional).

Returns ListDecisionsResult: decisions, a list of DecisionSummary rows (number, title, date?, status, type?, confidence), sorted by number descending and truncated to limit.

Returns a specific decision by its number, as a header triage projection or the full body.

Inputs:

• number (integer, required). Decision number, e.g. 23.
• mode (string enum header|full, optional, default full). header is frontmatter plus title plus short lede; full is the complete decision markdown.
• project_id (string, optional).

Returns GetDecisionResult: content (decision markdown body) on success, or error (kind="error") on a miss.

Shows what changed in the project context since the last snapshot, or since N days ago.

Inputs:

• days (integer, optional). Look back N days; finds the nearest snapshot to N days ago and diffs against the latest. Omit to diff the two most recent snapshots (session-scoped).
• project_id (string, optional).

Returns DiffSinceLastSessionResult: diff (human-readable diff body) and optional cutoff_date_used (echoes the baseline timestamp for time-based lookups). Sentinel diff strings cover "not enough snapshots (need at least 2)" and "one snapshot covers the requested range" rather than erroring.

Searches all decisions by BM25 relevance over titles and rationale.

Inputs:

• query (string, required, non-empty). Search text.
• limit (integer, optional, default 10). Max results.
• include_superseded (boolean, optional, default false).
• project_id (string, optional).

Returns SearchDecisionsResult: results, a list of SearchHit rows (number, title, date?, status, relevance_snippet?, score), sorted by BM25 score descending and truncated to limit; error (kind="rejected") on an empty or whitespace query.

Checks whether a proposed approach overlaps existing decisions without writing anything; returns related decisions and a deterministic assessment. It is advisory and does not judge whether the proposal should proceed.

Inputs:

• proposed_approach (string, required). The approach you are considering.
• context (string, optional). Extra context on why.
• project_id (string, optional).

Returns CheckDecisionResult: related_decisions, a list of RelatedDecision (id, title, score, status, date, rationale_preview) via Tier 1 plus Tier 2 BM25 retrieval; and assessment (a deterministic summary string).

The tool does not judge conflicts. The agent reads each related decision via get_decision before proposing.

Records an architectural decision; commits on Tier 1 structural validation (single-call), with Tier 2 BM25 similarity advisory (non-blocking). An agent must obtain explicit human approval for every add, update, or supersede before calling this tool.

Inputs:

• title (string). The only schema-required field is rationale: a title must be present for add and supersede (Tier 1 rejects a blank one) and must be omitted on update.
• rationale (string, required). Why, including constraints and tradeoffs.
• operation (string enum add|update|supersede, optional, default add).
• affected_decision_id (string, optional). Required when operation is update or supersede (e.g. decision-042).
• rejected (array of {alternative, reason} objects, optional). Alternatives considered.
• confidence (string enum high|medium|low, optional, default effectively medium for add/supersede).
• decision_type (string enum architecture|api_design|infrastructure|pattern|refactor|data_model, optional).
• reversibility (string enum easy|moderate|hard, optional).
• files_affected (array of strings, optional). Repo-relative paths.
• resolves_questions (array of strings, optional). Open-question ids to mark resolved.
• project_id (string, optional).

operation="update" is rationale-only: the server consumes rationale and affected_decision_id and rejects title, rejected, files_affected, decision_type, reversibility, and confidence at the boundary. Use supersede to change any of those. An update bumps the decision’s version and appends a dated paragraph to its rationale.

On a generation-backed project the local server routes the call through the decision reference contract instead, and the single-call commit above does not apply: request_mode defaults to prepare, which takes the content fields and saves an immutable draft without committing; submit commits that draft by its server-issued operation_id and payload_digest after explicit approval, recover looks the same reference up, and retry is a separate explicit action on the original identity and deadline; discover takes only an opaque after cursor. Reference modes cannot replace content, and the answer is a JSON text block marked isError when the status is stale, unresolved, pending, expired, conflict, or disposed. These fields are rejected on a local or legacy project.

Returns ProposeDecisionResult: status (confirmed|rejected), tier (int), operation (add|update|supersede|reject), similar_decisions (advisory RelatedDecision hits), assessment, decision_id (on-disk file stem on success), touched_decisions (files rewritten), resolved_questions (ids stamped resolved), relocated_ids and skipped_prose_ids (which of those entries moved below ## Resolved and which a detached body paragraph held back), and optional error. The confirmed status means the write succeeded; it is not a second approval prompt.

After a successful write the adapter captures a snapshot, refreshes a Nauro-managed AGENTS.md, and pushes to cloud. This incidental path preserves an unmanaged AGENTS.md with a warning. Adopt and setup do the same. nauro sync is the sole explicit overwrite path, and a # Manual section survives replacement.

Flags an unresolved question for human review, or resolves existing questions against a decision (writes open-questions.md). Pass exactly one of question or resolved_by.

Inputs:

• question (string, optional). The question to flag.
• context (string, optional). Why it matters.
• targets (array of strings, optional). Question ids; on flag, duplicate candidates that short-circuit if already resolved; on resolve, the entries to stamp (every id must exist).
• resolved_by (string, optional). Decision id that resolves targets; when set, the call resolves instead of appending.
• project_id (string, optional).

Returns FlagQuestionResult: status (ok|rejected), num (minted id on the ok-flag path; unset when rejected), relocated_ids and skipped_prose_ids on the resolve path (what moved below ## Resolved and what a detached body paragraph held back), and error. On flag, the adapter may add a BM25 similarity hint pointing to an addressing decision (the question is still logged). On success it captures a snapshot and pushes.

On a local or legacy project the local stdio surface does not surface the structured envelope; it returns a short string ("Question flagged." / "Question(s) resolved." / a hint plus "The question has still been logged." / a rejection reason). On a generation replica it returns the replica write result described under update_stack.

Replaces the project’s current state body (state_current.md) with the delta, archiving the prior body to state_history.md, and triggers a snapshot. Each call replaces the whole body rather than appending, so compose one delta per session; deltas over 5,000 characters (MAX_DELTA_LENGTH) are rejected at the boundary.

Inputs:

• delta (string, required). What changed, e.g. "Deployed v0.2.0 to staging".
• expected_revision (string, optional; not in the shared schema, added by the local stdio server for a generation replica). The state_revision from an authorized read, or absent; an omitted value uses the installed replica’s revision, and retries keep the saved revision.
• project_id (string, optional).

Returns UpdateStateResult: status (ok wrote a new state body; noop means no existing state file to update), optional warning (keyword-overlap caution; the update is still applied), and optional error. On a non-noop the adapter captures a snapshot and pushes.

On a local or legacy project the local stdio surface returns a short string ("State updated." optionally with the warning appended). On a generation replica it returns the replica write result described under update_stack.

Replaces the complete stack.md document in one call. content is the full replacement (Markdown, at most 40,000 characters, STACK_DOC_CHAR_LIMIT), stored byte-exact with no normalization; partial patches are not supported. stack.md is reported material (technologies, dependencies, compatibility observations); goals, constraints, and choices with rationale belong in propose_decision.

Served by the hosted endpoint, and registered by the local stdio server, where it writes only through an attached generation replica. Annotations are the write set with idempotentHint: False.

Inputs:

• content (string, required). The complete replacement document.
• expected_revision (string, optional). The lowercase SHA-256 hex stack_revision observed on a prior read, or absent when the file did not exist; enforced when supplied. The local server fills an omitted value with the installed replica’s revision.
• operation_id (string, optional in the schema). Client-generated idempotency identifier (1 to 128 printable ASCII characters); the hosted surface requires it, and resending the same id with the same payload returns the original outcome. On the local server it is the saved reference instead, paired with payload_digest and request_mode as described above.
• project_id (string, optional).

Returns, hosted: UpdateStackAccepted (status="ok", stack_revision, previous_revision, receipt_id, event_id) on a committed write, or StackRevisionConflict (status="stale_revision", expected_revision, current_revision; nothing written) on a mismatch.

Returns, local replica: a write envelope keyed by status. committed carries receipt_json plus the replica_status of the post-commit refresh (or error_code: receipt_refresh_required when that refresh fails; the write is still committed) and a guidance_status; revision_conflict_observed carries expected_revision and current_revision with unresolved: true; discovered carries attempts; the server’s own observations absent, expired, digest_conflict, and (for update_state) noop_observed can also come back. Diagnostic outcomes (refused, blocked, unresolved, unverified, recovery_required, retry_expired) carry an error_code and guidance. The envelope echoes operation_id and payload_digest, and a status other than committed or discovered is returned as an isError result.

Creates one immutable context brief and its discovery pointer as a single operation: the body lands at context/<slug>.md and a pointer entry is appended to open-questions.md so other agents can find it. Slugs are permanent: a taken slug returns a conflict with a fresh suggestion, to be retried as a new operation. pointer_kind is brief for shared context, resume for an in-flight work handoff, or selection for a parked candidate set.

Served by the hosted endpoint, and registered by the local stdio server, where it writes only through an attached generation replica. Annotations are the write set with idempotentHint: False.

Inputs:

• slug (string, required). 1 to 120 lowercase ASCII letters, digits, or internal hyphens; maps only to context/<slug>.md.
• content (string, required). The complete immutable brief body, at most 51,200 UTF-8 bytes (MAX_BRIEF_BYTES, 50 KiB).
• pointer_kind (string enum brief|resume|selection, required).
• summary (string, required). A nonempty single line of at most 300 characters with at least one visible character, carried in the discovery pointer; match the brief’s own summary.
• operation_id (string, optional in the schema). As for update_stack: required on the hosted surface as the idempotency identifier; the saved reference on the local server.
• project_id (string, optional).

The local server rejects an expected_revision on this tool.

Returns, hosted: ShareContextAccepted (status="ok", path, question_id, event_id, content_digest, receipt_id) on a committed write, or SlugConflict (status="slug_conflict", slug, suggested_slug) when the slug is taken.

Returns, local replica: the same write envelope as update_stack, with slug_conflict_observed (slug, suggested_slug, unresolved: true) in place of the revision conflict. A slug conflict leaves the saved attempt unresolved: recover its reference and reconcile the outcome before another operation, without changing the slug or payload of that attempt.

Returns the projects this user has access to (the discovery entry point for picking a project_id).

Inputs: none (empty object schema).

Returns the projects accessible to the current user. It is not registered on the local stdio server, because local installs auto-resolve to the single project store, so the discovery tool is unnecessary; only the remote or hosted surface registers it. The return-shape detail is not defined in nauro_core.operations (it is handled by the private hosted server).

The hosted result also carries a usage line (used count, monthly allowance, remaining, reset date), so list_projects doubles as the self-serve usage check.

Creates an empty hosted project for the authenticated account; it works before the caller has any project. The server trims outer whitespace from name, which must then be nonempty and at most 100 characters, with no other character restrictions. The authenticated bearer identity becomes the creator and initial owner; the server derives the project id, membership, owner role, timestamps, generation identity, storage keys, receipt, and audit facts, and the caller cannot supply any of them.

Annotations are the write set with idempotentHint: True, the only write tool with that hint: operation_id is an account-scoped idempotency key, so resending the same id with the same trimmed name replays the original outcome instead of creating another project, and a different trimmed name conflicts.

Inputs:

• name (string, required). The project name.
• operation_id (string, required). Client-generated idempotency identifier (1 to 128 printable ASCII characters).

The schema sets additionalProperties: false and takes no project_id. It is not registered on the local stdio server and has no CLI mirror. Like list_projects, its return shape is hosted-side and not defined in nauro_core.operations.

Source: packages/nauro-core/src/nauro_core/mcp_tools.py; packages/nauro/src/nauro/mcp/tools.py; packages/nauro-core/src/nauro_core/operations/results.py; packages/nauro/src/nauro/mcp/stdio_server.py; packages/nauro/src/nauro/sync/generation_writes.py; packages/nauro/src/nauro/sync/write_arguments.py.

The arguments below are passed in MCP tools/call requests, one example per common workflow.

// get_context at session start
{ "name": "get_context", "arguments": { "level": "L0" } }

// search the decision log
{ "name": "search_decisions", "arguments": { "query": "authentication", "limit": 10 } }

// check before adopting an approach (read-only, no write)
{ "name": "check_decision",
  "arguments": { "proposed_approach": "Use Redis as the hot-read cache" } }

// record a decision (write)
{ "name": "propose_decision",
  "arguments": {
    "title": "Adopt Redis for hot-read cache",
    "rationale": "In-memory cache for hot read paths; lower p99 than DB round-trips.",
    "rejected": [{ "alternative": "Memcached", "reason": "Less feature-rich" }],
    "files_affected": ["src/cache.py", "src/api.py"],
    "confidence": "medium",
    "decision_type": "infrastructure"
  } }

Source: packages/nauro-core/src/nauro_core/mcp_tools.py (input schemas); README.md (CLI mirror of propose-decision).

• One shared registry nauro_core.mcp_tools.ALL_TOOLS holds 11 tools: 8 read, 3 write. Order: get_context, get_raw_file, list_decisions, get_decision, diff_since_last_session, search_decisions, check_decision, propose_decision, flag_question, update_state, list_projects. HOSTED_TOOLS appends update_stack, share_context, and create_project for 14.
• Read tools (8): get_context, get_raw_file, list_decisions, get_decision, diff_since_last_session, search_decisions, check_decision, list_projects. Write tools (3): propose_decision, flag_question, update_state. Specs outside ALL_TOOLS (3, all write): update_stack, share_context, create_project; the local server registers the first two.
• The local stdio server registers 12 (7 read, 5 write): the shared tools without list_projects, plus update_stack and share_context, which write only through an attached generation replica. The hosted endpoint serves 14. list_projects and create_project are hosted-only, since local installs auto-resolve the single project store.
• Local transport: nauro serve --stdio runs nauro.mcp.stdio_server.run_stdio(), a FastMCP("nauro") server over stdin and stdout. --stdio is a hidden no-op kept for back-compat; stdio is the only local transport. On startup a generation replica refreshes its installed generation and a legacy cloud project pulls latest, both best-effort.
• Hosted endpoint: https://mcp.nauro.ai/mcp (private repo); requires nauro auth login plus nauro link --cloud plus nauro sync. Enter the URL with no trailing slash.
• All tools are openWorldHint: False (closed-world); writes are destructiveHint: False (additive, nothing deleted). Reads add readOnlyHint: True plus idempotentHint: True; writes add readOnlyHint: False plus idempotentHint: False, except create_project, whose operation_id replay makes it idempotentHint: True.
• .mcp.json connector entry shape (written by nauro adopt / nauro setup claude-code): mcpServers.nauro = {"command": "<validated absolute path to nauro>", "args": ["serve", "--stdio"]} when a durable install is available. Cursor uses the user-global ~/.cursor/mcp.json with the same shape plus "type": "stdio"; Codex uses [mcp_servers.nauro] in ~/.codex/config.toml with command, args = ["serve", "--stdio"], and startup_timeout_sec = 20 as a floor. Fragile and unresolved fallback paths produce warnings.
• Every tool except list_projects and create_project accepts optional project_id (string); list_projects takes an empty object schema and create_project requires exactly name and operation_id. propose_decision requires affected_decision_id when operation is update or supersede; flag_question takes exactly one of question or resolved_by; update_stack requires content and enforces expected_revision when supplied; share_context requires slug, content, pointer_kind, and summary.
• Return shapes are typed Pydantic *Result models in nauro_core.operations.results; each adds store (and the local surface adds project identity) at serialization time.

This page documents the shared tool contract from the public nauro_core registry and operations layer, which both the local stdio server and the hosted server implement. The hosted server’s own internals (JSON-RPC framing, auth flow, response envelope) belong to the hosted service and are not part of this contract.

list_projects and create_project are the two tools served only by the hosted endpoint: their inputs and purpose are documented above, but their exact return fields are hosted-side and may evolve independently of the stdio contract. update_stack and share_context belong to both surfaces; locally they write only through an attached generation replica.

On the counts: 11 shared tools (8 read, 3 write); the local stdio server registers 12 (7 read, 5 write) by dropping list_projects and adding update_stack and share_context; the hosted endpoint serves 14 (HOSTED_TOOLS).