Agent Codex by Arcology Labs
View Markdown ↗CONTRACT 0.1.0
On this page

MCP tool reference

Availability and transport

The official MCP SDK adapter implements the four tools below. Production remote MCP is not enabled. These schemas describe implemented behavior, not a public credential issuer or working connection URL. Read connection and identity first.

Machine-readable input/output schemas and annotations are in mcp-tools.json, exported from the actual SDK tool listing and checked against it in tests. Each tool's inputSchema and outputSchema is a separate JSON Schema root; resolve its local #/definitions/... references within that schema, not against the outer listing object. The advertised server is agent-codex, title Agent Codex, version 0.1.0. Compatibility tool names remain field_notes_*.

Successful calls return a JSON object in structuredContent and the same serialized JSON in a text content block. Notebook failures return isError: true and a text content block containing {"error":{"code":"...","message":"..."}}. MCP argument validation failures can be protocol errors rather than notebook-error objects. Inspect both failure forms. MCP also caps the entire argument tree at 2,000 cumulative array elements/object members, independently of entry byte/depth limits.

No owner, issuer, Passport ID, API key, cookie or OAuth token belongs in tool arguments. Authorization is checked afresh immediately before service execution. An entry ID identifies an entry, not a notebook owner.

field_notes_save

Scope: both notes:read and notes:write.

Arguments: exactly requestId (1–128 characters) and entry (entry input). Returns {"entry": Entry}.

{"requestId":"synthetic-design-note-001","entry":{"content":"The launch checklist needs a rollback step.","title":"Launch checklist","tags":["launch"],"provenance":{"source":"synthetic example"}}}

A request ID is a deduplication key within the authenticated codex. Retry with exactly the same request ID and entry input. Reusing it for different content or metadata returns conflict. A successful retry returns that entry's current revision, which may have changed since the first save. Do not interpret it as historical revision replay. Save annotations: non-destructive, idempotent.

field_notes_get

Scope: notes:read.

Arguments: exactly id, the lowercase UUIDv4 returned by save or search. Returns {"entry": Entry} including full original content.

{"id":"11111111-1111-4111-8111-111111111111"}

This UUID is synthetic, not a real entry. A missing entry and an entry belonging to another codex both return not_found. Get annotations: read-only, idempotent.

Scope: notes:read.

All arguments are optional. An empty object browses current entries.

  • query: 0–256 characters. Case-insensitive NFKC-normalized literal substring across content, title or tags. No semantic or fuzzy search.
  • tag: 1–64 characters. Exact, case-sensitive tag filter.
  • relatedAgentId: 1–512 characters. Exact identifier filter. It does not grant access to that agent.
  • limit: integer 1–50, default 20.
  • cursor: an opaque continuation from the preceding result, at most 2,048 characters.
{"query":"rollback","tag":"launch","limit":20}

Returns entries (summaries without full content), optional nextCursor, and coverage:

{"entries":[],"nextCursor":"opaque-continuation-from-this-query","coverage":{"storage":"active-only","mode":"literal-substring-v1","scanned":100,"hasMore":true}}

The continuation shown above is descriptive, not a valid token. Follow the actual returned token while keeping query/tag/related-agent filters unchanged. Filtered pages scan at most 100 candidates. An empty page with nextCursor is not proof of no matches. Unfiltered browsing scans only the requested page size. Search order follows entry IDs, not recency or relevance. Concurrent edits can change results; pagination is not a snapshot. Search annotations: read-only, idempotent.

field_notes_update

Scope: both notes:read and notes:write.

Arguments: exactly id, expectedRevision (positive safe integer), and a complete replacement entry. Returns {"entry": Entry} with revision incremented by one.

{"id":"11111111-1111-4111-8111-111111111111","expectedRevision":1,"entry":{"content":"The launch checklist now includes a rollback step.","title":"Launch checklist","tags":["launch"]}}

Omitted optional fields are removed. This is not a patch. On conflict, retrieve the latest entry, reconcile and make a new explicit replacement. Never blindly retry with a higher revision. No revision-history API is promised. Update annotations: destructive replacement, not idempotent.

Unsupported tools

There is no delete, archive, restore, upload, sharing, export or identity-management MCP tool. Do not invent agent_codex_* replacements or a delete method. The browser-local development preview's import/export functions are not remote MCP capabilities.