Skip to content

Developers

Add before-and-after evaluation to your product. HTTP API, a typed TypeScript client, a local MCP server for AI assistants, and embeddable public scorecards.

Private beta. The API origin and keys come with an invitation.

What you can build

  • HTTP API. Save ideas, request Reviews and Comparisons, agree how to measure them and record Results from your own product.
  • TypeScript client. @neonumber/client checks each call against the contract and types the answer.
  • MCP server for AI assistants. A local server with 30 tools, so an assistant can evaluate an idea with the person who wrote it.
  • Embeddable public scorecards. Show a published Review on your site, with its method, range and corrections.

How it works

  1. Idea. You send the person's own words; NeoNumber saves them as an exact version.
  2. Reading. NeoNumber reads what kind of idea it is and what it is trying to achieve; the person confirms or corrects it.
  3. Review. A judgment of that version: a Score out of 100 with its range, why, the biggest uncertainty and a useful next test. The Score is a judgment, not a probability.
  4. Measurement plan. Before the work starts, the person agrees what will be measured and when.
  5. Result. What happened, per objective, with missing outcomes shown as missing.

Reviews and Results are never combined into one number.

We want the record to mean the same thing wherever someone encounters it. Each Review names its scoring method and each Result shows what was measured, so people can understand the record outside the tool that created it.

Authentication

A workspace owner creates a Platform Key under Workspace settings → Developer keys, choosing only the permissions it needs and an expiry of 1 to 90 days. The secret is shown once: save it straight into your secret store. A key acts for the person who created it and stops working if they leave the workspace.

Send three headers:

Authorization: Bearer $NEONUMBER_PLATFORM_KEY
NeoNumber-Contract-Version: 1.1
Idempotency-Key: one saved key per write

Every answer names the contract version it was served under. A request without the version header is served 1.0 and marked as deprecated.

Never paste a key into an assistant conversation.

Quickstart with curl

# The origin comes with your invitation; the key comes from your secret store.
# NEONUMBER_API_ORIGIN and NEONUMBER_PLATFORM_KEY are read from the environment.

# 1. Save the idea in the person's own words.
curl -sS -X POST "$NEONUMBER_API_ORIGIN/v1/ideas" \
  -H "Authorization: Bearer $NEONUMBER_PLATFORM_KEY" \
  -H "NeoNumber-Contract-Version: 1.1" \
  -H "Idempotency-Key: idea-0001" \
  -H "Content-Type: application/json" \
  -d '{"schema_version":"idea-create.v1","advisory_only":true,"gate_authority":"none",
       "words":"A two-week referral offer for existing customers.","attachments":[]}'
# Save version (with version.idea_id) and reading_id from the answer.

# 2. Read the reading until its state is ready.
curl -sS "$NEONUMBER_API_ORIGIN/v1/readings/$READING_ID" \
  -H "Authorization: Bearer $NEONUMBER_PLATFORM_KEY" \
  -H "NeoNumber-Contract-Version: 1.1"

# 3. Request the Review of that exact version. It is written asynchronously.
curl -sS -i -X POST "$NEONUMBER_API_ORIGIN/v1/ideas/$IDEA_ID/score" \
  -H "Authorization: Bearer $NEONUMBER_PLATFORM_KEY" \
  -H "NeoNumber-Contract-Version: 1.1" \
  -H "Idempotency-Key: review-0001" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d '{"schema_version":"score-request.v1","advisory_only":true,"gate_authority":"none",
       "version":'"$VERSION"',"method_id":null}'
# The answer names the Review's Location and a Retry-After.

# 4. Read the Location after Retry-After until the Review is written.
curl -sS "$NEONUMBER_API_ORIGIN$LOCATION" \
  -H "Authorization: Bearer $NEONUMBER_PLATFORM_KEY" \
  -H "NeoNumber-Contract-Version: 1.1"

To confirm or correct the reading, send the person's corrections to POST /v1/ideas/{id}/versions. It saves a new version; request the Review of that version.

