The run surface

Two tools, two jobs

Oddlynew's MCP server exposes exactly two tools: guide and run. guide is the read-only cold start: it searches and reads maintained public guidance for you. run executes JavaScript server-side against the namespaces your connection exposes for actual organization reads and operations.

run takes one parameter, code: JavaScript statements that run in an async context, so top-level await works directly and whatever you return is the run's result:

Rules for what you write:

Because a run composes many calls in one round trip, the natural unit of work is a small program, not a single operation:

Start with guide, then orient inside run

Use top-level guide when you need to learn the workflow. Inside run, the orientation namespace is the identity entry point: orientation.whoami() takes no arguments and returns a bounded identity summary:

It gives you userId, authMethod ("api_key" or "oauth"), scopes (the OAuth scopes delegated to this connection), organizationCount (how many organizations you hold an active, unexpired membership in), documentationOrganizationId, and a short instructions string. documentationOrganizationId names the organization that holds Oddlynew's own documentation, so documents.* methods can read it directly like any other organization. It is null when the deployment configures none.

guide({ query?, explain?, cursor? }) reads maintained public documentation and returns the readable content directly. query answers a natural-language question. explain takes one namespace name, such as explain: "documents", and returns that namespace's manual: the generated live contract with every method signature first, then the maintained guidance for it. A dotted name like explain: "documents.getDocument" front-loads that method:

query is optional (1 to 500 trimmed characters) and defaults to getting-started guidance. The result carries { query, content, sources, nextCursor?, fallbackToStart? }. Read content directly; when nextCursor is present, call guide again with that token unchanged. sources provides document provenance rather than requiring another read.

guide answers product, workflow, namespace, and integration questions from maintained public documents. For exact parameters, call the method inside run; a wrong call fails with the live server signature.

Guide teaches the API; server validation is exact

Oddlynew keeps both tool descriptions compact. guide owns maintained workflow and API discovery; run carries the durable foundation and executes the live namespace calls. A client can still cache descriptions, so the server's returned signature is the final authority when a call disagrees.

Ask guide which namespace, method, and workflow apply. A question returns maintained readable guidance. guide({ explain: "<namespace>" }) returns that namespace's generated live contract with exact parameters, followed by its maintained manual, and an unknown name answers with the full namespace index. Then call the method inside run; if a parameter is wrong, the server's returned signature is the authoritative live contract.

Do not rely on a static namespace list in this article. Ask guide which namespace and workflow apply, then call the namespaced method inside run. If the server rejects a parameter, trust the signature in the server error, then correct the call. Do not keep retrying a stale client assumption.

If you guess a method name wrong, the failure teaches you the surface rather than just rejecting you. An unknown method comes back as Tool "<name>" not found. Available: <every callable signature on that namespace>, and the message ends with a pointer to that namespace's manual: guide({ explain: "<namespace>" }).

Authorization is checked on every call, not at discovery

Appearing in the index is not permission to call. Every namespace call is authorized independently, against three planes at once:

Integrations follow the same scope rule, with a consequence worth naming: a read-only token can observe connected integrations but can never act through them. Each integration enumerates its read methods explicitly; everything else — posting, sending, managing, provisioning on the external platform — refuses without mcp:write, and a method that has not been classified yet refuses as a write rather than passing as a read. What a write may reach externally is bounded a second time by how the organization set up the connection: the access level chosen when connecting an OAuth integration, or the permissions on the API key the organization stored. Granting mcp:write therefore never widens a connection beyond what it was set up to allow.

Follow each generated signature instead of applying one blanket organization-selection rule. Most collection queries, organization-owned creation, and administration methods require an explicit organizationId. setOrganizationVisibility is the deliberate exception: it may omit the id only to use the principal's current default organization. Methods that already receive an exact resource id, such as a document, source, or copy-operation id, may derive the owning organization from that resource. Every path authorizes live access to the organization it resolves.

organizations.getMyAccess returns organizationId, roles, enabledFeatures, organizationPermissions (derived from live roles and enabled features), and delegatedScopes. OAuth scopes cap what a connected client may do for a user. An organization API key instead authenticates a dedicated machine principal: the key is only a credential, and effective access comes from that principal's live memberships and roles. Provisioning documents:read assigns the documents_api_reader role, which permits MCP document reads without document creation or management; API-key principals cannot create organizations. When a call is denied, inspect getMyAccess rather than guessing which authorization plane blocked it.

Authorization is resolved live at each call, so an organization created earlier in the same run is usable by later calls in that same run.

Run budgets

Every run executes under fixed limits. The numbers below are the deployment defaults enforced today:

