@lobstack-ai/mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,9 @@
 # @lobstack-ai/mcp
 
-An MCP server for the [Lobstack](https://www.lobstack.ai) Gateway. One API key
-reaches every major model, and every call comes back with a receipt: which model
-served it, how many tokens, what it cost.
+An MCP server for the [Lobstack API](https://www.lobstack.ai/api-platform). One
+API key reaches [26 models across 9 providers](https://www.lobstack.ai/models), and
+every call comes back with a receipt: which model served it, how many tokens,
+what it cost.
 
 Works in Claude Desktop, Claude Code, Cursor, Zed, or anything else that speaks
 the Model Context Protocol over stdio.
@@ -118,8 +119,17 @@ against.
 The catalogue: model key, label, tier, provider, context window, and USD per
 million input and output tokens. Optional `tier` and `provider` filters.
 
-A model the registry cannot price comes back with `null` prices and renders as
-`—`. It is not free.
+**The first entry is `auto` — Nex 1, the router.** It carries `tier: "router"`
+and a null price on purpose: its cost is whichever model it picks, which is not
+knowable until the request is scored. That is the one null in this list that is
+not a gap.
+
+Every other null price is. A model the registry cannot price comes back with
+`null` and renders as `—`, and it is not free — a zero there would be a claim
+that a real charge did not happen.
+
+The full catalogue with rates is also public, no key required, at
+<https://www.lobstack.ai/models>.
 
 ### `lobstack_chat`
 
@@ -129,7 +139,7 @@ Sends a prompt or a conversation and returns the reply plus the receipt.
 | --- | --- | --- |
 | `prompt` | string | A single user message. Use this **or** `messages`. |
 | `messages` | array | `{ role, content }`, OpenAI-shaped. Use this **or** `prompt`. |
-| `model` | string | Defaults to `auto` — the router picks the cheapest capable model. |
+| `model` | string | Defaults to `auto` — **Nex 1**, the router, picks the cheapest capable model. |
 | `system` | string | Prepended to the conversation. |
 | `max_tokens` | integer | Cap on the reply. |
 | `temperature` | number | Some models do not accept it; the receipt says when it was dropped. |
@@ -171,14 +181,14 @@ It also reports `unpriced_requests` and sets `is_floor`. The endpoint sums an
 unpriced row as zero — the only arithmetic available — so a total that includes
 one is a lower bound, not a total, and this tool says which.
 
-It does **not** report a savings total. `/api/v1/usage` does not compute one,
-and adding up savings client-side would mean pricing the org's tokens against a
-copy of the rate card. Savings are reported per call, by `lobstack_chat`, where
-the gateway sends them with the reason attached.
+It does **not** report a savings total. Savings are reported per call, by
+`lobstack_chat`, where the API sends them with the reason attached. Adding them
+up client-side would mean pricing the org's tokens against a copy of the rate
+card, and a copy drifts.
 
 ## Two rules about the numbers
 
-**A null cost is not zero.** `cost_usd: null` means the gateway could not price
+**A null cost is not zero.** `cost_usd: null` means the API could not price
 the call. It renders as `unpriced`, never as `$0.00`. Rendering it as `$0.00`
 writes off a real charge, and that exact substitution ran for three months in
 production.
@@ -198,11 +208,11 @@ production.
 | variable | default | notes |
 | --- | --- | --- |
 | `LOBSTACK_API_KEY` | none | Read once at startup. Never logged, never in a tool result. |
-| `LOBSTACK_BASE_URL` | `https://www.lobstack.ai/api/gateway/v1` | For staging and self-hosted deployments. |
+| `LOBSTACK_BASE_URL` | `https://www.lobstack.ai/api/gateway/v1` | The Lobstack API base URL. Change it only to point at a staging deployment. |
 
 **Use `www`, not the bare apex.** `lobstack.ai` redirects to `www.lobstack.ai`,
 and [RFC 9110 §15.4](https://www.rfc-editor.org/rfc/rfc9110#section-15.4)
-requires a client to drop `Authorization` across a host change — so the gateway
+requires a client to drop `Authorization` across a host change — so the API
 answers a perfectly good key with "missing credentials". This server rewrites
 the apex and tells you it did, and refuses to follow any other 3xx rather than
 send a request whose credential has been stripped.

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 /**
- * The MCP server: four tools over the Lobstack Gateway.
+ * The MCP server: four tools over the Lobstack API.
  *
  * Exported as a factory rather than wired straight to stdio so the tests can
  * drive it over an in-memory transport with a real MCP client on the other end,

package/dist/server.js

@@ -1,5 +1,5 @@
 /**
- * The MCP server: four tools over the Lobstack Gateway.
+ * The MCP server: four tools over the Lobstack API.
  *
  * Exported as a factory rather than wired straight to stdio so the tests can
  * drive it over an in-memory transport with a real MCP client on the other end,
@@ -48,7 +48,7 @@ export const SERVER_VERSION = (() => {
         return "0.0.0";
     }
 })();
-const INSTRUCTIONS = `Lobstack is a metered LLM gateway: one key reaches every major model, and every call
+const INSTRUCTIONS = `The Lobstack API is a metered LLM gateway: one key reaches every major model, and every call
 comes back with a receipt saying which model served it and what it cost.
 
 - lobstack_route_preview needs NO API key. It scores a prompt against the same
@@ -56,7 +56,7 @@ comes back with a receipt saying which model served it and what it cost.
   estimated cost. Use it to choose a model, or to show what routing does.
 - lobstack_chat runs the completion. Send model "auto" to let the router pick
   the cheapest model that can handle the prompt.
-- Costs are reported as the gateway priced them. A null cost means the gateway
+- Costs are reported as the API priced them. A null cost means the API
   could not price the call — it does not mean the call was free.
 - A saving labelled "saved" is like-for-like: the caller named a model and got
   something cheaper. A saving labelled "vs ceiling" is measured against the most
@@ -69,23 +69,23 @@ export function createServer(options = {}) {
         title: "Preview routing and cost",
         description: "Score a prompt and report which model the Lobstack router would serve it with, and what that would cost. " +
             "Runs no inference, spends nothing, and NEEDS NO API KEY — use it to pick a model before calling lobstack_chat, " +
-            "or to show what the gateway does on a machine with no key configured. Token counts are estimates; the billed " +
+            "or to show what the Lobstack API does on a machine with no key configured. Token counts are estimates; the billed " +
             "figure comes from the provider's usage block on the real call.",
         inputSchema: routePreviewInput,
         outputSchema: routePreviewOutput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => runRoutePreview(cfg, args));
     server.registerTool("lobstack_models", {
-        title: "List gateway models",
-        description: "The models the Lobstack Gateway serves, with capability tier, provider, context window and USD price per " +
+        title: "List Lobstack API models",
+        description: "The models the Lobstack API serves, with capability tier, provider, context window and USD price per " +
             "million input and output tokens. A model the registry cannot price shows a null price, not zero.",
         inputSchema: modelsInput,
         outputSchema: modelsOutput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => runModels(cfg, args));
     server.registerTool("lobstack_chat", {
-        title: "Chat through the gateway",
-        description: "Send a prompt or conversation through the Lobstack Gateway and get the reply plus a receipt: the model that " +
+        title: "Chat through the Lobstack API",
+        description: "Send a prompt or conversation through the Lobstack API and get the reply plus a receipt: the model that " +
             'actually served it, token counts, USD cost, and any saving with the reason it may be claimed. Model "auto" ' +
             "(the default) lets the router pick the cheapest model that can handle the prompt. This call spends money " +
             "against the configured key's allowance.",
@@ -95,7 +95,7 @@ export function createServer(options = {}) {
     }, async (args) => runChat(cfg, args));
     server.registerTool("lobstack_spend", {
         title: "Read spend and usage",
-        description: "What this organization has spent through the gateway over a range, broken down by day, model, key or agent, " +
+        description: "What this organization has spent through the Lobstack API over a range, broken down by day, model, key or agent, " +
             "with request counts, tokens, error counts and latency percentiles. Requires an API key with the usage:read " +
             "scope. Reports how many requests could not be priced, because a total that includes them is a floor.",
         inputSchema: spendInput,

package/dist/tools/spend.d.ts

@@ -17,15 +17,18 @@
  * `truncated` — the endpoint pages to a cap. When it binds, the sums are a
  * floor for a second, independent reason.
  *
- * WHAT THIS TOOL DOES NOT REPORT
+ * WHAT THIS TOOL DOES NOT REPORT (YET)
  *
- * A savings total. `/api/v1/usage` does not compute one — its summary carries
- * requests, tokens, cost, error rate and latency percentiles, and nothing else.
- * Adding up per-call savings client-side would require the baselines, which are
- * not in this response, and printing a number derived from a rate card we hold
- * a copy of is the failure mode this whole product argues against. Savings are
- * reported per call, by lobstack_chat, where the Gateway sends them with the
- * reason attached.
+ * A savings total. `/api/v1/usage` now computes one, server-side from the
+ * priced ledger, as a top-level `savings` object split in two and never
+ * summed: `named` (a measured saving against a model the caller asked for) and
+ * `plan_ceiling` (a counterfactual against the priciest model the plan allows,
+ * when the caller sent `auto`). `savings` is null when the ledger could not be
+ * read. This tool does not read it yet; if it ever does, the two blocks must
+ * stay separate and `plan_ceiling` must be labelled as a counterfactual. What
+ * it must never do is add up per-call savings client-side from a rate card we
+ * hold a copy of. Per-call savings are reported by lobstack_chat, where the
+ * API sends them with the reason attached.
  */
 import { z } from "zod";
 import type { Config } from "../config.js";

package/dist/tools/spend.js

@@ -17,15 +17,18 @@
  * `truncated` — the endpoint pages to a cap. When it binds, the sums are a
  * floor for a second, independent reason.
  *
- * WHAT THIS TOOL DOES NOT REPORT
+ * WHAT THIS TOOL DOES NOT REPORT (YET)
  *
- * A savings total. `/api/v1/usage` does not compute one — its summary carries
- * requests, tokens, cost, error rate and latency percentiles, and nothing else.
- * Adding up per-call savings client-side would require the baselines, which are
- * not in this response, and printing a number derived from a rate card we hold
- * a copy of is the failure mode this whole product argues against. Savings are
- * reported per call, by lobstack_chat, where the Gateway sends them with the
- * reason attached.
+ * A savings total. `/api/v1/usage` now computes one, server-side from the
+ * priced ledger, as a top-level `savings` object split in two and never
+ * summed: `named` (a measured saving against a model the caller asked for) and
+ * `plan_ceiling` (a counterfactual against the priciest model the plan allows,
+ * when the caller sent `auto`). `savings` is null when the ledger could not be
+ * read. This tool does not read it yet; if it ever does, the two blocks must
+ * stay separate and `plan_ceiling` must be labelled as a counterfactual. What
+ * it must never do is add up per-call savings client-side from a rate card we
+ * hold a copy of. Per-call savings are reported by lobstack_chat, where the
+ * API sends them with the reason attached.
  */
 import { z } from "zod";
 import { apiUrl } from "../config.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lobstack-ai/mcp",
-  "version": "0.1.0",
-  "description": "The Lobstack Gateway as an MCP server: thirty models behind one key, and what each call cost.",
+  "version": "0.1.2",
+  "description": "The Lobstack API as an MCP server: one key across many model providers, and what each call cost.",
   "type": "module",
   "bin": {
     "lobstack-mcp": "./dist/index.js"
@@ -38,7 +38,8 @@
     "anthropic",
     "claude",
     "cursor",
-    "lobstack"
+    "lobstack",
+    "lobstack-api"
   ],
   "license": "MIT",
   "author": "Lobstack",
@@ -49,7 +50,7 @@
   "bugs": {
     "url": "https://github.com/Lobstack-ai/lobstack-mcp/issues"
   },
-  "homepage": "https://github.com/Lobstack-ai/lobstack-mcp#readme",
+  "homepage": "https://www.lobstack.ai/docs/mcp",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.25.76"