Terminal
Terminal/Skill
Guides an agent through Monospace REST and SDK data access, typed client codegen, auth, permissions and MCP setup (not for legacy Directus).
By Directus
Works with
npx skills add directus/monospace-agent-skills --skill monospaceWork with a Monospace instance: query and mutate data through the REST API or the typed SDK, generate instance-specific types, bootstrap workspaces and discover schema, and use the per-workspace MCP server. Read the traps below, then load the reference that matches the task.
Verified against engine source 4f6f48c (reports 0.7.0) with @monospace/sdk 0.8.0 and @monospace/cli 0.1.0 from continuous build 31d52d0. Monospace is in early access. If an instance behaves differently, trust the instance and its error messages.
monospace sdk generate), the instance's own responses and error messages, and these references. The workspace OpenAPI document describes item routes (use it for payload shapes and codegen). It is not a complete or fully correct catalog of management and schema routes, so use bootstrap-and-schema.md for those.fields selection on item reads and writes. Afterwards, read back using the same key or the user's exact filter.source chain. After 2–3 failed attempts, re-check the schema, permissions, and license instead of retrying.{ data } (plus meta when requested). JSON login, /api/system/info, the /schema manifest, and OpenAPI are bare. A raw item POST returns a data array even for one object. The SDK unwraps only the top level. Nested to-many relations stay relation.data, and to-one relations are direct.deleteOne({ key, fields: ['id'] }) / deleteMany({ filter, fields: ['id'] }) / DELETE …?fields=id. Without one, the engine returns 422 and the row remains. Confirm with a read-back.method(parameters, options?). The first argument is an object ({ key, data, fields, include, filter, sort, limit, offset, meta }), never a positional id. The optional second argument is { unwrapEnvelope: false }, needed to keep meta.totalCount. Collections are cased as named (client.Articles).fields selects scalars, include selects relations. Example: fields: ['id'], include: { author: { fields: ['name'] } }. Don't use dotted paths, nested objects in fields, or deep. Inside include, arguments are filter/sort/limit/offset (no underscore), and operators keep underscores (_eq)._eq, _in, _null), combined with _and/_or/_not, and _some/_every/_none on to-many relations. The full operator table is in the REST reference. _null works only on nullable fields. Field and connector capabilities decide what is filterable, sortable, and writable.sort: [{ field: { direction: 'desc' } }]. -field is rejected.search, no page or cursor, no aggregates. Use limit (default 100) + offset + a stable sort, and meta for totalCount. Unknown parameters can be silently ignored with a 200, so a success status doesn't prove a parameter was applied.string | number, but values outside the safe integer range can round before transmission, so pass large integers as strings. Decimals are strings too. Don't convert money through floats.MonospaceAuthError) and 403 (MonospacePermissionError) get subclasses. Validation failures (400/422), 402 license limits, and 404s arrive as base MonospaceError, so branch on .status. MonospaceValidationError is not currently thrown.You need the host, the workspace (its apiName, used as the URL segment in /api/<workspace>/...), and a token: an API key (Studio → Account → Access → API Keys) or a user access token from login. Use Authorization: Bearer <token>. If login returns requireAcceptTerms: true, surface the pending Studio onboarding step to the operator; successful API calls do not imply terms acceptance. Details: mcp-and-auth.md.
POST https://<host>/api/<workspace>/mcp: per workspace, stateless streamable HTTP, protocol 2025-11-25. The caller needs the ai:mcp entitlement, and anonymous access is 403 unless the public role was explicitly granted it.
// .mcp.json
{ "mcpServers": { "monospace": { "type": "http",
"url": "https://YOUR_HOST/api/YOUR_WORKSPACE/mcp",
"headers": { "Authorization": "Bearer ${MONOSPACE_API_KEY}" } } } }
Seven tools: list_items, create_items, update_item, delete_item, read_schema, read_data_sources, mutate_schema (can be destructive). A tool being listed doesn't mean the caller may run it. Each call is checked against the subject's permissions. To diagnose, send a real initialize request with Content-Type: application/json and Accept: application/json, text/event-stream, not a bare POST: mcp-and-auth.md.
# For a new project; keep existing compatible pins in an established project.
npm install https://pkg.pr.new/directus/monospace/@monospace/sdk@31d52d0
npm install --save-dev https://pkg.pr.new/directus/monospace/@monospace/cli@31d52d0
npx monospace sdk init --url https://YOUR_HOST --workspace YOUR_WORKSPACE --dir ./src/generated/monospace
npx monospace login --url https://YOUR_HOST # or set MONOSPACE_API_KEY
npx monospace sdk generate # writes <output>/index.ts
Import createClient from the generated output, not from @monospace/sdk. The old npx @monospace/sdk … commands no longer work. The engine, SDK, and CLI have independent version numbers. Tested pins, config, and flags: sdk.md.
| Load when | Reference |
|---|---|
Writing TypeScript: install and pin packages, CLI codegen, createClient, browser auth, pagination with a total, types, errors | references/sdk.md |
Reading or writing data: CRUD, relation writes (_connect/_create), deletes, money, read-back verification | references/data-workflows.md |
| Calling HTTP directly: query parameters, envelopes by endpoint, value encoding, item routes, status codes | references/rest-api.md |
Starting from scratch: instance info, license, workspaces, schema discovery, bundled scripts/schema-view.mjs decoder, migrations | references/bootstrap-and-schema.md |
| Logging in, API-key authority, roles and license preflight, MCP setup, tools, and diagnostics | references/mcp-and-auth.md |