Skip to main content
SMEme
Create account Log in

MCP reference

Add deductive reasoning superpowers directly in your AI interface

SMEme exposes expert decision trees as MCP tools any connected agent can call — Claude, ChatGPT, Microsoft Copilot, Cursor, or your own MCP client. Your agent gathers and structures evidence; SMEme validates and runs your deployed logic on our servers and returns structured reports the agent treats as trusted context.

Create account Build in chat

Need help? Ask the MCP tools community — Sign in with GitHub (free).

Build with your agent

Create or revise a decision-tree draft in chat

Your agent constructs the dt_graph_json using SMEme’s design guidance. SMEme validates and saves the graph; the MCP authoring tools do not generate or Deploy it automatically.

  1. Load the design standard

    Call smeme_authoring_design_guidance before drafting the tree.

  2. Construct the graph together

    You and your agent agree the questions, options, branches, and conclusions. The agent then constructs the dt_graph_json from that design.

  3. Validate and fix

    Call smeme_authoring_validate_graph, address the returned findings, and repeat until draft_ready is true.

  4. Save the draft

    For a new tree, call smeme_authoring_create_draft. To revise one, call smeme_authoring_get_draft, validate the revision, then call smeme_authoring_update_draft with its expected_graph_hash.

  5. Review and Deploy in the editor

    Open the returned editor URL, review the saved draft, then Deploy it and choose Listed or Hidden. MCP authoring never changes those settings for you.

Questions about graph design or authoring tools? Ask in MCP Tools.

Prerequisites

Every reasoning tool requires OAuth 2.1 Bearer (Clerk) and a linked SMEme account. Complete OAuth before calling tools.

  1. Connect MCP

    Add the SMEme MCP server from your dashboard or docs; authenticate with Clerk OAuth. A web account is optional when MCP-first signup is enabled — complete email verification and Terms/Privacy in Clerk, then call a tool.

  2. Deploy + Listed

    Deploy the decision tree for reasoning from the editor and set it Listed (not hidden) on your dashboard.

  3. Bootstrap session

    smeme_reasoning_capabilities → compare guidance.content_digest → on first use or mismatch call smeme_reasoning_guidance_get and cache the calling contract.

  4. Pick decision tree

    smeme_reasoning_list → copy decision_tree_id from the response. Do not guess UUIDs.

  5. Guided gather (default)

    smeme_reasoning_evaluate (decision_tree_id only) → loop smeme_reasoning_evaluate_continue until report or isolated_evaluations_required. Do not call template_get first.

Typical call sequence

Default path is guided gather. Bulk worksheet Apply is a labeled alternate. Skills, runbooks, or guidance_get guide most agents.

  1. Discover

    smeme_reasoning_capabilities (bootstrap + guidance digest) → smeme_reasoning_guidance_get when needed → smeme_reasoning_list to find the right deployed decision tree.

  2. Start guided gather

    smeme_reasoning_evaluate(decision_tree_id) starts a durable session. Returns a blind task (question_id, stem, options) plus inquiry_session_id, or is already terminal (report or isolated_evaluations_required).

  3. Continue until terminal

    Gather evidence for only that task, then smeme_reasoning_evaluate_continue. Pass selected_option + provenance_id to admit; omit option to abstain. Loop until report or isolated_evaluations_required — do not invent VERIFY trials in chat. On report, branch on result_kind; optional stop_reason is Inquire status, not a quota denial.

  4. Bulk / audit (optional)

    When you already have a full worksheet assignment: smeme_reasoning_template_get → smeme_reasoning_validate_answers → smeme_reasoning_evaluate_answers with raw_answers_json.

  5. Logical analysis (after gather)

    smeme_reasoning_what_if, smeme_reasoning_edit_affects_path, smeme_reasoning_how_to_reach, smeme_reasoning_decisive_support, and smeme_reasoning_list_conclusions use a provenance envelope — not during an active gather loop in the same thread.

Tool selection guide

Use this table to pick the right tool. Do not substitute siblings.

