Capabilities · Oaken Mail

MCP workspaces

Core: Mail 31

Operation	Provider	Permission	Summary
approve_action	core	mutate	Say yes to an action that is waiting for approval: it runs now, for this message and route.
create_folder	core	mutate	Make a folder under Inbox, and any folders above it. A path that already exists is fine.
create_label	core	mutate	Make a label (a tag for finding mail). A label that already exists is fine.
get_action	core	read	Show what the actions did about a message: for each action and route, whether it succeeded, failed or was skipped. An action that is waiting for approval is a parked job.
get_message	core	read	One message: its summary and triage when stored, the cleaned text and metadata. Prefer include_text=false and read the summary first; open the text only when you need it. Never marks it read.
get_message_rules	core	read	How a message was filed: its labels, flags and disposition, and the rule behind each.
get_raw	core	read	The raw headers of a message, and optionally its raw bytes, for inspection. Not for MCP.
get_thread	core	read	A conversation as a tree: every message that shares a thread, in reading order, each with its parent and depth.
get_triage	core	read	Show the stored triage verdict for a message: which triager rated it, the category, level (priority) and whether a reply is owed.
list_actions	core	read	The actions waiting for approval or for a route to be answered, and what the actions did lately. No message text.
list_labels	core	read	Every label, folder (location) and disposition with how many live messages carry it.
list_mailbox	core	read	The sidebar: Inbox and Discarded, the folder tree under Inbox, and labels, each with how many messages are in it and how many are unread. Empty folders and labels are included.
list_messages	core	read	List the newest messages that match the filters, with a short snippet of each.
mailbox_counts	core	read	The sidebar's numbers in one call: Inbox, Starred and Discarded, every folder (location) and every label, each with how many messages and how many are unread. No mail content.
mark_read	core	mutate	Mark messages read. Written back to the mailbox; undoable.
mark_unread	core	mutate	Mark messages unread. Written back to the mailbox; undoable.
message_dismissed	core	read	The user stopped looking before the delay passed: cancel the pending mark.
message_presented	core	mutate	The user is looking at this message: core marks it read after the configured delay.
move_to_folder	core	mutate	File messages into a folder under Inbox (made if new), or back into the Inbox. The person's choice beats a Sieve rule's.
search	core	read	Hybrid search: keyword and meaning together. Understands from:, before:, after:, is:unread, category: and "quoted phrases".
search_keyword	core	read	Keyword search (BM25) over the index: words, phrases, -exclusions and from:/label:/after:.
set_flagged	core	mutate	Star or unstar messages. Written back to the mailbox through \Flagged; undoable.
set_labels	core	mutate	Add labels to messages (made if new) and remove labels the person added earlier.
sieve_check	core	read	Compile a Sieve script and report the first error, with its line.
sieve_delete	core	mutate	Remove one Sieve script. It stops running on the next filter pass.
sieve_get	core	read	Read one Sieve script's text, so an editor can load it.
sieve_list	core	read	List the Sieve scripts on disk, and any skipped with the reason.
sieve_save	core	mutate	Compile a Sieve script and, only if it compiles, save it so it runs on the next filter pass.
sieve_test	core	read	Run a Sieve script on one message and show each effect and its rule. Stores nothing.
triage_message	core	mutate	Run the triagers on one message now and store the verdict.
undo	core	mutate	Undo a read-state change from the audit log, restoring exactly what each message was.

Core: Pipeline 28

