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/clientchecks 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
- Idea. You send the person's own words; NeoNumber saves them as an exact version.
- Reading. NeoNumber reads what kind of idea it is and what it is trying to achieve; the person confirms or corrects it.
- 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.
- Measurement plan. Before the work starts, the person agrees what will be measured and when.
- 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 writeEvery 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.tgzimport { 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.tgzKeep 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-mcpCursor
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
| Step | Operation | What 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-Keywith the same body replays the saved answer. The same key with a different body is refused with 409. - 202, or an error with
codenot_yet, means the work is saved and still being written. Read theLocationafterRetry-After. - Lists return 50 items per page. Pass
next_cursorasafter(ascursorfor corrections) until it is null. - The event feed's
next_cursoris never null: follow it whilehas_moreis 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
codebudget_refused. The reason, such asplatform_key_ceiling_exceeded, is inmessage. 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
Run locally without credentials
For contributors with a repository checkout:
pnpm build
pnpm beta:demoIt 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.