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 See how it works

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; authenticate with Clerk OAuth Bearer.

  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. Worksheet → validate → evaluate

    smeme_reasoning_template_get → gather evidence → smeme_reasoning_validate_answers → smeme_reasoning_evaluate.

Typical call sequence

Skills, runbooks, or guidance_get guide most agents through this order. Power users can call tools directly by MCP name when appropriate.

  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. Evidence worksheet

    smeme_reasoning_template_get returns required question IDs, labels, and valid answer strings. Optional smeme_reasoning_template_check for drift.

  3. Gather & structure

    Agent reads the skill, pulls facts from chat and connected sources, and maps them to the worksheet with provenance references.

  4. Validate

    smeme_reasoning_validate_answers — structure, option strings, refs, and logical consistency before evaluate.

  5. Evaluate

    smeme_reasoning_evaluate runs your branching graph on SMEme servers. Returns a report with result_kind, path, and conclusions where your logic allows.

  6. Continue

    smeme_reasoning_what_if, smeme_reasoning_edit_affects_path, smeme_reasoning_how_to_reach, smeme_reasoning_decisive_support, and smeme_reasoning_list_conclusions extend the same thread without re-gathering from scratch.

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 smeme_reasoning_template_get template_check — get returns manifest_markdown with question IDs and valid options
Pre-flight ingest gate smeme_reasoning_validate_answers evaluate — validate does not run logic, persist audit rows, or return a report
Run branching logic smeme_reasoning_evaluate validate_answers alone — evaluate requires a worksheet and validated evidence envelope
Catalog possible outcomes smeme_reasoning_list_conclusions evaluate — list conclusions needs no answers; reachability is structural, not case-specific
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

    smeme_reasoning_template_get

    Authoritative worksheet: required questions and exact valid option strings for slot-filling.

  • Structure evidence

    Agent + worksheet

    Map facts from chat, files, and connectors to question IDs with source references before validate.

  • Validate

    smeme_reasoning_validate_answers

    Gate before evaluate: shape, IDs, option strings, evidence refs, and self-consistency.

  • Evaluate

    smeme_reasoning_evaluate

    Run your branching logic on validated evidence. Deterministic execution on SMEme — not model improvisation.

  • Non-concluded outcomes

    result_kind on evaluate

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

  • List conclusions

    smeme_reasoning_list_conclusions

    Catalog possible outcomes and structural reachability before evaluate — or to target how-to-reach.

  • 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 Download the authoritative worksheet — manifest_markdown with question IDs, labels, valid options. For drift-only checks — use template_check; before you have a decision_tree_id. decision_tree_id (UUID from list)
smeme_reasoning_validate_answers Phase 1 ingest gate — structure, option strings, evidence refs, consistency. Returns harness_next. As a substitute for evaluate; without a worksheet from template_get; with guessed question IDs. decision_tree_id, raw_answers_json — JSON object (legacy flat or provenance envelope)
smeme_reasoning_evaluate Run compiled branching logic on validated evidence; returns report with result_kind. Before validate passes; for drift checks; to list possible outcomes without answers. 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 for a user’s answers — use evaluate. 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

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. 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
Success (evaluate) report (result_kind, headline, reasoning_path, …), evaluation_run_id, warnings, harness_next
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. 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.