SOLWYN
Commands

mcp / mcp-config

The local MCP server, its 33-read and 37-guardrails profiles, authentication, work bounds, and launch descriptor.

solwyn mcp serves Solwyn's operations as tools to any MCP client over stdio. solwyn mcp-config prints the command and arguments a client needs to launch it. solwyn doctor --mcp checks that the wiring works. For how an agent should use the tools, see Agent integration.

mcp

Terminal
solwyn [--project <project>] [--api-url <url>] mcp [--profile read|guardrails]
OptionTypeDefaultPurpose
--profileread | guardrailsguardrailsThe fixed tool surface for this launch.
Contract
Authresolved per tool call, never at startup
Exit codes0 clean shutdown · 1 startup or protocol failure · 2 usage
Transportstdio only; stdout is reserved for JSON-RPC framing

Put the global --project and --api-url before mcp and --profile after it. The output flags (--json, --format, --no-color) are accepted and ignored. The server advertises tools only — no prompts, no resources — and the profile is fixed for the life of the process; no tool argument can change it.

Read tools resolve their credential from the environment (SOLWYN_TOKEN, SOLWYN_API_KEY) or the CLI's credential store on every tool call, and listing tools never touches a credential. The metering tools are different: their project, credential store and login are read once at startup and their key is kept from the first metering call (see What the metering tools read at startup), so restart the server after rotating the stored key, editing .solwyn.env or logging in again. When no login is available, an empty or malformed SOLWYN_API_KEY blocks fallback to the stored API key rather than silently selecting another identity.

Profiles

ProfileToolsUse when
read33 read-only toolsObserve projects, accounts, costs, billing estimates, team access and delivery. The default for setup, mcp-config, doctor --mcp, and the shipped example clients.
guardrailsAll 37, adding budget_check, budget_confirm, budget_check_batch, record_callThe agent makes un-instrumented provider calls itself and must run the check → confirm loop. The default for bare solwyn mcp.

Recommend --profile read unless the agent genuinely spends. A tool excluded by the profile is not merely denied — it is never registered, so calling it fails as an unknown tool before any argument, credential, or network is touched. Profiles expose tools; they never grant permissions. A full-scope key does not promise that a future budget decision will allow spend.

The tool catalogue

ToolCLI equivalentMutatesCredential
budget_statusbudget statusnoeither
budget_checkbudget checkyesfull-scope API key
budget_confirmbudget confirmyesfull-scope API key
budget_check_batchbudget check --batchyesAPI key; read-only suffices for recover_only
record_callrecordyesfull-scope API key
get_project_statusstatusnoeither
get_forecastforecastnoeither
get_costscostsnoeither; account=true requires a login
get_cost_totalcosts totalnoeither
list_budget_rulesbudget rules listnoeither; with_last_fired=true requires a login
list_tagstags listnoeither; Team and above
list_tag_valuestags valuesnoeither; Team and above
list_agent_runsruns listnoeither
get_agent_runruns shownoeither
list_alert_eventsalerts listnoeither; account: true requires a login
list_projectsprojects listnologin
get_overviewoverviewnologin
list_cost_eventscosts eventsnoeither
get_cost_baselinecosts baselinenoeither
get_unit_economicscosts unit-economicsnoeither
get_cost_driftcosts driftnoeither
list_priced_modelscosts priced-modelsnoeither
simulate_costscosts simulatenoeither
list_provider_failoversproviders failoversnoeither
list_untracked_surfacesproviders untrackednoeither
list_audit_eventsauditnologin
plan_statusplannologin or API key with account context; no project required
plan_catalogplan listnologin or API key with authenticated user context; no project required
get_whoamiwhoaminoeither; a key returns local context only
get_account_phoneaccount phone shownologin
list_alert_activityalerts activitynologin
list_open_alert_deliveriesalerts pendingnologin
budget_uncountedbudget uncountednoeither
get_account_alertalerts account shownologin; optional with_last_fired
plan_previewplan change --dry-runnologin at any account role; no project required
list_team_membersteam members listnologin at any account role; no project required
list_team_invitesteam invites listnoowner/admin login; no project required

Every read tool is annotated readOnlyHint: true, idempotentHint: true; the four writers carry destructiveHint: true. Tool inputs mirror the CLI flags in snake case — get_costs takes the full shared cost-filter set and from_/to windows, list_tag_values takes key, prefix, limit, cursor, and so on — and every input schema is closed, so an unknown key is rejected as invalid_arguments. The three budget tools' descriptions are generated from the same text as solwyn agent-context, so the MCP guidance and the CLI brief cannot drift apart.