Task Call Not
Session bootstrap smeme_reasoning_capabilities list — capabilities returns service info, tool list, and guidance.content_digest
Guidance digest only smeme_reasoning_guidance_check guidance_get — prefer digest from capabilities; use check only when skipping capabilities
Full calling contract smeme_reasoning_guidance_get template_get — guidance is platform-wide; per-decision-tree worksheets come from template tools
Find decision trees smeme_reasoning_list Guessing decision_tree_id — list returns only Deployed + Listed decision trees you can invoke now
Drift probe only smeme_reasoning_template_check template_get — check returns digest + in_sync only, no worksheet body
Full evidence worksheet (bulk) smeme_reasoning_template_get evaluate first — ordinary chat gather does not download the worksheet; use template_get for bulk/audit only
Pre-flight ingest gate (bulk) smeme_reasoning_validate_answers evaluate_answers — validate does not run logic, persist audit rows, or return a report
Start guided case gather smeme_reasoning_evaluate evaluate_answers — evaluate starts a blind-task session; bulk Apply is evaluate_answers
Continue guided gather smeme_reasoning_evaluate_continue Guessing VERIFY — continue until report or isolated_evaluations_required
Bulk Apply completed worksheet smeme_reasoning_evaluate_answers evaluate — evaluate_answers needs raw_answers_json; guided gather does not
Catalog possible outcomes smeme_reasoning_list_conclusions During an active gather loop — list conclusions needs no answers; not mid-continue
Scenario delta (one fact change) smeme_reasoning_what_if how_to_reach — what-if compares baseline vs override; it does not search for a repair plan
Minimal edits to reach a target smeme_reasoning_how_to_reach what_if — how-to-reach needs target_conclusion_id from list conclusions first
Path sensitivity under an edit smeme_reasoning_edit_affects_path what_if — path-under-edit asks whether the current path stays forced; use what-if for the alternate world
Which answers were sufficient smeme_reasoning_decisive_support how_to_reach — decisive support needs the target already forced; how-to-reach searches for edits when it is not

How agents invoke tools

  • Semantic match — the agent recognizes the task fits a published decision tree and calls SMEme without you naming a tool.
  • Natural language — e.g. “Run my foreign-national property tax decision tree on this folder.”
  • Direct MCP call — invoke smeme_reasoning_evaluate or any tool by wire name from a runbook or custom client.

Tool catalog

Conceptual map of what each tool does. Wire names match the MCP surface your agent discovers at connect time.

  • Agent guidance

    smeme_reasoning_guidance_get

    Connector-only bootstrap: full calling contract markdown (sequence, errors, provenance). Cache when guidance.content_digest matches.

  • Discover

    smeme_reasoning_list

    List your deployed, Listed decision trees with names and descriptions so the agent can pick the right one.

  • Evidence checklist (bulk)

    smeme_reasoning_template_get

    Authoritative worksheet for bulk/audit slot-filling — not the default chat gather path.

  • Start guided gather

    smeme_reasoning_evaluate

    Start a durable inquire session with decision_tree_id only. Returns a blind task, or a terminal report / isolated_evaluations_required.

  • Continue guided gather

    smeme_reasoning_evaluate_continue

    Admit one answer (selected_option + provenance_id) or omit option to abstain. Loop until report or isolated_evaluations_required.

  • Validate (bulk)

    smeme_reasoning_validate_answers

    Ingest gate before bulk Apply: shape, IDs, option strings, evidence refs, and self-consistency.

  • Bulk Apply

    smeme_reasoning_evaluate_answers

    Apply a completed worksheet envelope (raw_answers_json). Deterministic execution on SMEme — not model improvisation.

  • Non-concluded outcomes

    result_kind on report

    When the report can’t conclude — multiple outcomes, conflicts, or gaps — it says so. No fabricated single answer.

  • List conclusions

    smeme_reasoning_list_conclusions

    Catalog possible outcomes and structural reachability — before how-to-reach, not during an active gather loop.

  • What-if

    smeme_reasoning_what_if

    Change one fact; see what flips. Baseline vs override with structured delta.

  • How-to-reach

    smeme_reasoning_how_to_reach

    Minimal answer changes to reach a target outcome. Call list conclusions first to pick a valid target.

  • Path under edit

    smeme_reasoning_edit_affects_path

    Would a hypothetical answer change break the current forced path? Pair with what-if when you also need the alternate world.

  • Decisive support

    smeme_reasoning_decisive_support

    Minimal sufficient evidence: which answered questions force the target when it is already concluded.

Wire reference

Per-tool purpose, anti-patterns, and key parameters. Wire names match the MCP surface at connect time.