Operation	Provider	Permission	Summary
cache_stats	core	read	The enrichment cache: how many answers it holds, how big, from which prompt versions, and how often it saved a model call.
cancel_job	core	mutate	Cancel a queued job, or ask a running one to stop at its next safe point.
clear_cache	core	mutate	Delete cached model answers (all, or one task's). Only derived results go: mail, the index and the usage record are untouched, and anything cleared is recomputed the next time it is asked for, at the cost of the model calls the cache had saved.
events_tail	core	read	The most recent events core published, from its event log: what happened before this page was opened, or before core was last restarted. Ids, states and numbers, never mail text.
list_audit	core	read	The newest audit-log rows: who changed what, why, and whether it can be undone.
list_jobs	core	read	The newest jobs in the durable queue, with their status, attempts and any scrubbed error.
list_schedules	core	read	Every sync schedule: when it next runs, how the last run went, and whether it is paused.
pause_backfill	core	mutate	Pause the model-bound ingest stages (embed, enrich), or just one with stage. Mail keeps landing and being filtered; a running job finishes. It survives a restart.
pause_schedule	core	mutate	Pause a sync schedule until it is resumed.
pipeline_status	core	read	Where ingest stands: each stage's queue, throughput and ETA, and jobs parked as failed.
rebuild_index	core	mutate	Rebuild the search index from the raw store (resumable).
remove_schedule	core	mutate	Remove a sync schedule (a per-folder one, or an account's, which stops its sync).
reset_usage	core	mutate	Clear the token-usage record (the figures the stats page shows). Model calls and the context savings both go; mail, the index and the enrichment cache are untouched. The accounting starts fresh from the next call.
resume_backfill	core	mutate	Resume the model-bound ingest stages after a pause, or just one with stage.
resume_schedule	core	mutate	Resume a paused sync schedule: it is due now and its failure count is cleared.
retry_job	core	mutate	Re-queue a failed or cancelled job to run now, clearing its last error.
retry_parked	core	mutate	Re-queue one parked ingest job, or with all=true every parked ingest job, to run again.
savings_summary	core	read	Tokens saved, by caller: model calls the cache skipped, and mail text kept out of a client's context. Estimates.
set_pipeline_limits	core	mutate	Change how many jobs of a stage run at once, now and after a restart. A running job is never dropped: a lower number takes effect as running jobs finish.
set_schedule	core	mutate	Create or change a sync schedule. The floor and the timezone are checked now.
status	core	read	A short health summary: accounts, messages, index, queue, plugins and paused schedules.
storage_info	core	read	Where Oaken keeps its data and how big it is: the two databases, their write-ahead logs and the quarantine folder. Read from the filesystem, not by scanning mail.
sync_now	core	mutate	Sync an account (or one folder) now, or every account on every provider when none is named. Each is a job that calls the provider's pull; it joins a sync already queued or running.
trace_set	core	mutate	Turn the trace on or off now (`oaken trace on\|off`). It holds mail text, so it is off until asked for; `[log] trace = true` is the start-up default. Not applied across a restart.
trace_status	core	read	Whether the trace is on, and where its file is. The trace records what a model or an agent is told, thinks and returns, with the full text.
trace_tail	core	read	The most recent trace events (oldest first), optionally for one plugin (plugin.KIND.NAME), one job or one message: prompts, responses, thinking, tool calls, timings and what was committed. Holds mail text.
usage_summary	core	read	Model calls and tokens per workspace, stage and model, and what the cache saved.
vacuum	core	mutate	Rewrite raw.db and index.db to give back the space deleted rows left. One at a time, and not while a rebuild runs. It holds each database's write lock while it works (ingest waits, reads go on) and needs about the database's own size free on the disk.

Core: Enrichment 5

Operation	Provider	Permission	Summary
enrich_message	core	mutate	Run the enrichers on one message now.
get_enrichment	core	read	Show the stored enrichment results (summary, actions, inspector) for a message. The triage verdict is `get_triage`.
reprocess	core	mutate	Bring one pipeline stage up to date for old mail (parse, filter, embed, triage, enrich, action, scan or start).
summarize_message	core	mutate	Summarize messages with the local model. Optionally mark the summarized ones read.
try_triage	core	read	Run triage on one stored message, or on pasted text, and show the verdict without storing it: which triager decided (a header rule or a model), the category, priority and whether a reply is owed. For tuning: change a rule or the triage model, then try again.

Core: System 30

Operation	Provider	Permission	Summary
check_plugin_config	core	read	Test one plugin's settings before saving them: they are checked against the plugin's own schema and capabilities, then a throwaway instance is started on them and asked if it is healthy. Give no change to test the saved settings. The running plugin is not touched and nothing is written.
check_settings	core	read	Test a change to one section of core's settings without saving it: field-level errors, which keys would change, and whether it needs a reload, a reindex or a restart.
check_workspace	core	read	Validate workspace settings without saving: field errors, the effective backend, and a warning when trust would drop from secure to insecure.
config_get	core	read	Read the current config.toml text (non-secret; tokens are never stored here).
config_reload	core	mutate	Reload core on the saved config.toml (the Reload button). Core rebuilds in place: the old config is restored automatically if the new one fails to start. Watch /v1/health to see it come back (the port may change).
config_save	core	mutate	Validate and save config.toml, backing up the previous file (the Save button). Does not reload core; call config_reload to apply.
config_validate	core	read	Test an edited config.toml against the settings schema without saving it (the Test button).
create_account	core	mutate	Add an account. Its credential is stored separately by the provider's own auth command (for example gmail.auth).
create_agent	core	mutate	Register an external agent and show its token once.
get_account	core	read	One account: provider, its non-secret settings, what the provider's settings are, and why it cannot sync if it cannot.
get_plugin_config	core	read	Read one plugin's settings: its [plugins.NAME] table, the schema of its settings and an example to start from. Non-secret only.
get_settings	core	read	Core's own settings that a client may edit: each key's value, default, where the value comes from (default, config.toml or an environment variable), its schema, and what changing it costs (a reload, a reindex). Name a section or get them all.
get_workspace	core	read	One workspace: its settings as editable TOML, the effective LLM backend, and usage numbers.
list_accounts	core	read	The configured accounts: id, provider and display name (never credentials).
list_agents	core	read	List the registered agents (never their tokens).
list_operations	core	read	Every operation with its permission class, and whether MCP clients may call it.
list_plugins	core	read	Every plugin: kind, version, capabilities, health, the operations it offers, its settings.
list_workspaces	core	read	List every configured workspace plus the implicit 'default', with its trust level, effective LLM backend, and aggregate usage numbers.
plugin_disable	core	mutate	Stop a plugin and keep it off until plugin_enable or a restart, without reloading core. Put `enabled = false` in the plugin's [plugins] table to make it last.
plugin_enable	core	mutate	Start a plugin that plugin_disable stopped. A plugin whose table says `enabled = false` stays off until that line is removed and the plugin is reloaded.
plugin_health	core	read	Whether plugins are started and healthy, and why not if they are not.
plugin_reload	core	mutate	Restart one plugin on the current config.toml (and pick up a plugin installed since boot) without reloading core.
remove_account	core	mutate	Remove an account and its sync schedules. Stored mail is kept; the credential is dropped.
remove_workspace	core	mutate	Remove a workspace from config.toml. Refuses to remove 'default'. LLM cache and usage rows are kept; clear them separately.
revoke_agent	core	mutate	Revoke an agent at once; the jobs it holds go back to the queue.
set_account_config	core	mutate	Replace an account's non-secret settings (and, if given, its display name).
set_operation_exposure	core	mutate	Choose whether MCP clients may call an operation, or all of a plugin's operations.
set_plugin_config	core	mutate	Change one plugin's settings in its [plugins.KIND.NAME] table (or the older [plugins.NAME]) and leave the rest of config.toml, comments included, as it is. Keys are merged onto the saved ones (or replace them); text from an editor keeps the person's comments. Validated first; the previous file is backed up. Does not restart the plugin: call plugin_reload to apply.
set_settings	core	mutate	Change core's settings in one section of config.toml, keeping the file's comments and every other table. Validated first (the whole file), and the previous file is backed up. It does not reload core: apply it with config_reload (`oaken reload`). The result says which keys need a reload, a reindex or a restart.
set_workspace	core	mutate	Create or update a workspace in config.toml, keeping all other tables and comments. The change takes effect immediately (live reload); no restart needed.

Providers 0

Operation	Provider	Permission	MCP	Summary
None.

Triagers 0

Operation	Provider	Permission	MCP	Summary
None.

Embedders 0

Operation	Provider	Permission	MCP	Summary
None.

Enrichers 4

Operation	Provider	Permission	Summary
greeter.boom	greeter	read	Always fails.
greeter.hello	greeter	read	Say hello.
greeter.rename	greeter	mutate	Rename it.
greeter.secret	greeter	read	Never over MCP.