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
solwyn [--project <project>] [--api-url <url>] mcp [--profile read|guardrails]| Option | Type | Default | Purpose |
|---|---|---|---|
--profile | read | guardrails | guardrails | The fixed tool surface for this launch. |
| Contract | |
|---|---|
| Auth | resolved per tool call, never at startup |
| Exit codes | 0 clean shutdown · 1 startup or protocol failure · 2 usage |
| Transport | stdio 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
| Profile | Tools | Use when |
|---|---|---|
read | 33 read-only tools | Observe projects, accounts, costs, billing estimates, team access and delivery. The default for setup, mcp-config, doctor --mcp, and the shipped example clients. |
guardrails | All 37, adding budget_check, budget_confirm, budget_check_batch, record_call | The 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
| Tool | CLI equivalent | Mutates | Credential |
|---|---|---|---|
budget_status | budget status | no | either |
budget_check | budget check | yes | full-scope API key |
budget_confirm | budget confirm | yes | full-scope API key |
budget_check_batch | budget check --batch | yes | API key; read-only suffices for recover_only |
record_call | record | yes | full-scope API key |
get_project_status | status | no | either |
get_forecast | forecast | no | either |
get_costs | costs | no | either; account=true requires a login |
get_cost_total | costs total | no | either |
list_budget_rules | budget rules list | no | either; with_last_fired=true requires a login |
list_tags | tags list | no | either; Team and above |
list_tag_values | tags values | no | either; Team and above |
list_agent_runs | runs list | no | either |
get_agent_run | runs show | no | either |
list_alert_events | alerts list | no | either; account: true requires a login |
list_projects | projects list | no | login |
get_overview | overview | no | login |
list_cost_events | costs events | no | either |
get_cost_baseline | costs baseline | no | either |
get_unit_economics | costs unit-economics | no | either |
get_cost_drift | costs drift | no | either |
list_priced_models | costs priced-models | no | either |
simulate_costs | costs simulate | no | either |
list_provider_failovers | providers failovers | no | either |
list_untracked_surfaces | providers untracked | no | either |
list_audit_events | audit | no | login |
plan_status | plan | no | login or API key with account context; no project required |
plan_catalog | plan list | no | login or API key with authenticated user context; no project required |
get_whoami | whoami | no | either; a key returns local context only |
get_account_phone | account phone show | no | login |
list_alert_activity | alerts activity | no | login |
list_open_alert_deliveries | alerts pending | no | login |
budget_uncounted | budget uncounted | no | either |
get_account_alert | alerts account show | no | login; optional with_last_fired |
plan_preview | plan change --dry-run | no | login at any account role; no project required |
list_team_members | team members list | no | login at any account role; no project required |
list_team_invites | team invites list | no | owner/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:
--projectbeforemcp, elseSOLWYN_PROJECT, else.solwyn.envin 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 configcredential_store, elseauto, andSOLWYN_CREDENTIALS_FILEor 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'sproj_id in theSolwyn-Projectheader, and results includeproject_id. Once bound, the key is kept even if the login changes. - Read tools take an optional
project(a name orproj_id; it replacedproject_idin 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 isallowed: truewithreservation_id: null, and a stopped run is an ordinary denial. Denials record attribution by default unlessno_recordis 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_deniedorcli_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:approval_limit_reachedkeeps its code, even on a429.- Any other
429becomesrate_limited. account_membership_revokedand the allowlisted codes keep their code.- Any other code becomes
service_busyon a503,authentication_failedon a401,forbiddenon a403, andapi_errorotherwise, 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:
| Limit | Value |
|---|---|
| Useful-work deadline | 30 seconds |
| Pages fetched for a paginating tool | 10 |
| Aggregate HTTP response bytes | 1 MiB |
| Encoded request body | 4 MiB |
| Complete tool result | 2 MiB |
| Batch size | 1 to 32 checks |
| Continuation cursor | 4,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.
solwyn [--project <project>] [--api-url <url>] [--json] mcp-config [--executable <path>] [--profile read|guardrails]| Option | Type | Default | Purpose |
|---|---|---|---|
--executable | path | this installation's solwyn | An explicit installed executable. Never a PATH lookup. |
--profile | read | guardrails | read | Profile to bake into the descriptor. |
| Contract | |
|---|---|
| Auth | none; no credential lookup |
| Exit codes | 0 descriptor emitted · 1 executable unavailable · 2 usage |
| JSON schema | solwyn.mcp-config.v1 |
$ 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.
Related
- Agent integration — the one rule, the guardrail loop, client wiring, and diagnostics
budget— every option the budget tools mirror, including recovery after a lost replydoctor—--mcplaunches the server in isolation and checks discovery and a read