MCP tool When to call When not to call Key parameters
smeme_reasoning_capabilities Once per session after OAuth — service info, MCP surface version, authoritative tool list, and guidance.content_digest. Before OAuth completes; as a substitute for list when you need decision-tree IDs. (none) — returns guidance block with digest
smeme_reasoning_guidance_check Cheap guidance drift probe when you skipped capabilities — compare digest to cached copy. As default bootstrap — prefer guidance.content_digest from capabilities. (none)
smeme_reasoning_guidance_get First use or digest mismatch — download full platform calling contract as content_markdown; cache locally. For per-decision-tree worksheets — use template_get; on every session when digest unchanged. (none) — quota weight 0
smeme_reasoning_list Discover Deployed + Listed decision trees for the connected account; copy id for later tools. When you already have a valid decision_tree_id; to probe hidden or unpublished decision trees. (none) — returns decision_trees[] with id, title
smeme_reasoning_template_check Cheap drift probe — skip template_get when cached digest still matches. When you need question IDs or valid option strings — use template_get. decision_tree_id (UUID from list)
smeme_reasoning_template_get Bulk/audit only — download the authoritative worksheet (manifest_markdown) with question IDs, labels, valid options. Before ordinary guided gather — use evaluate / evaluate_continue; for drift-only — use template_check. decision_tree_id (UUID from list)
smeme_reasoning_validate_answers Bulk Phase 1 ingest gate — structure, option strings, evidence refs, consistency. Returns harness_next. As a substitute for evaluate_answers; during guided gather; with guessed question IDs. decision_tree_id, raw_answers_json — JSON object (legacy flat or provenance envelope)
smeme_reasoning_evaluate Start guided case gather — returns a blind task + inquiry_session_id, or a terminal report / isolated_evaluations_required. With a completed worksheet / raw_answers_json — use evaluate_answers; after template_get as the default chat path. decision_tree_id only
smeme_reasoning_evaluate_continue Continue guided gather — admit one answer; next blind task or terminal. Loop until report or isolated_evaluations_required. To fake VERIFY trials; without inquiry_session_id from evaluate. inquiry_session_id, question_id; admit = selected_option + provenance_id; omit option to abstain
smeme_reasoning_evaluate_answers Bulk Apply on a worksheet envelope; returns report with result_kind. As the default chat path — prefer evaluate / evaluate_continue; before validate passes on bulk. decision_tree_id, raw_answers_json, optional persist (default true)
smeme_reasoning_list_conclusions Catalog conclusion IDs and structural reachability — no answers required. When you need case-specific results — use guided gather or evaluate_answers; during an active gather loop. decision_tree_id — returns conclusion_id values for how_to_reach
smeme_reasoning_what_if Compare baseline vs override assignments; returns before/after reports and structured delta. To find minimal edits for a target outcome — use how_to_reach; with persist=true (v1 unsupported). decision_tree_id, base_raw_answers_json, override_raw_answers_json
smeme_reasoning_how_to_reach Cardinality-minimal answer-edit plans to reach a target conclusion. Without target_conclusion_id from list_conclusions; for simple scenario deltas — use what_if. decision_tree_id, base_raw_answers_json, target_conclusion_id; optional locked_question_ids, max_changes, top_k
smeme_reasoning_edit_affects_path Whether a hypothetical override keeps the baseline path forced; returns path steps lost and a conclusion side-car. For the alternate-world report — use what_if; for “which answers mattered” — use decisive_support. decision_tree_id, base_raw_answers_json, override_raw_answers_json
smeme_reasoning_decisive_support Inclusion-minimal answered-question supports that still force a target already entailed by the current answers. When the target is not yet forced — use how_to_reach; as abduction under incomplete or conflicting answers. decision_tree_id, base_raw_answers_json, target_conclusion_id; optional top_k

For bulk Apply and analysis tools, raw_answers_json is a JSON object string — e.g. {"Q1": "Yes"} or a provenance envelope with answers, evidence_items, evidence_refs. Pass the bare object, not a double-encoded string. Guided evaluate / evaluate_continue do not take a worksheet envelope. Tool calls count against your monthly MCP allowance on paid plans. See pricing.

Chat authoring tools

Design a decision tree with your agent in chat, then save it as a draft on your dashboard. Included on hosted SMEme (Cloud). Self-hosted servers need MCP_AUTHORING_GRAPH_TOOLS_ENABLED=true (and a restart). Drafts are not live for agents yet — Deploy from the SMEme editor when you are ready.