To keep the key out of your shell history, write the header to a private file and pass it with -H @file.

Quickstart with TypeScript

Install from the tarball provided with your invitation:

npm install ./neonumber-contracts-0.0.0.tgz ./neonumber-client-0.0.0.tgz
import { randomUUID } from "node:crypto";
import { NeoNumberClient } from "@neonumber/client";
import { contractSchemas } from "@neonumber/contracts";

const client = new NeoNumberClient({
  origin: process.env.NEONUMBER_API_ORIGIN ?? "",
  token: () => process.env.NEONUMBER_PLATFORM_KEY ?? "",
});

// A literal operation id checks parameters and body and types the reply.
const created = await client.call({
  operation: "post_v1_ideas",
  idempotencyKey: randomUUID(), // save it with the body; reuse both to retry
  body: {
    schema_version: "idea-create.v1",
    advisory_only: true,
    gate_authority: "none",
    words: "A two-week referral offer for existing customers.",
    attachments: [],
  },
});
const idea = contractSchemas.IdeaV11.parse(created.body);
await client.wait(`/v1/readings/${idea.reading_id}`, { attempts: 10 });

const requested = await client.call({
  operation: "post_v1_ideas_id_score",
  params: { id: idea.version.idea_id },
  idempotencyKey: randomUUID(),
  body: {
    schema_version: "score-request.v1",
    advisory_only: true,
    gate_authority: "none",
    version: idea.version,
    method_id: null,
  },
});
const reply = await client.wait(requested.location ?? "", { attempts: 10, maxWaitMs: 30000 });
const review = contractSchemas.Review.safeParse(reply.body);

Quickstart with MCP

Install the server from the tarball provided with your invitation. It runs locally over stdio and gives the command neonumber-mcp:

npm install --global ./neonumber-mcp-0.1.0.tgz

Keep the key in a private file and point NEONUMBER_PLATFORM_KEY_FILE at it. Never write the key itself into a configuration file. Read tools are on by default; write tools appear with NEONUMBER_MCP_ALLOW_WRITES=1, and every write still needs the person's confirmation.

Claude Code

Not yet qualified against this host.

In .mcp.json, the values are read from your environment when Claude Code starts:

{
  "mcpServers": {
    "neonumber": {
      "command": "neonumber-mcp",
      "env": {
        "NEONUMBER_API_ORIGIN": "${NEONUMBER_API_ORIGIN}",
        "NEONUMBER_PLATFORM_KEY_FILE": "${NEONUMBER_PLATFORM_KEY_FILE}"
      }
    }
  }
}

Or add it from the command line:

claude mcp add neonumber \
  --env NEONUMBER_API_ORIGIN="$NEONUMBER_API_ORIGIN" \
  --env NEONUMBER_PLATFORM_KEY_FILE="$NEONUMBER_PLATFORM_KEY_FILE" \
  -- neonumber-mcp

Cursor

Not yet qualified against this host.

In .cursor/mcp.json, give the path to the private key file, not the key:

{
  "mcpServers": {
    "neonumber": {
      "command": "neonumber-mcp",
      "env": {
        "NEONUMBER_API_ORIGIN": "https://api.example.com",
        "NEONUMBER_PLATFORM_KEY_FILE": "/absolute/path/to/private/neonumber-key"
      }
    }
  }
}

Claude Desktop

Not yet qualified against this host.

Open neonumber.mcpb from your invitation. Claude Desktop asks for the API origin and the Platform Key and keeps the key as a sensitive setting. If you configure the server by hand instead, use NEONUMBER_PLATFORM_KEY_FILE.

Ideas, Reviews, Results and Methods are also readable as neonumber:// resources, and the evaluate_idea prompt walks an assistant through a first Review. The guide lists every tool.

Workflow reference

