Tools

Every tool Omni's MCP server offers, with its arguments, what it returns and the errors it can give.

Omni's MCP server offers ten tools. Your AI app lists them with tools/list and calls them with tools/call; you don't call them yourself, but knowing them helps you write better instructions and debug a connection.

Every tool takes a JSON object. Arguments not listed here are refused (invalid_arguments). A space_id is "personal", "inbox" or the id of one of your own spaces (dsp_…), as returned by list_spaces.

Tool	Title	Reads or writes
`list_spaces`	List workspaces	reads
`create_space`	Create a workspace	writes
`get_space_persona`	Get a workspace persona	reads
`update_space_persona`	Update a workspace persona	writes
`update_space`	Update a workspace	writes
`search_memory`	Search memory	reads
`remember`	Remember a fact	writes
`list_files`	List workspace files	reads
`read_file`	Read a workspace file	reads
`write_file`	Write a workspace file	writes

Every tool carries MCP annotations: the reading tools are marked read-only, and none is marked destructive. There is no tool that deletes; deleting is done by you, on the dashboard.

Results

A successful call answers with the result as JSON text in content, and the same object in structuredContent:

{
  "content": [{ "type": "text", "text": "{\"status\":\"created\",\"space_id\":\"dsp_01JX…\",\"name\":\"Startup coach\"}" }],
  "isError": false,
  "structuredContent": { "status": "created", "space_id": "dsp_01JX…", "name": "Startup coach" }
}

A failure the AI can recover from answers isError: true with an error code and a plain sentence to act on. See Errors.

{
  "content": [{ "type": "text", "text": "{\"error\":\"space_not_found\",\"message\":\"No workspace with that space_id that this app may use. Call list_spaces to see the person's workspaces.\"}" }],
  "isError": true
}

list_spaces

List your spaces: Personal (if this app may use it), Inbox and your own, each with its use for line. The AI should call this first and pick the space whose use for matches.

Arguments: none.

Returns:

Field
`count`	number of spaces
`spaces[]`	`space_id`, `kind` (`personal`, `inbox` or `custom`), `name`, `use_for`, `persona_preview` (the first 160 characters), `memories`, `files`, `updated_at`
`spaces[]` (Personal only)	`status` (`ready` once the account is set up), `pending_memories`, `shared_with_omni_app: true`
`how_to_choose`	the picking rule, in one sentence

create_space

Create a new space, starting with empty memory and no files. Only when you ask for one.

Argument	Type
`name`	string, 1–80, required	not "Personal" or "Inbox"
`persona_prompt`	string, up to 8,000	how the AI should act in this space
`use_for`	string, up to 300	one line: what this space is for

Returns: status: "created", space_id, name. If the app was given only some spaces, the new one is added to them.

Errors: invalid_arguments (no name, or a reserved name), limit_reached (three spaces of your own on the free plan).

get_space_persona

Read a space's persona. The AI should adopt it for the rest of the conversation.

Argument	Type
`space_id`	string, required

Returns: space_id, name, persona_prompt, how_to_use. Personal and Inbox have fixed, neutral personas.

Errors: space_not_found.

update_space_persona

Replace a space's persona. Only when you ask to change how a space behaves.

Argument	Type
`space_id`	string, required
`persona_prompt`	string, 1–8,000, required

Returns: status: "updated", space_id.

Errors: space_not_found, not_editable (Personal and Inbox personas are fixed), invalid_arguments.

update_space

Rename a space, or change its persona or its use for line. Only when you ask. Give at least one of the three.

Argument	Type
`space_id`	string, required
`name`	string, 1–80	not "Personal" or "Inbox"
`persona_prompt`	string, 1–8,000
`use_for`	string, up to 300

Returns: status: "updated", space_id.

Errors: space_not_found, not_editable (nothing about Personal can change; for the Inbox, only use_for), invalid_arguments.

search_memory

Search what a space remembers. The AI should search before giving advice, so it builds on what you've already said.

Argument	Type
`space_id`	string, required
`query`	string, up to 500, required	an empty string lists the most recent memories

Search matches the words in the query, then tries its longer words (four letters or more) one by one. It is not semantic search.

Returns: space_id, query, match, count, memories[], and sometimes a note.

`match`
`search`	memories that matched
`recent`	nothing matched (or the query was empty), so the 25 most recent memories in the space
`pending`	Personal is still being set up; these are the memories waiting to move in (`status: "setting_up"`)

Each memory has memory_id, fact, kind, topic, saved_at and source: the app that saved it, such as Claude, or Omni app for Personal memories from the iPhone app.

Errors: space_not_found.

remember

Save one durable fact, as a short self-contained sentence, to exactly one space: the one whose use for fits. Without a space_id it goes to the Inbox. A fact with the same topic replaces the older one.

Argument	Type
`fact`	string, 1–2,000, required	for example "Their startup, Lumen, sells AI bookkeeping to dentists."
`space_id`	string	leave it out to save to the Inbox
`topic`	string, up to 60	such as `pricing` or `runway`; saving the same topic again updates it
`kind`	one of `profile_fact`, `goal`, `project`, `preference`, `commitment`, `routine`, `constraint`, `note_summary`, `relationship`	defaults to `profile_fact`

Returns: status: "remembered", space_id, memory_id, topic. Saved to Personal, it adds a note that the Omni app will know it too. While a new account's Personal is being set up, status: "saved_pending": the memory is kept and moved in automatically.

Errors: space_not_found (including Personal when this app may not use it), invalid_arguments (an empty fact), limit_reached (200 memories in a space), not_saved.

list_files

List the text and Markdown files in a space. Personal has no files.

Argument	Type
`space_id`	string, required

Returns: space_id, count, files[] with path, bytes and updated_at.

Errors: space_not_found, no_files (Personal).

read_file

Read one file by its path, as listed by list_files.

Argument	Type
`space_id`	string, required
`path`	string, 1–200, required

Returns: space_id, path, bytes, content.

Errors: space_not_found, no_files, file_not_found.

write_file

Create or replace a text or Markdown file. Paths may use folders, such as plans/week-1.md.

Argument	Type
`space_id`	string, required
`path`	string, 1–200, required	a relative path ending in `.md`, `.markdown` or `.txt`: letters, numbers, spaces, dots, dashes, underscores and folders, no `..`
`content`	string, required	UTF-8 text, up to 100 KB on the free plan

Returns: status (created or replaced), space_id, path, bytes.

Errors: space_not_found, no_files (Personal), invalid_path, invalid_content (not UTF-8 text), limit_reached (file size, or 20 files in a space).

Instructions

When an app connects, Omni sends it these instructions (initialize and server/discover), so every AI files things the same way:

Omni is the person's memory and workspaces, shared across their AI apps and the Omni app.
- Start with list_spaces. Every workspace has a use_for line. "personal" is the person's own Omni memory (about them: life, preferences, people, plans), shared with the Omni app and its companion. "inbox" is for anything unclear.
- Pick the one workspace whose use_for matches. If two fit, ask the person once which one, then keep using it.
- Never save the same fact to two workspaces.
- Search before advising: call search_memory on the workspace you are working in and build on what is there.
- Anything unclear goes to the inbox (remember without a space_id saves there).
- In a workspace with a persona, read it (get_space_persona) and adopt it. Save durable facts with remember, one short self-contained sentence each.
- If a tool says Omni's free limit is reached, tell the person in plain words.