Task Call Not
Design standard (bootstrap) smeme_authoring_design_guidance guidance_get — authoring design is for building trees; reasoning guidance is the evaluate calling contract
Validate chat-built graph smeme_authoring_validate_graph validate_answers — graph validate checks tree structure; answer validate is case evidence
Create dashboard draft smeme_authoring_create_draft Auto-Deploy — draft is unpublished; open editor_url, polish, then Deploy + Listed
Fetch owner draft smeme_authoring_get_draft reasoning_list — list is Deployed + Listed only; get_draft reads unpublished owner graphs
Revise dashboard draft smeme_authoring_update_draft Create another draft — update revises in place with expected_graph_hash

  • Design guidance

    smeme_authoring_design_guidance

    Server-owned design standard for chat authoring. Call once per session; cache by content_digest. Quota 0.

  • Validate graph

    smeme_authoring_validate_graph

    Validate a chat-built dt_graph_json (raw graph or .smeme.json export). Returns draft_ready. Quota 0.

  • Create draft

    smeme_authoring_create_draft

    Create an unpublished dashboard draft when draft_ready. Returns graph_hash. MCP quota 0; still counts against the plan’s decision-tree cap. Does not Deploy.

  • Get draft

    smeme_authoring_get_draft

    Owner-only read of the saved graph, hash, and current validation. Does not require Listed or Deployed. Quota 0.

  • Update draft

    smeme_authoring_update_draft

    Lenient in-place revise with atomic expected_graph_hash. Prefer validate first. Does not Deploy or change Listed; Deployed trees become Stale until Redeploy.

MCP tool When to call When not to call Key parameters
smeme_authoring_design_guidance Start of a chat authoring session — radio-only rules, conclusion-first outcomes, preflight checklist. For evaluating a case — use reasoning tools; every turn when digest unchanged. (none) — quota weight 0
smeme_authoring_validate_graph After the plain-language tree is agreed, and after each fix pass until draft_ready is true. To validate case answers — use smeme_reasoning_validate_answers; before design guidance. dt_graph_json — serialized graph object or export envelope
smeme_authoring_create_draft When validate returns draft_ready and the user confirms — creates an unpublished draft, editor_url, and graph_hash. Before draft_ready; to revise an existing draft — use get/update; to Deploy or List — do that in the editor. dt_graph_json; optional title override
smeme_authoring_get_draft Before revising an owned draft — returns graph, hash, and current validation. For Deployed + Listed evaluate discovery — use smeme_reasoning_list. decision_tree_id
smeme_authoring_update_draft After get + validate when revising — lenient save; pass expected_graph_hash; retry from get on graph_conflict. To create a brand-new tree — use create_draft; to Deploy — editor only. decision_tree_id, dt_graph_json, expected_graph_hash; optional title

Responses & errors

All tools return JSON strings. Parse the payload and branch on error.code when present — tools never raise over MCP.

Shape Fields
Active gather inquiry_session_id, status: ACTIVE, harness_next: continue_evaluate, blind task (question_id, stem, options)
Success (report) report (result_kind, headline, reasoning_path, …), optional evaluation_run_id, warnings, harness_next — from gather STOP or bulk evaluate_answers
Gather needs isolation error.code: isolated_evaluations_required — stop the chat gather loop; session stays ACTIVE for an isolated orchestrator (not advertised on this page)
Success (validate) status: "ok", warnings, harness_next — no report, no persistence
Success (list) decision_trees[] with id, title, count; hint when empty
Failure envelope {"error": {"code": "...", "message": "..."}} — stable code for programmatic recovery
Common error codes Meaning
auth_error Bearer token invalid or user not linked — complete OAuth first.
invalid_decision_tree_id decision_tree_id is not a valid UUID — call list and copy an id.
not_discoverable Decision tree exists but is hidden from MCP — set it Listed on the dashboard.
no_reasoning_artifact Decision tree not Deployed for reasoning — Deploy from the editor.
stale_theory Editor graph changed since last Deploy — Redeploy, then retry.
ingest_* Provenance envelope hard rejects — unknown question ID, invalid option, dangling evidence ref, etc.
quota_exceeded Monthly MCP allowance exhausted — upgrade or wait for reset.
internal_error Unexpected server failure — retry once, then escalate with approximate time.

Connect your agent

Deploy a decision tree, add the SMEme MCP server, and complete OAuth (verify email and accept Terms/Privacy when prompted). With MCP-first signup enabled, that provisions your Free account on the first tool call — signing in on the web remains an alternative path. Your agent loads the calling contract via smeme_reasoning_guidance_get.

Create account MCP setup guide

Signed-in setup guide includes endpoint URL and OAuth Client ID. Stuck connecting? Ask in MCP Clients (GitHub Discussions) — Sign in with GitHub (free). Account or billing: contact@aristalabs.ai.