Claude MCP setup and API docs

Unsame connects to Claude, Codex and other AI apps as an MCP server (the standard way AI apps connect to outside tools). Before each piece of writing it returns a protocol, a short instruction for your AI. Your AI writes the text. These pages cover connecting it, calling it, and writing the playbook it chooses from.

Getting started

1. Sign in. The free plan has monthly credits and needs no card.
2. Create a goal. Pick a starter template, or describe the repeated writing in one sentence and the playbook is drafted for you (it can take up to 2 minutes). Or ask your assistant to run playbook_init through the author server.
3. Connect the engine to your assistant or your code (next section).
4. Call advise before every generation, give the protocol to your model, then report what happened.

# The pull pattern: the model asks before it writes
tool advise(goal, scope, input, facts)   # MCP, or POST /v1/advise
  -> put draws[0].advice into the system prompt or the message tail
  -> your model writes the text
tool report(draw_id, outcome)            # always free

A goal is one kind of writing you repeat. A playbook is the list of approaches (called ways) for a goal, plus your voice and rules. A scope is a label you choose inside a goal (an account, an agent, a project) under which history and anti-repeat memory are kept; use the same scope every time for the same account. A draw is one instruction (protocol) returned by Unsame. One advise request can ask for several, and a credit pays for one draw.

Starter templates: Threads posts, Threads replies, X posts, X replies, Short video scripts, Newsletter and blog, Cold outreach, Support replies, Release notes.

New here? Follow the 6 steps with screenshots, or see examples for Threads, X, support and cold outreach.

Questions people ask first

What do I type into Claude?

Once, at the start of a chat: the prompt from “Use this goal” on your goal page in the app. It tells Claude which goal and scope to use. Paste it as it is. An example is shown below.

After that, ask for your writing as you normally would, for example “Write a Threads post about our new soy candle.” When you have decided what to do with the draft, say so: “I posted it.” or “Too long, I rewrote it.”

Before you write each piece for this goal, call Unsame's advise tool with goal `threads_posts` and scope `clayandfire`. Use this same scope every time for this account. Follow the instructions it returns. After I tell you whether I used or rejected the draft, report that outcome to Unsame.

What is a scope, and which one should I use?

A scope is a name you choose for whose writing this is, such as your account name without the @. Unsame keeps its memory of recently used approaches per scope, so it avoids recently used approach-and-form combinations. The same approach can return with a different form.

Use the account or project name, and use the same one every time for the same account. If you leave it empty in the app, the goal name is used, which is fine when you have one account. Use different scopes for different accounts so their histories stay separate. A scope may use letters, digits and _ : . - and is created the first time it is used.

What happens when my credits run out?

Your AI gets an error saying the quota is used up, with the time your credits come back. Unsame never sends a weaker protocol instead. A credit pays for one draw, which is one protocol; reports, reading your goals and stats, exports and checks stay free, so you can keep reporting how earlier drafts went.

Free credits reset every month and do not roll over. Paid plans include more credits each month, and you can buy packs. When credits run out, work stops until you upgrade or buy a pack. Drafting a playbook with AI costs 10 credits and accepting a suggested approach costs 5; starting from a template is free. See Pricing mechanics below.

Does Unsame write my posts?

No. Your own AI writes the post. Unsame only tells it how to approach this one: the situation, the points to answer, one approach from your playbook, the form, and your voice and rules. Unsame never sees your AI key and never produces the text.

Can I edit the approaches?

Yes. Open your goal and the Playbook tab to edit the playbook text, or connect the author server and ask your AI to change it. Each save creates a new version, and every approach must be concrete and valid before it is accepted. Your wording is copied as written into the protocol. The learner never edits what you or a template wrote; it only proposes new approaches.

Which AI apps work?

Any app that can connect to a remote MCP server (the standard way AI apps connect to outside tools) with sign-in. That includes Claude.ai and the Claude desktop app through a custom connector, Claude Code, Codex CLI, Cursor and ChatGPT connectors. Claude Code and Codex CLI have been tested against Unsame end to end. Cursor uses the same sign-in steps but has not been tested yet.