StepOperationWhat to save
Save the words
The version and its reading_id
Wait for the reading
Its state; ready is not a Review
Confirm or correct the reading
The new version
Request a Review
The Idempotency-Key and the Location
Read the Review
Score, range, why, uncertainty, next test, Method
Compare alternatives
The Location; a tie is an answer
Propose measurements
The proposal id
Confirm the plan
The plan, once the person agrees
Report outcomes
The Result id
Read the Result
Each objective, missing ones included
Correct a Result
The new Result; the old one stays
Find due measurements
next_cursor until it is null
Follow corrections
The cursor, after each page
Start a campaign
The campaign id and its revision
Record the choice
The new revision
Read the benchmark
The reason, when there is none yet
Follow events
next_cursor, after each page; poll with it

Errors, retries and pagination

Branch on the HTTP status, then the error's code, then its retry. Every refusal has the same shape:

{
  "schema_version": "error.v1",
  "advisory_only": true,
  "gate_authority": "none",
  "code": "conflict",
  "message": "idempotency_key_conflict: this key was used with a different body",
  "retry": "same_key_only",
  "request_id": "request-0001"
}
  • The same Idempotency-Key with the same body replays the saved answer. The same key with a different body is refused with 409.
  • 202, or an error with code not_yet, means the work is saved and still being written. Read the Location after Retry-After.
  • Lists return 50 items per page. Pass next_cursor as after (as cursor for corrections) until it is null.
  • The event feed's next_cursor is never null: follow it while has_more is true, then keep the last one and poll with it. A cursor works only for the workspace that received it.
  • A workspace or key limit answers 402 with code budget_refused. The reason, such as platform_key_ceiling_exceeded, is in message. Never retry it with another key.
  • 401 means the key is missing, expired or revoked; 403 a missing permission or membership; 404 that the item is not available to this key.

What a Platform Key can and cannot do

It can

Save and read Ideas, confirm or correct readings, request and read Reviews and Comparisons, propose and confirm measurement plans, report, read and correct Results, follow corrections and due measurements, and read Records and Methods. With the Campaigns permission it runs campaign decision cycles in its own workspace; with the Events permission it reads the signed event feed.

Not yet

Export, Activity, key management, billing, publication and webhooks.

Embed a public record

A workspace owner chooses to publish under Workspace settings → Publication; nothing is public without that consent. Paste the frame and the short script beside it, which resizes the frame to fit:

<iframe src="https://neonumber.com/embed/SCORECARD_ID" title="NeoNumber public scorecard" width="100%" height="1000" style="border:0" data-neonumber-embed></iframe>
<script>addEventListener("message",function(e){var d=e.data;if(e.origin!=="https://neonumber.com"||!d||d.type!=="neonumber:embed-height")return;var h=Math.min(Math.max(Number(d.height)||0,200),20000);document.querySelectorAll("iframe[data-neonumber-embed]").forEach(function(f){if(f.contentWindow===e.source)f.style.height=Math.ceil(h)+"px"})});</script>

A published Result embeds the same way from /embed/results/RESULT_ID. For your own layout, read GET /v1/public/scorecards/{id} as JSON; it needs no key. Corrections travel with the record: a superseded Review links to the current one.

Staying in sync

Poll the event feed, GET /v1/events, with the cursor you saved last time. Each event is signed and names the Review or Resolution it announces; read that item with your key. Follow the Result corrections cursor and list due measurements with filter=due. Webhooks are planned, with no date yet.

API reference

Downloads

Run locally without credentials

For contributors with a repository checkout:

pnpm build
pnpm beta:demo

It runs the whole workflow through the API and the MCP server with constructed data, no key and no provider spending.

Beta status

  • Nothing is deployed yet; the API origin comes with your invitation.
  • Hosted MCP over HTTP with OAuth is not built. The MCP server runs on your machine.
  • The client, the MCP server and the Claude Desktop bundle are local packages; none is published to a registry.
  • Payments and connector collection are off. The OpenAPI document includes operations outside this beta; documentation does not grant access.
Manage developer keys