Axon MCP Tool Schema (Source of Truth)

Last Modified: 2026-08-31

Contract

• MCP server command: axon mcp
• Operation tool count: 1
• Operation tool name: axon
• Widget tool: axon_status_dashboard (MCP Apps presentation helper, not an operation surface)
• Primary route field: action
• Canonical route form: action + optional subaction
• Response control field: response_mode (path|inline|both|auto_inline; omitted mode auto-inlines small non-document payloads and otherwise falls back to path metadata, while retrieve defaults to inline paged reads)

Code references:

• crates/axon-mcp/src/schema.rs
• crates/axon-api/src/action/*.rs
• crates/axon-mcp/src/server.rs
• crates/axon-mcp/src/server/handlers_*.rs

Task-Augmented Calls

• Server capabilities advertise the SEP-2663 io.modelcontextprotocol/tasks extension in the extensions capability map.
• Task support is server-wide, not per-tool. The rmcp 1.x execution.taskSupport tool field was removed in rmcp 3.x; no tool advertises it.
• A client opts a single call into task mode by carrying the io.modelcontextprotocol/tasks key in the tools/call request _meta, and must itself declare the tasks extension capability. Without the _meta key the call is served synchronously.
• Normal calls still return Axon's canonical JSON success envelope with job_id or job_ids fields for async starts.
• Task-augmented calls use RMCP task lifecycle methods backed by the same durable SQLite job rows.
• Supported task starts: extract.start.
• Unsupported task action/subaction pairs return invalid_params; immediate actions such as help, status, and query remain normal calls.
• Task IDs are stable aliases over Axon job IDs: axon:<kind>:<job_uuid>.
• The lifecycle surface is tasks/get and tasks/cancel. SEP-2663 removed tasks/result and tasks/list: tasks/get returns a DetailedTask that inlines the compact sanitized payload under result once the job completes (or under error when it failed), instead of a raw ServiceJob row, and tasks/cancel acknowledges with an empty result.
• Task objects include pollIntervalMs of at least 5000 ms. Clients should not hot-poll SQLite-backed task status.
• If _meta.progressToken is supplied on a task call, Axon sends allowlisted notifications/progress updates from persisted job progress and stops on terminal status or send failure.
• MCP task metadata belongs in protocol request metadata (_meta.progressToken / task-augmented request fields), not inside the Axon tool argument map.
• Authorization is server-scoped: valid Axon OAuth/static credentials grant Axon server access. Job and task IDs are server-bound references, not per-user ACL objects.

See also:

• MCP overview for normal versus task-augmented workflow guidance.
• Configuration guide for server auth and async job runtime settings.
• Architecture overview for MCP, service, and job-runtime boundaries.
• Repository guide for source layout and testing policy.
• This tool-schema reference for tasks/get, tasks/cancel, _meta.progressToken, and axon:<kind>:<job_uuid> wire details.

Canonical Success Envelope

{
  "ok": true,
  "action": "<resolved action>",
  "subaction": "<resolved subaction>",
  "data": { "...": "..." }
}

Parser Rules

Incoming request map is parsed strictly with serde:

• action is required and must match canonical schema names
• subaction is optional for lifecycle families (extract); when omitted, handlers default to start
• No fallback fields (command, op, operation)
• No token normalization or case folding
• No action alias remapping

Preferred Client Actions

Use CLI-identical top-level actions:

• Lifecycle families: extract, memory
• Direct actions: ask, brand, diff, doctor, endpoints, evaluate, help, map, prune, query, research, retrieve, screenshot, search, source, status, suggest, summarize

For lifecycle management (status|cancel|list|cleanup|clear|recover), use canonical families with subaction:

{ "action": "extract", "subaction": "status", "job_id": "..." }

Response Policy (Context-Safe Defaults)

• When response_mode is omitted, non-document actions auto-inline small payloads and fall back to artifact path metadata for larger payloads.
• retrieve is a document-reading action and defaults to inline-first paged responses.
• ask, research, and summarize always write the full payload to an artifact and include the key answer/summary fields inline in the path-mode response.
• Heavy operations write result artifacts to ~/.axon/artifacts/<context>/ (override root with AXON_MCP_ARTIFACT_DIR).
• Tool response returns compact metadata only by default:
  • path, bytes, line_count, sha256, preview, preview_truncated
• Explicit inline and both modes are capped/truncated and include artifact pointers.
• response_mode=auto_inline/auto-inline selects threshold-based automatic inlining: small payloads return auto-inline, larger payloads return path metadata.

Direct Actions

These actions do not require subaction:

Action	Required Fields	Optional Fields
ask	query (string)	diagnostics, explain, collection, since, before, hybrid_search, ask_chunk_limit, ask_full_docs, ask_max_context_chars, ask_hybrid_candidates, ask_min_relevance_score, ask_doc_chunk_limit, ask_doc_fetch_concurrency, ask_backfill_chunks, ask_candidate_limit, ask_min_citations_nontrivial, ask_authoritative_domains, ask_authoritative_boost, response_mode
brand	url (string)	render_mode, response_mode
diff	url_a (string), url_b (string)	render_mode, response_mode
doctor	--	response_mode
endpoints	url (string)	include_bundles, first_party_only, unique_only, max_scripts, max_scan_bytes, verify, capture_network, probe_rpc, probe_rpc_subdomains, response_mode
evaluate	query (string)	diagnostics, retrieval_ab, collection, since, before, hybrid_search, response_mode
help	--	response_mode
map	url (string)	limit, offset, response_mode
prune	--	plan_id, target, generation, collection, confirm, response_mode
query	query (string)	limit, offset, collection, since, before, hybrid_search, response_mode
research	query (string)	limit, offset, search_time_range, response_mode
retrieve	url (string)	max_points, collection, since, before, response_mode, cursor, token_budget
screenshot	url (string)	full_page, viewport, response_mode
search	query (string)	limit, offset, search_time_range, response_mode
source	--	source, scope, collection, priority, response_mode, detached
status	--	response_mode
suggest	--	focus, limit, collection, response_mode
summarize	url or urls	render_mode, root_selector, exclude_selector, response_mode

Note: graph is a deprecated compatibility field. false/unset is accepted as a no-op; true is rejected because graph retrieval is not wired in production.

Note: MCP search uses the same SearXNG-first/Tavily-fallback search-and-source service as the CLI and REST route. It queues one-page Source jobs for returned URLs so terminal and agent searches are auto-indexed.

Lifecycle Action Families

• extract: start -- start requires urls (array)
• memory: remember|list|search|show|link|supersede|context|reinforce|contradict|pin|archive|forget|review|compact|import|export -- no required fields

Enum Values

ResponseMode

Values: path|inline|both|auto_inline

McpRenderMode

Values: http|chrome|auto_switch

SearchTimeRange

Values: day|week|month|year

Pagination Defaults

List/search style endpoints default to low limits and accept limit + offset.

MCP Resources

Implemented resource(s):

• axon://schema/mcp-tool
• ui://axon/status-dashboard

Runtime Dependencies

Server reads existing Axon stack vars:

• QDRANT_URL
• TEI_URL
• AXON_HEADLESS_GEMINI_CMD — path to Gemini CLI (default: gemini)
• AXON_SYNTHESIS_HEADLESS_GEMINI_MODEL — preferred Gemini synthesis model override (optional)
• AXON_HEADLESS_GEMINI_MODEL — legacy alias for AXON_SYNTHESIS_HEADLESS_GEMINI_MODEL
• TAVILY_API_KEY

MCP transport env vars:

• AXON_HTTP_HOST
• AXON_HTTP_PORT

MCP auth env vars:

• AXON_HTTP_TOKEN
• AXON_AUTH_MODE
• AXON_PUBLIC_URL
• AXON_GOOGLE_CLIENT_ID
• AXON_GOOGLE_CLIENT_SECRET
• AXON_AUTH_ADMIN_EMAIL
• AXON_ALLOWED_REDIRECT_URIS

Error Semantics

• Input or shape failures -> MCP invalid_params
• Runtime failures -> MCP internal_error