If your app has no connector support, call the HTTP API from your own code. Any model can write the text.

Example conversation

One round trip for a candle shop on Threads. The marked lines are what Claude and Unsame say to each other, written out in plain words. The protocol is a real answer from the Threads posts template. The post is written by Claude, not by Unsame.

1. You

   Before you write each piece … (the prompt above, pasted once at the start of the chat)

2. You

   Write a Threads post about this: we poured 40 candles yesterday and 12 came out with cracked tops. Trying a slower cool-down tomorrow.

3. Claude asks Unsame

   Asks for a protocol. Goal: threads_posts. Scope: clayandfire. Input: your note about the candles. This uses 1 credit.

4. Unsame answers

   Situation: behind the scenes
   Engage with:
   - We poured 40 candles yesterday and 12 came out with cracked tops.
   - Trying a slower cool-down tomorrow.
   Approach:
   1. and: what was going on
   2. but: the thing that went wrong or surprised us
   3. therefore: what we did, with the result
   Form: length: under_350_chars; opener: specific_detail; ending: none
   Write: skip the first wording that comes to mind; Form sets the length, opening and ending.
   Always: use one concrete detail from our own day or work: a name, a number, a place, an object or a moment, taken from the input
   Voice: conversational first person, like talking to people who already follow you; at most one emoji; at most one topic tag
   Never: use more than one topic tag, sound like an ad or use hype words, invent a detail, number, price or date that is not in the input, ask followers to like, repost or follow

5. Claude

   We poured 40 candles yesterday. 12 of them came out with cracked tops. So tomorrow’s batch gets a slower cool-down. Fingers crossed for smooth tops.

6. You

   Good. I changed “Fingers crossed” to “We’ll see” and posted it.

7. Claude tells Unsame

   Reports the outcome for that draw: edited, a small change. This is free.

8. Claude

   Done. I told Unsame you posted it with a small edit. Send me the next topic when you are ready.

To see what changes after many reports, read How Unsame gets better over time.

Connect the MCP

MCP is the standard way AI apps connect to outside tools. Unsame has two remote MCP servers, both behind OAuth 2.1 sign-in that apps discover automatically:

• https://api.unsame.io/mcp/engine: sign-in permission advise. Tools: goal_list, advise, report, report_batch, recent, draw_get.
• https://api.unsame.io/mcp/author: sign-in permission author. Tools to init, read, edit, dry-run and export a playbook, and to review the learner’s proposals.

These sign-in permissions are separate from the scope label you send in requests.

Not sure which goal id to use? Ask your AI to list your goals (the goal_list tool, available on both servers). In Claude.ai, open Customize, then Connectors, click + Add, then Add custom connector, paste the engine URL and finish the sign-in. Then, in your chat, click + at the lower left, choose Connectors and turn Unsame on. The tabs below cover each app step by step.

HTTP API

Base URL https://api.unsame.io/v1. JSON in and out; playbooks also accept application/yaml. Every response carries X-Request-Id. For server-to-server calls create an API client in the panel under API keys and exchange it for a token with the client_credentials grant. The HTTP API tab above has the three curl calls end to end.

Advise

{
  "goal": "your_goal",
  "scope": "your_scope",
  "input": { "text": "…what you are reacting to…" },
  "facts": ["glm-5.3 test run finished the task in 14 min"],
  "k": 1
}

{
  "batch_id": "01J…",
  "playbook_version": 7,
  "situations": [{ "id": "someone_post", "label": "reacting to someone's post", "p": 0.93 }],
  "hooks": ["they claim local models can't do agentic coding"],
  "facts": ["glm-5.3 test run finished the task in 14 min"],
  "draws": [
    {
      "draw_id": "01J…",
      "way": "build_on",
      "axes": { "length": "short", "opener": "statement" },
      "advice": "Situation: reacting to someone's post.\nEngage with:\n- …",
      "reason": null
    }
  ],
  "miss": null
}

