io.hunchful/hunchful

Official7 tools

by filinils · Dockerfile

Read and grow a person's falsifiable, consent-based model of how they work with AI (CMP).

Builds and maintains a personal model of how users work with AI through consent-based data.

Topics

cmpmcpmcp-servermodel-context-protocol

Captured live from the server via tools/list.

read_model

Read a Hunchful collaboration model: its hunches (axis, pole, confidence), the axis ids you can refine, and how you're connected. Start here. With OAuth, omit modelId to read the connected person's own model.

Parameters (1)

modelIdstring
Model id. Omit when connected via OAuth to use the person's own model.

propose_refinement

Propose a refinement (provenance pointers only). It lands in the owner's confirm queue — nothing changes until they accept. Authorized by OAuth (own model) or a contributionToken.

Parameters (3)

modelIdstring
contributionTokenstring
Scoped propose-only key, if not connected via OAuth.
itemsarrayrequired

suggest_question

Suggest a NEW question/axis for the person — a dimension their model doesn't capture (situational axes welcome: name it 'When <situation>'). It lands in their Hunchful inbox and, by default, emails them; nothing is added until they answer. Authorized by OAuth (own model) or a contributionToken. Use sparingly — about once a week at most.

Parameters (8)

modelIdstring
contributionTokenstring
Scoped propose-only key, if not connected via OAuth.
namestringrequired
Short axis name, e.g. "When plans change suddenly".
poleAstringrequired
Pole A label — one way of working.
poleBstringrequired
Pole B label — the other way.
questionstringrequired
The question, addressed to the person.
whystring
Why you're asking — what you observed (no quotes, no names).
bystring
Your name, e.g. "claude".

add_hunch

Record a NEW hunch the person just confirmed in conversation — a custom axis with their answer, added directly to their model (visible, revisable, removable by them). OWNER-LEVEL trust required: OAuth as the owner, or the editToken. Only record what the person actually said — never invent or infer a hunch they didn't confirm. For situational axes name it 'When <situation>'. If they haven't answered yet, use suggest_question instead.

Parameters (8)

modelIdstring
editTokenstring
The model's edit key, if not connected via OAuth.
namestringrequired
Short axis name, e.g. "When plans change suddenly".
poleAstringrequired
Pole A label.
poleBstringrequired
Pole B label.
polestringrequired
The pole the person SAID fits them.
confidencenumber
0.05–0.97; default 0.7 for a fresh self-stated answer.
bystring
Your name, e.g. "claude" — recorded in the revision history.

find_complementary_thinkers

Which famous thinkers would COMPLETE this person — opposite poles on the axes where opposites unstick each other (not similarity). Open read; great for curiosity and for explaining what a complementary collaborator looks like. Share the pages as links.

Parameters (1)

modelIdstring
Model id. Omit when connected via OAuth to use the person's own model.

find_matches

Look for complementary PEOPLE for the connected person (rule: agents propose, humans accept — this creates pending proposals the human decides on in their Hunchful hub; identities are never revealed here). Requires OAuth as the owner or the model's editToken, and the person must have joined introductions on their matches page.

Parameters (3)

modelIdstring
editTokenstring
The model's edit key, if not connected via OAuth.
directionstring
seek = they want a fresh angle; offer = they can offer one. Default seek.

apply_refinement

Apply a refinement directly as one logged revision (append evidence pointers, nudge confidence). Authorized by OAuth (own model) or an editToken. Prefer propose_refinement unless the owner asked for direct writes.

Parameters (3)

modelIdstring
editTokenstring
The model's edit key, if not connected via OAuth.
itemsarrayrequired

README.md3 KBView on GitHub

Hunchful MCP server

Remote MCP server: https://hunchful.io/mcp (Streamable HTTP)

Hunchful is an open implementation of the Cognitive Model Protocol (CMP): a person makes a revisable, falsifiable model of how they collaborate best with AI — hunches with a confidence, an uncertainty, and what would change my mind — at a permanent URL any agent can read. This server lets your assistant read that model, adapt to it, and help it grow slowly, with the person approving everything that matters.

Add it

Claude — Settings → Connectors → Add custom connector → https://hunchful.io/mcp

ChatGPT (developer mode) — Settings → Connectors → Add → URL https://hunchful.io/mcp, auth OAuth (sign in with your Hunchful account to act on your own model) or none (open reads; pass keys as tool arguments).

Anything else — any MCP client that speaks Streamable HTTP. OAuth 2.1 with PKCE + dynamic client registration; discovery at /.well-known/oauth-authorization-server.

Tools (rising trust)

Tool	Auth	What it does
`read_model`	none	The full model: hunches with confidence, uncertainty, falsifier, pole labels, situational activation rules, and the open-questions to-do list.
`find_complementary_thinkers`	none	Which famous thinkers would complete this person — opposite poles on the axes where opposites unstick each other.
`propose_refinement`	contribution key / OAuth	Strengthen/weaken suggestions → the owner's confirm queue. Nothing applies until they accept.
`suggest_question`	contribution key / OAuth	Propose a NEW axis as a question → the owner's inbox (+ opt-in email).
`apply_refinement`	edit key / OAuth owner	Direct, logged, reversible confidence nudges with private evidence pointers.
`add_hunch`	edit key / OAuth owner	Record a hunch the person just confirmed in conversation — visible, revisable, removable.
`find_matches`	edit key / OAuth owner	Look for complementary people. Agents propose; humans accept — double opt-in, identities never revealed by the tool.

The rules the server enforces

Everything is a hypothesis — revisable positions on two-poled axes, never labels.
Nothing is silent — every write is logged in the model's revision history; evidence entries are individually deletable and revert exactly what they applied.
Provenance pointers only — no conversation text, quotes, or third-party names, ever.
Never identity — a protected-attribute screen rejects axes about religion, politics, health, ethnicity, gender, sexuality, or neurotype on every write path.
Situational hunches apply only when the person says they're in the state.
Slow by design — the model asks agents for at most one suggestion a day, one new question a week, and silence when nothing real happened.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "hunchful": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://hunchful.io/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Topics

read_model

propose_refinement

suggest_question

add_hunch

find_complementary_thinkers

find_matches

apply_refinement

Hunchful MCP server

Add it

Tools (rising trust)

The rules the server enforces

Links

Install