The 30 second budget is wall-clock and covers awaited provider work. The separate 1 second CPU allowance covers synchronous computation in your script: awaiting many calls is fine, grinding through a large in-memory transformation is not. Split heavy work across runs.

The limits behave differently at each boundary:

Fetch data and create documents in the same run

A run can read from a source and create documents from what it read, so the content never passes through your context. The source can be an integration (any namespace with a listSources method, mcp.callTool, api.callOperation), a file in Files up to 96,768 bytes through files.getFileContent, or any other Oddlynew read. Each answer arrives in your script as an ordinary value: shape it into Markdoc there and pass it to documents.createDocument. You write the script and get back ids and counts.

Three rules keep the content on the server and the result honest:

The budgets above set the size of one run. Most namespaces answer up to 128 KB per call; the whole createDocument call, Markdoc included, may be up to 512 KB, so one document from one create holds a little under 512 KB of Markdoc. One read and one create per item take two of the 64 calls, so one run creates at most about 30 documents, and fewer when each create is large, because the run must also finish within 30 seconds. Continue with the next page in a further run, with fresh ids for the new items.

The same recipe works for files and URLs. A text file up to 96,768 bytes is read in the same run with files.getFileContent and encoding: 'text'. Longer text goes through several parts joined on the server, as Long text into a document describes. A public URL first becomes a file with files.ingestFileFromUrl; once files.getFileIngestion reads completed, a later run reads the file and creates the document.

Reading the result

A run comes back as { code, result, error?, logs?, calls? }. code is always an empty string; it is kept only for clients that expect the field, so never read your script back from it. A successful run puts your returned value in result. A failed run puts its public failure message in error; some clients display its unusable result as null. logs carries bounded console output, and a failed run keeps the console output written before the failure. Whenever provider calls ran, calls carries the host-recorded ledger; a zero-provider run can omit it. Always check error before reading result. The tools advertise no output schema, so treat this shape as documentation, not as a contract a client validates.

One class of failure never produces that envelope. A refusal that stops the run before it starts, such as the throughput denial Too many run starts: at most X per minute and Y per hour. Retry in N seconds. (or ... in the current throughput window ...), comes back as an MCP tool error carrying only its message, so there is no result, no logs, and no calls ledger to read.

An uncaught namespace rejection ends the run and appears in the envelope's error field. Expected per-item provider failures are catchable with try / catch: handle them deliberately, return an honest partial result, and inspect the failed_but_handled ledger row. Always await provider calls. Fire-and-forget calls and dispatcher transport failures remain fatal or outcome-unknown, and calls completed before an uncaught failure may already have taken effect. The full failure model and retry rules are in Errors, receipts, and safe retries.

The provider-call ledger

Whenever a run invoked providers, the result carries calls, a host-recorded provider-call ledger. Each row is { tool, outcome, count }, where tool is the qualified namespace.method name and outcome is succeeded, failed_but_handled, or in_flight_unknown. This ledger is host evidence; values returned by sandbox code cannot forge it.

Read it precisely, because the honest reading is narrower than it looks:

Only in_flight_unknown leaves an open outcome question. Before retrying one of those calls, read current state and check; a timeout can happen after a write.

Expected provider failures are catchable

Use try / catch when a provider failure is an expected part of a bounded workflow, such as continuing a per-item sweep after one inaccessible item. A handled rejection remains visible in calls as failed_but_handled, so the returned partial result cannot silently look like a fully successful sweep.

Do not catch failures merely to erase them. Return enough per-item status for the caller to understand what was skipped, and leave unexpected failures uncaught so the run fails visibly. Await every provider call; a fire-and-forget rejection cannot be recovered safely.

An oversized provider result is the one exception and is not a failure: the call did its work, so it resolves with the truncation envelope described above and the run continues.

Idempotency: mint your ids outside the retry

Because a timeout can land after a write, creating methods accept a caller-minted UUID version 7 as an idempotency key. Reusing the same key on a retry returns the existing object instead of creating a duplicate.

For caller-owned idempotency keys, run async () => await ids.mintOperationIds({ count: 1 }) as a separate preparation run. It must be the first and only provider call in that run. Pass a larger count to mint a batch in one preparation run when a plan needs several keys, such as a paging loop. Preserve the returned UUID v7 outside the sandbox, paste it as a literal into the mutation run, and reuse it only when retrying that same intended operation. A UUIDv7 generated by the host is also valid. This applies to caller-owned fields such as creationId, copyId, and connector mutation operationId; never replace a platform-returned operationId, such as the snapshot-copy operation returned by organizations.planDocumentCopy.

Do not derive the key from content, and do not reuse one across different objects. For methods with no idempotency key, read current state before retrying.

Sharp edges worth remembering