k asks for up to that many distinct protocols (limited by your plan). Send an Idempotency-Key header and a repeated request returns the stored response without a new draw or a new charge.

Engine routes (sign-in permission advise)

Errors

Errors are {"error":{"code","message","details","request_id"}}.

Playbook format

A playbook is a versioned tree for one goal. YAML is the import and export form; the stored JSON document is isomorphic to it. Edit it in the panel, or through the author MCP.

version: 7                      # server-assigned, increments on every change
goal: indie_dev_x
goal_text: "grow the account as an indie dev: one post a day, reply to mentions"
language: en
voice: "casual, concrete, no emojis"
always: ["one real example from own work"]
never: ["politics", "competitor names"]

situations:
  - id: world_event
    label: "reacting to a news event"
    when: "the input is about a news event relevant to dev tools or AI"
  - id: someone_post
    label: "reacting to someone's post"
    when: "the input is another person's post we may react to"
  - id: scheduled
    label: "a planned post"
    when: "no external trigger; a planned post"
    default: true

ways:
  - id: hot_take
    fits: [trend, world_event]
    how: "one contrarian line, backed by one fact from own experience"
  - id: build_on
    fits: [someone_post]
    how: "quote their point, add the missing angle, end with a question back"
  - id: behind_scenes
    fits: [scheduled, trend]
    how:
      - "hook: the surprising number first"
      - "setup: what we tried"
      - "turn: what broke"
      - "payoff: the fix, one line"

axes:
  length: [one_liner, short, medium]
  opener: [statement, question, number]

variety:
  recent_window: 10             # draws per scope remembered for anti-repeat
  entropy_floor: 0.3            # minimum normalized entropy of the way distribution

learning:
  mode: propose                 # off | propose | auto

Rules enforced on every write

• Ids are [a-z0-9_]{1,64}, unique within their kind in the goal.
• Exactly one situation is default: true. fits must reference existing situations.
• At least one situation and one way. A situation with no fitting way is accepted with a warning.
• when and how must be concrete. A how list has 2 to 8 steps.
• voice and goal_text up to 500 characters; always and never up to 20 entries; at most 6 axes with 8 values each.

Updating a playbook with PUT needs If-Match: <version>. A stale version returns 409 version_conflict instead of overwriting someone else’s edit.

How a way is chosen

For each candidate way that fits the active situations the engine scores fit × novelty × weight, normalises, keeps a minimum entropy so the choice never collapses to one way, and samples from the result. It never takes the top score. Novelty penalises recent uses in the same scope; weight comes from outcomes you report, and is 1.0 until there are any. The panel’s dry run shows this table for any input.

Learning

With learning on, inputs the playbook handled badly (no situation matched, or no way fit) are clustered and turned into proposals. Each proposal carries its evidence: example inputs and cluster size.

• off: nothing is learned and no inputs are kept.
• propose: you accept, edit or reject each proposal. An edited proposal is re-checked before it enters.
• auto: proposals enter as trials and are promoted or retired by outcome data. Only on plans that allow it.

Nodes move through trial, active and retired. Nodes you wrote are never touched. You can pin a node, ban it, or restore a retired one at any time. Strategy (voice, always, never, goal text) is never varied, learned or retired.

Pricing mechanics

• 1 credit = 1 draw. A draw is one instruction (protocol) returned by Unsame. advise with k=3 asks for 3 options in one request, so it is 3 draws and 3 credits.
• Always free: report, report_batch, reads, stats, export and validation.
• Free plan: monthly credits, no card, no rollover. Out of credits returns 429 quota_exceeded with Retry-After.
• Paid plans: included credits, paid in advance. Work stops at the limit.
• Packs: prepaid credits for API users. Each pack has its own price per credit and is valid for 12 months. Credits are used after the monthly included credits.
• AI drafting and suggestions: drafting a playbook with AI costs 10 credits and uses part of a separate monthly AI allowance (tokens, small pieces of text the AI model processes). Accepting a suggested approach costs 5 credits; the learner’s suggestions are generated from the same allowance. Starting from a template is free.

See plans and packs.