All 33 reads appear in both profiles. The four writers appear only in guardrails; recovery-only batch access still requires that profile. Reads carry destructiveHint: false; writers carry readOnlyHint: false and idempotentHint: false. All tools carry openWorldHint: true because they contact Core. Annotations describe behavior and do not enforce authorization.

plan_preview(tier="team", interval="year") uses a read-only POST, creates no invoice or subscription change, and returns solwyn.plan.preview.v1 with immediate/scheduled mode, dates, signed integer cents, currency and proration lines. An estimate is not a price lock. Cost simulation and opt-in latest-alert lookup also use read-only POSTs.

Billing, team/member writes, account rename and the invitation token workflow remain CLI-only; personal-account recovery is in the dashboard. Rule, channel, project, key and alert writes also remain CLI/dashboard operations.

Selection and authorization

Credentials are chosen by tool class. Metering tools (budget_check, budget_check_batch, budget_confirm, record_call) use only an API key for the launch project: SOLWYN_API_KEY, then the key stored on this computer for that project, never a login, bound once per server (see What the metering tools read at startup). Every other tool resolves its credential fresh on every call and uses SOLWYN_TOKEN, then the stored Solwyn login, then SOLWYN_API_KEY, then the stored API key, so a stored key never hides a login from account tools. SOLWYN_AUTH=project_key skips both logins for those tools and SOLWYN_AUTH=login requires one. A login-only tool refuses an API key; the server never silently switches identities. See Scoped login for the full order.

MCP tools never wait for a browser approval. A tool that needs one returns isError: true with the code approval_required and the approval URL in its hint, for a human to open.

What the metering tools read at startup

When the server starts, without any network call, it reads:

  • the launch project: --project before mcp, else SOLWYN_PROJECT, else .solwyn.env in its working directory (with the same mismatch and account checks as the CLI; see Choosing the project);
  • its environment and working directory, including SOLWYN_API_KEY;
  • which credential store to use: SOLWYN_CREDENTIAL_STORE, else config credential_store, else auto, and SOLWYN_CREDENTIALS_FILE or the default file;
  • which login a project name resolves through: SOLWYN_TOKEN, else the stored login.

Later edits to any of these change nothing until the server restarts, and every attempt to bind the metering tools, retries included, uses only these startup values.

  • Metering tools take no project argument and refuse one. They always spend from the launch project. The first metering call picks the key (SOLWYN_API_KEY, else the key stored for the launch project), checks it with Solwyn, and keeps it; no other key is ever tried. Every later metering request names the project's proj_ id in the Solwyn-Project header, and results include project_id. Once bound, the key is kept even if the login changes.
  • Read tools take an optional project (a name or proj_ id; it replaced project_id in 0.5.0) and default to the launch project. They resolve their credential and project on every call.

If the stored login is replaced, removed or added before the metering tools are bound (logging in again as the same account counts), every metering call returns credentials_changed: The Solwyn login on this computer changed after the server started., hint Restart the server. It never switches logins, projects or keys while it runs. With SOLWYN_TOKEN set, the stored login is ignored for this check.

Restart the MCP server after you rotate the stored key, change SOLWYN_API_KEY, edit .solwyn.env or log in again.

If the launch project and key can't be used (project_mismatch, project_ambiguous, api_key_not_stored, api_key_account_mismatch, credentials_changed, or an expired or revoked key), every later metering call returns that error until the server restarts. For project_mismatch, the hint is addressed to a person: Ask a person to change .solwyn.env if this repo should use another project, or to restart the server with the project it names. Never switch projects to get past a budget limit. Read tools keep working, and get_whoami names the launch project. Project selection does not change key scope, account role or account membership. Core also checks access and plan entitlements.

get_costs(account=true) defaults to project grouping, requires a login and rejects an explicit project; the launch project is irrelevant. Only model, provider, modality and preset/paired custom windows apply in account mode. list_alert_events(account=true) reads account-scope history and ignores project; list_alert_activity reads all projects plus account scope. Roster reads allow any member; invitation listings require owner/admin and preserve expired open rows and delivery statuses. Listing or resending an invitation does not prove email delivery.

MCP 2026-07-28 discovery advertises ttlMs=60000, cacheScope="private"; legacy clients receive the same tools without those fields. Hosts may cache discovery for one minute per launch/profile. Tool results have no cache hint: discovery freshness does not cache credentials, authorize spend or extend reservations.

The result envelope

Every tool returns one typed object, serialized identically into the text content and the structured content of the result:

{"schema":"solwyn.mcp.budget-check.v1","ok":true,"data":{"allowed":false,"reservation_id":null,"denied_by_period":"monthly","call_id":"…","recorded":{"status":"ingested"}},"error":null}
{"schema":"solwyn.mcp.budget-status.v1","ok":false,"data":null,"error":{"code":"authentication_required","message":"Solwyn authentication is required.","hint":"Configure an API key or run solwyn login, then retry.","status_code":null}}

isError is set exactly when ok is false. Two consequences matter for a model:

  • A budget denial is a successful decision, not an error: ok: true, isError: false, data.allowed: false. Fail-open is allowed: true with reservation_id: null, and a stopped run is an ordinary denial. Denials record attribution by default unless no_record is set.

  • Error messages are fixed strings. A Solwyn API rejection keeps its code when the code is on the CLI's allowlist (for example upgrade_required, quota_exceeded, project_limit_reached, approval_required, approval_denied or cli_credential_expired), so an agent can tell which limit it hit. The message is a fixed CLI-owned sentence for that code, filled only from validated structured fields such as a quota count or the required plan tier. The server's own message text is never relayed. The code is chosen in this order:

    1. approval_limit_reached keeps its code, even on a 429.
    2. Any other 429 becomes rate_limited.
    3. account_membership_revoked and the allowlisted codes keep their code.
    4. Any other code becomes service_busy on a 503, authentication_failed on a 401, forbidden on a 403, and api_error otherwise, each with a fixed generic message. Validation hints name a schema path, never an input value. Tracebacks, raw server text, secrets, and the names of unknown methods are never returned.

An HTTP-200 result whose attribution recording was rejected or failed is downgraded to ok: false with a recording_* code while keeping data, so a settled reservation is never mistaken for an unsettled one.

Bounded work

Every call runs inside fixed limits. There is no per-session cap and no option to change these:

LimitValue
Useful-work deadline30 seconds
Pages fetched for a paginating tool10
Aggregate HTTP response bytes1 MiB
Encoded request body4 MiB
Complete tool result2 MiB
Batch size1 to 32 checks
Continuation cursor4,096 characters

Hitting a limit returns an ordinary tool error — operation_deadline, page_limit, response_size_limit, result_size_limit — but never loses identities. An oversized result is replaced by the error plus a compact recovery object: for a mutating tool, the operation id, per-item states, reservation and call ids, and the settlement and recording status; for a read, the cursor to resume from. Cancellation or a closed stdin stops future requests and pages but cannot undo a request the API already admitted.

budget_check_batch extends this with a durable journal: supply a caller-retained UUIDv7 operation_id before calling, and if the reply is lost, call again with recover_only: true to read the outcome without admitting anything new. Reservations expire 300 seconds after they were checked; journal entries expire after 24 hours.

Cursor listings retain their first unread cursor on a later-page error. This bounded MCP behavior differs from CLI --all, which emits no partial success. See bounded work and journal recovery, observed media recovery, and service capacity and uncertain writes.

mcp-config

Print the command and argument array a client should use to launch the server. It writes no files, reads no credential, and makes no network call.

Terminal
solwyn [--project <project>] [--api-url <url>] [--json] mcp-config [--executable <path>] [--profile read|guardrails]
OptionTypeDefaultPurpose
--executablepaththis installation's solwynAn explicit installed executable. Never a PATH lookup.
--profileread | guardrailsreadProfile to bake into the descriptor.
Contract
Authnone; no credential lookup
Exit codes0 descriptor emitted · 1 executable unavailable · 2 usage
JSON schemasolwyn.mcp-config.v1
Terminal
$ solwyn --json --project checkout-bot mcp-config
{"schema":"solwyn.mcp-config.v1","command":"/absolute/path/to/solwyn","args":["--project","checkout-bot","--api-url","https://api.solwyn.ai","mcp","--profile","read"],"env_vars":["SOLWYN_TOKEN","SOLWYN_API_KEY","SOLWYN_AUTH","SOLWYN_API_URL","SOLWYN_CREDENTIAL_STORE","SOLWYN_CREDENTIALS_FILE","XDG_DATA_HOME","XDG_CONFIG_HOME","XDG_STATE_HOME"]}

The descriptor is host-neutral; adapt command, args and env_vars to your client's configuration format. It never contains a secret. env_vars names (never values) the environment variables a host should pass through to the server; Codex needs them in its env_vars key. Supply credentials with solwyn login or the host's environment. See Agent integration for ready-to-paste examples and doctor --mcp to verify the result.

  • Agent integration — the one rule, the guardrail loop, client wiring, and diagnostics
  • budget — every option the budget tools mirror, including recovery after a lost reply
  • doctor — --mcp launches the server in isolation and checks discovery and a read

On this page