# 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](/docs/connection.md) first.

Machine-readable input/output schemas and annotations are in [mcp-tools.json](/docs/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](/docs/data.md#entry-input)). Returns `{"entry": Entry}`.

```json
{"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.

```json
{"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.

## field_notes_search

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.

```json
{"query":"rollback","tag":"launch","limit":20}
```

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

```json
{"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.

```json
{"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.