obto-mcp-extend

Extending the OBTO MCP surface (per-tenant tools, resources, prompts)

The OBTO MCP server is itself extensible from inside a session: the triad CRUD tools — obto_{create,update,delete,list}_mcp_{tool,resource,prompt} — register per-domain dynamic tools, markdown resources, and prompt templates that the server then serves alongside its built-ins to every session in that domain. This is how a tenant grows its own MCP surface without touching server code.

All triad calls are domain-scoped: they require domain (from obto_whoami) but no appName. Regular users target their own domain; super-users may target any tenant. Exposure follows domain inclusion — an artifact registered at domain X is visible to sessions whose domain resolves to X (or to global/a parent).

Dynamic tools (obto_create_mcp_tool)

• Name: lowercase, underscores only (^[a-z][a-z0-9_]*$, ≤50 chars), unique per domain. It becomes available to all sessions in the domain.
• zodSchemaString: the input schema as a Zod v4 string, e.g. z.object({query: z.string()}). Zod v4 trap: z.record(valueSchema) with one argument crashes tool listing for the whole domain — always write the two-argument form, z.record(z.string(), valueSchema).
• handlerFunction: a JavaScript function expression, not a bare statement body — write it async so you can await: async (args) => { const rows = await ...; return { content: [{ type: 'text', text: JSON.stringify(rows) }] }; } args is the validated input. The handler compiles in a vm sandbox and runs wrapped in a timeout + structured envelope (dynamic_tool_failed), so a broken handler fails loudly per-call instead of taking the session down.
• Never save an empty or stub handler. A record whose handlerFunction is blank fails to compile at every session init — a dead tool that error-logs forever. If a tool isn't ready, set isActive: false or delete it.
• Annotations are required and reviewed: readOnlyHint, destructiveHint, openWorldHint (booleans, idempotentHint optional) plus annotationJustifications — a short written justification for each. Set them truthfully; they drive client-side confirmation behavior.