Skip to main content
Glama
Sign In
@lobstack/mcp

@lobstack/mcp

Official
by Lobstack-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

@lobstack-ai/mcp

An MCP server for the Lobstack API. One API key reaches chat models from Anthropic, OpenAI, Google and xAI, plus embeddings and web search, 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.

Try it without a key

lobstack_route_preview is unauthenticated. Install the server with no credential at all and an agent can still ask "which model would this prompt go to, and what would it cost":

npx -y @lobstack-ai/mcp

Add it to your client using one of the blocks below, leave env out, and ask:

Preview how Lobstack would route: "summarise this changelog into three bullets"

lobstack_models also works without a key on www.lobstack.ai. The other four tools need one, minted in Console → API keys.

Related MCP server: Kyma API MCP Server

Install

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "lobstack": {
      "command": "npx",
      "args": ["-y", "@lobstack-ai/mcp"],
      "env": {
        "LOBSTACK_API_KEY": "lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. The six lobstack_* tools appear under the tools menu.

Cursor

~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

{
  "mcpServers": {
    "lobstack": {
      "command": "npx",
      "args": ["-y", "@lobstack-ai/mcp"],
      "env": {
        "LOBSTACK_API_KEY": "lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code

claude mcp add lobstack --env LOBSTACK_API_KEY=lsk_live_... -- npx -y @lobstack-ai/mcp

Zed

In settings.json, under context_servers:

{
  "context_servers": {
    "lobstack": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@lobstack-ai/mcp"],
      "env": {
        "LOBSTACK_API_KEY": "lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Tools

Tool

Costs money

Needs a key

Endpoint

lobstack_route_preview

No

No

POST /api/gateway/v1/route-preview

lobstack_models

No

No

GET /api/gateway/v1/models

lobstack_chat

Yes, per token

inference scope

POST /api/gateway/v1/chat/completions

lobstack_embeddings

Yes, per input token

inference scope

POST /api/gateway/v1/embeddings

lobstack_web_search

Yes, per search

inference scope

POST /api/gateway/v1/search

lobstack_spend

No

usage:read scope

GET /api/v1/usage

The intended order for an agent: lobstack_route_preview with the prompt it is about to send (free), then lobstack_chat. lobstack_models when it needs a model id or a rate. lobstack_spend to check what has already been spent.

Every tool description states its cost, what it needs, when to use a sibling instead, and how to read its output, and every parameter has a description with its range, default and an example. The annotations are accurate: the three spending tools are readOnlyHint: false, idempotentHint: false (a repeat is billed again), the other three are read-only and idempotent, and none is destructive.

There is no tool for creating, rotating or revoking API keys. That stays in the Console. There is also no "who am I" tool, because no key-authenticated endpoint reports it; the allowance comes back as quota on every spending call and as credit on lobstack_spend.

There is no streaming switch either. The server streams from the API (that is how the chat receipt arrives), but an MCP tool result is one message, so the agent gets the whole answer at once.

lobstack_route_preview

Scores a prompt against the same router the paid path uses and reports the model that would serve it, the capability tier, the complexity score, and the estimated cost. Runs no inference and spends nothing. Needs no API key. Rate-limited to ten a minute per IP address.

argument

type

notes

prompt

string, required

The prompt you are about to send. 1 to 8000 characters. Scored, never sent to a model.

requested_model

string

A chat model id to compare against. Default auto. An unknown id is a 400.

plan_tier

enum

free, byok, developer, studio, scale, appsumo_1..3, or the legacy starter, pro, performance, enterprise. Default pro. Sets the ceiling the router may reach.

expected_output_tokens

integer 1 to 200000

Default half the prompt's estimated tokens, at least 64.

conversation_length

integer ≥ 0

Messages already in the conversation. Default 0.

Token counts are estimates, roughly four characters per token. The billed figure always comes from the provider's own usage block on the real request, and the tool says so in every answer. A baseline is returned only when you named a model and the router moved away from it; on auto it is null.

lobstack_models

The catalogue: model id, type (chat or embedding), label, tier, provider, context window, embedding dimensions, and USD per million input and output tokens.

argument

type

notes

type

chat | embedding

Default both: chat rows first, embedding rows last.

tier

router | nano | small | standard | premium | flagship

Chat models only.

provider

anthropic | openai | google | xai | lobstack

lobstack is the auto row.

The first entry is auto, which is Nex 1, the router. It carries tier: "router" and a null price on purpose: its cost is whichever model it picks. It is not counted in unpriced_count. Every other null price is a gap: the registry cannot price that model, and it renders as —, not as free. Embedding rows have an output price of 0 because embeddings have no output tokens. The full catalogue is also public at https://www.lobstack.ai/models.

lobstack_chat

Sends a prompt or a conversation and returns the reply plus the receipt. Costs money on input and output tokens.

argument

type

notes

prompt

string

A single user message. Use this or messages.

messages

array

{ role, content }, oldest first, role system/user/assistant. Use this or prompt.

model

string

Default auto, which is Nex 1, the router. Any chat id from lobstack_models.

system

string

Sent first, ahead of the conversation.

max_tokens

integer 1 to 200000

Default 4096 (8192 for OpenAI GPT-5 and o-series models). Caps the worst-case cost.

temperature

number 0 to 2

Not sent unless set. Some models do not accept it; dropped_params says when it was dropped.

client_tag

string

Who the call is for, for cost attribution. See Client tags.

The reply and the receipt come back as two separate content blocks, so whatever consumes the answer does not get a price line concatenated onto it. The structured result carries:

{
  "text": "...",
  "model": { "requested": "claude-opus-5", "served": "claude-haiku-4-5", "routed": true },
  "usage": { "prompt_tokens": 400, "completion_tokens": 140, "total_tokens": 540 },
  "receipt": {
    "request_id": "req_...",
    "cost_usd": 0.0011,
    "cost_display": "$0.001100",
    "priced": true,
    "savings": {
      "amount_usd": 0.0044,
      "label": "saved",
      "named": true,
      "baseline_model": "claude-opus-5",
      "baseline_reason": "named"
    }
  },
  "quota": { "meter": "spend", "remaining_usd": 16.75 },
  "dropped_params": []
}

lobstack_embeddings

Vectors for text, from OpenAI text-embedding-3-small (default, 1536 dimensions) or text-embedding-3-large (3072). Costs money on input tokens. Not routed: auto means the small model, because vectors from different models cannot be compared.

argument

type

notes

input

string, or array of 1 to 64 strings

Required. Each string is embedded separately and returned in the same order.

model

auto | text-embedding-3-small | text-embedding-3-large

Default the small model.

dimensions

integer

Shorten each vector. At most the model's own length; refused before any call if larger.

client_tag

string

See Client tags.

The API takes up to 2,048 inputs per call. This tool takes 64, because every vector comes back into the agent's context. For bulk indexing, call the HTTP API directly. The receipt is read from the x-lobstack-* headers: an empty x-lobstack-cost-usd is reported as cost_usd: null, never 0.

lobstack_web_search

Web results from Brave Search's index through the Lobstack API: title, URL and a plain-text snippet each. Costs money, per search, not per token or per result: Brave's published price inside your plan's included usage and on the Free plan's credit, and that times the Lobstack rate past it. The current figure is on https://www.lobstack.ai/docs/gateway/search.

argument

type

notes

query

string, required

1 to 400 characters after trimming. Lobstack logs its length, not its text.

count

integer 1 to 10

Default 5. Fewer may come back.

client_tag

string

See Client tags.

The same query and count from the same organization within ten minutes may be answered from a short cache: receipt.cache is "hit" and the cost is 0. A 402 or 503 means search will not run on Lobstack right now; the error text tells the agent to use another search rather than retry in a loop.

lobstack_spend

What the organization has spent. Read-only and free. Requires a key holding the usage:read scope.

argument

type

notes

range

month | 1d | 7d | 14d | 30d | 90d | 365d

Default 7d. month is the UTC calendar month to date, the Console's default. A window longer than the plan's history starts where the history does, and history.limited says so.

group_by

day | model | key | agent | provider | mode | client | app

Default model. client is the client tag; mode splits managed from your own provider key; app is the calling application.

client

string

Only calls for this client tag. __untagged__ selects calls with none.

Use it for budget monitoring (how much of the month is gone, which model or key drives it) and for cost attribution (spend per client tag or per agent).

The total is the Console's figure. /api/v1/usage returns two totals from two tables: spend.cost_usd, from the billing ledger that the allowance and invoices are read from and that the Console's Spend shows, and summary.cost_usd, the request trace's own copy of each price, kept for older callers. They are written separately and can disagree. This tool reports spend.cost_usd (and each group's ledger_cost_usd) as cost_usd, with cost_source: "ledger". Only when the ledger figure is null or missing does it fall back to summary.cost_usd, set cost_source: "trace", and say so in the output.

is_floor means "at least". Unpriced rows sum as zero, the only arithmetic available, so a total that includes one is a lower bound. So is a total whose read hit the row cap. When is_floor is true, report the figure as "at least $X", never as the bill.

Routing savings are two figures, never one. When the API sends savings, the tool shows named (saved on models you asked for, measured) and plan_ceiling (what auto requests would have cost on the best model your plan allows: a comparison, not a saving) on separate lines. It never adds them together, and it never computes a saving client-side from a copy of the rate card.

credit is passed through from the API: on a spend-metered plan, the Free plan's weekly credit, any welcome credit and when it expires, included usage this period, and purchased credit left.

Client tags

lobstack_chat, lobstack_embeddings and lobstack_web_search take an optional client_tag: who the call is for, sent as x-lobstack-client-tag. 1 to 64 characters of lowercase a-z, 0-9, ., _ or -, starting with a letter or digit. Read it back with lobstack_spend group_by: "client". A tag set on the API key itself wins over the argument. A client with a hard monthly budget that is spent refuses the call with 402 CLIENT_BUDGET_EXHAUSTED.

Errors

A failed call returns isError: true with the API's message, then a line naming the error class, the HTTP status, the error_code when there is one, and whether a retry can help:

monthly allowance exhausted

Error class: quota (HTTP 402, ALLOWANCE_EXHAUSTED). Do not retry: the allowance or a budget is spent until it is raised or resets.
The plan's included usage and credit are used. Top up or upgrade in Console → Billing.
Request id: 8f2b1e0c-...

Class

Status

Retry?

auth

401, 403

No. Fix the key or its scopes.

quota

402, 429

402 no. 429 yes, after Retry-After.

validation

400, 409, 422

No. Fix the arguments.

provider

502, 503, other 5xx

Yes, with backoff, except SEARCH_UNAVAILABLE, MANAGED_DISABLED and PROVIDER_ACCOUNT_UNAVAILABLE: use a fallback.

timeout

408, 504

Yes. The first attempt may have completed and been billed.

internal

500

Once, then report the request id.

The full list is at https://www.lobstack.ai/docs/gateway/errors.

Two rules about the numbers

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.

baseline_reason decides what a saving may be called.

  • named — you asked for a model and got something cheaper. Like-for-like, and the only case labelled saved.

  • plan_ceiling — you sent auto, so the comparison is against the most expensive model your plan allows. Real, and not something you asked for: labelled vs ceiling, with the baseline model named next to it.

  • missing — treated as unnamed. A receipt that does not say where its baseline came from does not get the flattering reading.

Configuration

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

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 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.

The key

LOBSTACK_API_KEY is read from this process's environment and from nowhere else. No tool takes a key, a token, or a base URL as an argument: a base URL that can arrive as a tool argument is a credential that can be redirected by whoever wrote the argument. Error text is scrubbed on the way out, including text that came back from upstream.

This process holds a live credential for as long as your MCP client runs. The dependency list is the MCP SDK, zod, and what those two bring with them.

Development

npm install
npm run build
npm test

The tests run a real MCP client against the server over an in-memory transport, and the server against a fake gateway over real HTTP. The fake gateway writes its SSE stream in two pieces with the cut landing mid-frame, serves a model with no price, and refuses any request to /route-preview that arrives carrying an Authorization header — so a client that leaks a credential to a public endpoint fails a test rather than shipping.

Publishing to the MCP Registry

server.json is what the Official MCP Registry stores. PulseMCP lists a server once that registry accepts it, so this is the publish that puts @lobstack-ai/mcp there. The registry stores metadata only. .github/workflows/release.yml publishes the npm tarball when a v* tag is pushed, and the registry then reads mcpName out of that tarball.

The registry name is io.github.Lobstack-ai/lobstack-mcp in both places GitHub authentication checks: name in server.json, and mcpName in package.json. A GitHub login can only publish under io.github.Lobstack-ai/. version in server.json, the npm package entry inside it, and package.json are the same string. The package is @lobstack-ai/mcp on https://registry.npmjs.org, stdio, invoked as npx -y @lobstack-ai/mcp. LOBSTACK_API_KEY is optional (isRequired: false, isSecret: true) because lobstack_route_preview runs with no key.

One click

.github/workflows/publish-mcp.yml runs when a GitHub Release is published, and from the Actions tab with Run workflow. It refuses to publish when the versions disagree, waits until that version is on npm, then runs:

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
./mcp-publisher login github-oidc
./mcp-publisher publish

login github-oidc is why the workflow has id-token: write. There is no registry token to store.

On a laptop the publisher commands are the same, with the device-code login in place of OIDC:

./mcp-publisher login github
./mcp-publisher publish

The registry reads mcpName from the tarball already on npm, not from this checkout. 0.1.3 was published before mcpName existed, and npm will not accept a second upload of that version, so the first publish that succeeds is the next one: bump package.json and server.json together, push the v* tag, then publish the GitHub Release.

Licence

MIT

Available Tools

4 tools
lobstack_chatChat through the gatewayA

Send a prompt or conversation through the Lobstack Gateway 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.

NameRequiredDescriptionDefault
modelNoLobstack model key, e.g. "claude-sonnet-5". Defaults to "auto", which lets Token Intelligence pick the cheapest model that can handle the prompt. lobstack_models lists the keys.
promptNoA single user message. Use this or `messages`, not both.
systemNoSystem prompt, prepended to the conversation.
messagesNoA full conversation, OpenAI-shaped. Use this or `prompt`, not both.
max_tokensNoCap on the reply length.
temperatureNoSampling temperature. Some served models do not accept it; the receipt says when it was dropped.

Output Schema

NameRequiredDescription
textYesThe assistant's reply.
modelYes
quotaYesAllowance remaining, as the gateway reported it.
usageYes
receiptYesNull when the endpoint sent no receipt at all.
dropped_paramsYes

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already disclose openWorldHint, non-readonly, non-idempotent, non-destructive. The description earns credit beyond that by stating it charges the configured key, that the receipt reports the actually-served model and any saving/claim reason, and that temperature may be silently dropped for some models.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no wasted words, and the core action plus the cost consequence are front-loaded. Slightly dense but each sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a chat/completion call with an output schema, the agent has the action, the money-spend warning, the routing behavior, and receipt contents. The main omission is explicit guidance to preview with lobstack_route_preview before spending.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so model, prompt, system, messages, max_tokens and temperature are all already documented in the schema. The description restates the auto default but adds no syntax or format detail beyond what the schema carries; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb (Send) plus resource (prompt/conversation) and adds the scope of the return (reply + receipt with model, tokens, cost, savings). The function is unmistakable, but the description never names a sibling like lobstack_route_preview to sharpen the boundary, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It flags a real usage consideration (this call spends money) and explains the auto default, but gives no explicit when/when-not guidance and does not route the agent to lobstack_route_preview for a cost-free preview. Usage is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lobstack_modelsList gateway modelsA
Read-onlyIdempotent

The models the Lobstack Gateway 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.

NameRequiredDescriptionDefault
tierNoOnly models in this capability tier. Token Intelligence walks these from cheapest upward.
providerNoOnly models from this provider, e.g. "anthropic", "openai", "google".

Output Schema

NameRequiredDescription
countYes
modelsYes
unpriced_countYesModels the registry could not price. Their prices are null, not zero.

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral detail beyond that: an unpriceable model yields a null price rather than zero, which prevents an agent from misreading the data. It stops short of describing pagination or ordering of the results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both load-bearing: the first states the resource and its fields up front, the second anticipates a likely misreading of the output. No filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-format explanation is not required, and the description already sketches the payload. With both parameters fully described in the schema and annotations covering behavior, the definition is complete enough to invoke correctly; only filtering workflow guidance is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both the tier enum and provider filter are fully documented in the schema, making 3 the baseline. The description mentions tier and provider only as returned fields, not as filter semantics, so it adds nothing beyond the schema for parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource ('the models the Lobstack Gateway serves') and enumerates the returned fields (capability tier, provider, context window, USD price), so an agent knows exactly what this tool produces. It is unambiguous, though it never explicitly names a verb like 'list' and does not differentiate itself from siblings such as lobstack_route_preview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to call this versus the siblings (lobstack_route_preview, lobstack_chat, lobstack_spend), nor any prerequisite or sequencing advice. The only contextual hint is embedded in the tier parameter schema ('Token Intelligence walks these from cheapest upward'), which is not usage guidance for the tool itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lobstack_route_previewPreview routing and costA
Read-onlyIdempotent

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 figure comes from the provider's usage block on the real call.

NameRequiredDescriptionDefault
promptYesThe prompt to score. Scored, never sent to a model.
plan_tierNoPlan id, which sets the ceiling the router may reach. Defaults to the pro ceiling.
requested_modelNoA model key to compare against, e.g. "claude-opus-5". Defaults to "auto".
conversation_lengthNoMessages already in the conversation; it feeds the complexity score.
expected_output_tokensNoHow long the reply is expected to be. Defaults to half the prompt, which is the common chat ratio.

Output Schema

NameRequiredDescription
tierYes
reasonYes
routedYesTrue when the router would serve something other than what was requested.
baselineYesOnly present when a model was named and the router moved away from it — the "named" case.
providerYes
estimatedYesAlways true. These are estimates, not a bill.
complexityYes
served_labelYes
served_modelYesThe model this prompt would actually be routed to.
token_estimateYes
requested_modelYes
estimated_cost_usdYesNull when the registry cannot price the model.
estimated_cost_displayYes
managed_key_configuredYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them by disclosing that it runs no inference, spends nothing, and requires no API key. It also flags that token counts are estimates and that the authoritative billed figure comes from the provider's usage block on the real call, which is exactly the caveat an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, zero filler, with the cost/safety guarantee and the keyless property front-loaded before the usage routing. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description still covers the safety profile, key requirement, cost semantics, and estimate-vs-billed distinction. Nothing an agent needs in order to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter already carries its own explanation including defaults for plan_tier and requested_model. The description adds only the estimate caveat around token accounting, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Score a prompt and report which model the Lobstack router would serve it with') plus the second output dimension, cost. It explicitly contrasts with the sibling that actually performs inference, lobstack_chat, so an agent can route between them without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives two concrete selection conditions: pick a model before calling lobstack_chat, and demonstrate gateway behavior on a keyless machine. It names the alternative explicitly and the circumstance that picks it, so no inference about when to invoke this tool is required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lobstack_spendRead spend and usageA
Read-onlyIdempotent

What this organization has spent through the gateway 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.

NameRequiredDescriptionDefault
rangeNoHow far back to look. Defaults to 7d.
group_byNoHow to break the total down. Defaults to model.

Output Schema

NameRequiredDescription
rangeYes
groupsYes
enabledYesFalse when request tracing is not enabled on this deployment.
messageYes
summaryYes
group_byYes
is_floorYesTrue when some rows were unpriced or the row cap bound, so the totals are a lower bound, not a total.

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description is not obligated to restate that. It adds genuinely useful disclosure beyond the annotations: the usage:read scope requirement and the caveat that unpriced requests make any total a floor. It stops short of noting rate limits or freshness/caching behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler; the core capability is front-loaded and the auth requirement and pricing caveat follow in priority order. The first sentence is long and clause-dense, but every clause carries information an agent would otherwise have to infer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the bounded range enum removes pagination concerns. The description covers scope, auth, and the pricing-floor caveat, but omits any hint of the consuming context (e.g. budget monitoring vs. cost attribution) that would complete the picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are enum-constrained with documented defaults, so the schema already carries the parameter meaning. The description's 'over a range' and 'broken down by day, model, key or agent' mirror the enums without adding format or default detail beyond them, which is the baseline-3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('what this organization has spent through the gateway over a range') and enumerates the exact breakdown dimensions (day, model, key, agent) plus the metrics returned. No sibling (route_preview, models, chat) does spend reporting, so an agent can route to this tool without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied by the spend-reporting framing, and a concrete prerequisite is given ('Requires an API key with the usage:read scope'). However, there is no explicit when-to-use/when-not guidance and no alternatives are named, so routing between this and other tools is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedlobstack_chat
    • First observedlobstack_models
    • First observedlobstack_route_preview
    • First observedlobstack_spend
Deploy Server
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a clearly distinct concern: route_preview scores/routes without spending, models lists the catalog, chat performs the actual paid call, and spend reports usage. The overlap risk between route_preview and chat is explicitly resolved by descriptions clarifying one runs no inference while the other spends money.

Naming Consistency4/5

All tools share a consistent 'lobstack_' prefix and are snake_case, so they scan as one family. Suffix styles vary though — route_preview is verb_noun while models, chat and spend are bare nouns/verbs — a minor inconsistency but still readable and predictable.

Tool Count4/5

Four tools is on the lean side but each earns its place and maps to a real workflow stage (discover, preview, execute, audit). Slightly thin, though appropriate for a focused gateway server.

Completeness4/5

The surface covers the core lifecycle: model discovery, routing/cost preview, the paid completion call, and spend auditing. Minor gaps exist (e.g. no embeddings, streaming controls, or key/scope management), but agents can accomplish the primary gateway tasks without dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • Kyma API MCP Server

    kyma-api
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables MCP clients to browse a live catalog of 100+ models with pricing, rankings and measured uptime, check credits and spend, and send chat completions through an OAuth-authenticated, per-connection key capped by a spend limit. Read tools are free, and paid calls are priced and approved before any credit is used.
    MIT

  • io.github.0xzr/freellmpool

    kerstinc7303
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables MCP clients to discover and use pooled free LLM chat routes and models across multiple providers through an OpenAI-compatible gateway, with automatic failover and keyless operation when available. It supports routing for coding agents and other tools without requiring separate provider integrations.
    -

  • io.github.0xzr/freellmpool

    peterkaraca7006
    F
    license
    Not graded
    quality
    A
    maintenance
    Exposes an MCP interface that lets agents route chat requests across a pooled catalog of free LLM provider routes through a single OpenAI-compatible endpoint, with automatic failover, usage tracking, and keyless start when an enabled route is available. It also lets clients query live capacity and provider health, capacity status, and available models without leaving the agent workflow.
    -