Wiele runs a remote MCP server. It exposes the CLI's remote commands as tools: organizations, workspaces, files, history, copies, merges, conflicts, access, retention and billing. Results carry the same data as the CLI prints with --json.
| Endpoint | https://api.wiele.io/mcp |
| Transport | Streamable HTTP, POST only, JSON responses, no sessions |
| Authentication | Authorization: Bearer TOKEN, where the token is a Wiele session |
| Capabilities | Tools only. No resources or prompts. |
What can connect
Any client that can send a fixed Authorization header: Claude Code, Codex, Cursor and others.
claude.ai and ChatGPT connectors can't connect yet. They need OAuth, and Wiele's MCP server only accepts a bearer token. In those apps, use the CLI through an agent that runs commands instead, such as Claude Code or Codex.
Get a token
The token is a Wiele session. Sign in to a separate session kept in a file, so you can revoke the MCP token without signing out the CLI:
mkdir -m 700 ~/.wiele-mcp
wiele login --credential-file ~/.wiele-mcp/session.json
export WIELE_MCP_TOKEN="$(jq -r .credential ~/.wiele-mcp/session.json)"
The configurations below read the token from WIELE_MCP_TOKEN, which keeps it out of config files where they allow it. Start the client from a shell where the variable is set.
A session lasts 7 days from its last refresh, and every MCP request refreshes it at most once a day. A token in regular use keeps working until you revoke it.
Claude Code
claude mcp add --transport http --scope user wiele https://api.wiele.io/mcp \
--header "Authorization: Bearer $WIELE_MCP_TOKEN"
The shell expands the variable, so ~/.claude.json stores the token itself. To keep it out of that file, add the server to a .mcp.json instead. Claude Code expands ${VAR} in headers when it starts:
{
"mcpServers": {
"wiele": {
"type": "http",
"url": "https://api.wiele.io/mcp",
"headers": { "Authorization": "Bearer ${WIELE_MCP_TOKEN}" }
}
}
}
Check it with claude mcp get wiele. Remove it with claude mcp remove wiele.
Codex
In ~/.codex/config.toml, or .codex/config.toml in a trusted project:
[mcp_servers.wiele]
url = "https://api.wiele.io/mcp"
bearer_token_env_var = "WIELE_MCP_TOKEN"
tool_timeout_sec = 150
codex mcp add wiele --url https://api.wiele.io/mcp --bearer-token-env-var WIELE_MCP_TOKEN writes the same entry without the timeout. Codex stops a tool call after 60 seconds by default, and some Wiele tools wait up to 120 seconds, so raise tool_timeout_sec or pass a smaller waitMs.
Cursor
In ~/.cursor/mcp.json, or .cursor/mcp.json in a project:
{
"mcpServers": {
"wiele": {
"url": "https://api.wiele.io/mcp",
"headers": { "Authorization": "Bearer ${env:WIELE_MCP_TOKEN}" }
}
}
}
Cursor reads ${env:NAME} from its own environment. If it started before you exported the variable, quit it and start it from that shell.
Other clients
Point the client at https://api.wiele.io/mcp and send Authorization: Bearer TOKEN on every request. The server supports MCP protocol versions 2025-03-26, 2025-06-18, 2025-11-25 and 2026-07-28. The server refuses requests from browsers, which send an Origin header.
Revoke a token
wiele auth logout --credential-file ~/.wiele-mcp/session.json
The next request with that token fails with 401. The CLI's own session keeps working. Remove the server from each client too.
The token has your account's full power
There are no scoped or read-only tokens yet. A client holding the token can do everything you can: read every workspace you see, push, merge, invite and remove members, change retention, prune versions and start billing changes.
- Keep the token out of shared files. Never commit a
.mcp.jsonorconfig.tomlthat contains it, and never paste it into a chat. - Use a separate session for MCP, as above, so revoking it affects nothing else.
- Turn on your client's confirmation prompts for tools that change data. Each tool says whether it reads, adds or changes data.
How tools behave
organizationis required on most tools. There's no default organization over MCP.workspacetakes an ID, slug or name, andpathalso acceptsWORKSPACE:/path.branchdefaults tomain.- Tools that change something take an optional
idempotencyKey(a UUIDv7). Without one the server generates a key and returns it in the result's_metaunderio.wiele/idempotencyKey. Call again with the same key to retry safely. - Tools that start server work take
waitMs: 30,000 by default, at most 120,000.0returns at once. A wait that runs out fails withOPERATION_PENDING; call again with the same key, or check withoperation_show. - Merge drafts travel as JSON.
conflict_listreturns adraft; pass it toconflict_showandconflict_resolve, then tobranch_merge_approveasapproval. - Failures come back as tool results with
isError: trueand{ error: { code, message, retryable, nextActions } }. The codes are the same as the CLI's; see error codes.
Limits
- Request bodies up to 1 MiB.
path_readreturns file content inline up to 1 MiB, and folder contents up to 768 KiB per page with 256 KiB per file.file_readreturns text inline up to 64 KiB. Larger files come back as a short-lived signed download URL.path_writechanges up to 100 paths, 512 KiB per file.conflict_showshows a text diff only when both sides are 64 KiB or less.
What stays in the CLI
Anything that needs your local disk: fetch, track, status, diff, push, pull, restore, checkout, branch switch, live, sync, daemon, skills install, doctor and sign-in. org logo set is CLI and web only.
Tools
The server lists these tools. We build this table from the server code.
| Tool | Kind | Description |
|---|---|---|
auth_status |
Read | Show the signed-in user, their username and when this connection's session expires. Changes nothing. Requires a signed-in user. |
settings_list |
Read | List the signed-in user's account settings and their version. Changes nothing. Requires a signed-in user. |
settings_get |
Read | Read one account setting (username or branch-name-template), or all settings when key is omitted. Changes nothing. Requires a signed-in user. |
settings_set |
Changes or removes | Change the signed-in user's username or branch-name template, replacing the current value. Fails instead of overwriting when the settings changed concurrently. Affects only the caller's own account. |
settings_reset |
Changes or removes | Reset the signed-in user's username or branch-name template to its default, replacing the current value. Affects only the caller's own account. |
onboarding_status |
Read | Show whether the signed-in user still has to create a first organization or accept invitations, and list their pending invitations. Changes nothing. Requires a signed-in user. |
onboarding_complete |
Adds | Finish the signed-in user's onboarding with exactly one choice: name creates a new organization they own, invitationIds accepts their pending invitations and adds them to those organizations. Accepting marks those invitations accepted and can widen the user's existing grants. Repeating the call returns the first result. |
org_list |
Read | List one page of the organizations the signed-in user belongs to. Changes nothing. Requires a signed-in user. |
org_show |
Read | Show one organization by ID or slug, including the caller's role. Changes nothing. Requires membership. |
org_create |
Adds | Create a new organization with the signed-in user as its owner. Without a slug the server derives one from the name in lowercase ASCII, so "Łódź Klienci" becomes lodz-klienci, adding a short suffix when that slug is taken; org_slug_set changes it later. Changes nothing that already exists. Any signed-in user, at most five per hour. |
org_leave |
Changes or removes | Remove the signed-in user's own membership from the organization. They lose access to its workspaces until invited again. expectedVersion is the membership version from org_member_list. The last owner cannot leave. |
org_member_list |
Read | List one page of the organization's members with their roles and versions. Changes nothing. Requires membership. |
org_member_set_role |
Changes or removes | Change a member's organization role to owner, admin or member, which changes what they can manage. The last owner cannot be demoted. Requires organization owner or admin; only an owner can grant owner. |
org_member_remove |
Changes or removes | Remove a member from the organization. They lose access to all of its workspaces and branches. The last owner cannot be removed. Requires organization owner or admin. |
org_invite |
Changes or removes | Invite an email address to the organization with an organization role and optional content grants (up to 20 resource or branch targets). Creates a pending invitation and sends an invitation email to that address. Requires organization owner or admin; a workspace or folder admin may invite as member to content they administer. |
org_invitation_list |
Read | List one page of the organization's invitations. Changes nothing. Requires organization owner or admin. |
org_invitation_show |
Read | Show one organization invitation with its state, targets and version. Changes nothing. Requires organization owner or admin, or the member who sent it. |
org_invitation_accept |
Adds | Accept an invitation addressed to the signed-in user, which adds them to the organization with the invited role and grants. Pending invitations are listed by onboarding_status. Only the invitee can accept. |
org_invitation_reject |
Changes or removes | Reject an invitation addressed to the signed-in user. The invitation can no longer be accepted. Only the invitee can reject. |
org_invitation_revoke |
Changes or removes | Revoke a pending invitation. The invitee can no longer accept it. Requires organization owner or admin. |
org_invitation_resend |
Changes or removes | Send a pending invitation's email to the invitee again. Requires organization owner or admin. |
org_rename |
Changes or removes | Rename the organization, replacing its display name. The slug stays the same. Logos are set in the web app. Requires organization owner or admin. |
org_slug_set |
Changes or removes | Change the organization's slug, the short name used for organization arguments and in web links. The old slug is freed and does not redirect, so scripts, links and tool calls that used it stop working; the organization ID and every saved selection keep working. Fails with OPERATION_CONFLICT when another organization holds the slug. Setting the current slug again changes nothing. Requires organization owner or admin. |
org_logo_clear |
Changes or removes | Remove the organization's logo. Requires organization owner or admin. |
org_activity |
Read | List recent pushes, merges, copies and changes across the workspaces the caller can read, newest first. Owners and admins also see membership, access and retention changes. Changes nothing. Requires membership. |
org_usage |
Read | Show files, size, open copies and daily pushes per workspace the caller can see. Organization totals and stored version sizes appear only for owners and admins. Changes nothing. Requires membership. |
billing_status |
Read | Show the organization's subscription state, plan, trial and period end, members against the plan's limit, and the retained storage billing counts, every kept file version included. Fails with NOT_FOUND when the server does not bill. Changes nothing. Requires membership. |
billing_checkout |
Changes or removes | Create a Stripe Checkout link for the organization's subscription. Nothing is charged by this tool: a person must open the link in a browser and pay, and the subscription starts after Stripe confirms it. Expires the organization's previous open checkout link and sets the Stripe customer email to the caller's. Requires organization owner or admin. |
billing_plan |
Changes or removes | Move the organization's existing subscription to another plan. Stripe prorates the price and charges the card on file. Starter allows at most 3 members. Requires organization owner or admin. |
billing_usage |
Read | Show the organization's memory credits for the current billing period: credits included in the plan, used, overage in credits and US dollars, the monthly spending cap, a projection to the period end, threshold warnings, whether memory is paused at the cap, and totals by operation (indexing, language changes, recall, answers) and by workspace. One credit is $0.01. Usage is recorded even where the server does not bill. Changes nothing. Requires membership. |
billing_cap |
Changes or removes | Set the organization's monthly cap on memory credit overage in US dollars, or null for no cap. Overage beyond the plan's included credits is billed at $0.01 per credit up to the cap; at the cap memory recall and answers fail with SPENDING_CAP_REACHED and indexing pauses until the cap is raised or the next period starts. Files, sync and file search are not affected. Setting the same value again changes nothing. Requires organization owner or admin. |
billing_portal |
Adds | Create a short-lived Stripe Customer Portal link where a person updates the card, views invoices or cancels the subscription in a browser. The tool itself changes nothing in the subscription. Requires organization owner or admin. |
workspace_list |
Read | List one page of the organization's workspaces the caller can see. Changes nothing. Requires membership. |
workspace_show |
Read | Show one workspace, including its initialization state and version. Changes nothing. Requires access to the workspace. |
workspace_create |
Adds | Create a new, empty workspace and wait until it is ready. The slug defaults to the name in lowercase ASCII. With waitMs 0 the result is the accepted provisioning state. Changes nothing that already exists. Requires organization owner or admin. |
workspace_retry |
Adds | Resume a stalled workspace initialization and wait until it is ready. Exhausted Git sends allow observation only; exhausted provisioning receives five further attempts. Changes no files. Requires organization owner or admin. |
workspace_archive |
Changes or removes | Archive a workspace. Members lose access to its files and it disappears from listings. Requires workspace admin or organization owner or admin. |
workspace_visibility |
Changes or removes | Make a workspace public, giving every organization member read or write access, or private, limiting it to people with a grant. Changes who can see and edit its files. Requires workspace admin or organization owner or admin. |
workspace_usage |
Read | Show workspace storage use and original backup coverage. Changes nothing. Requires organization owner or admin. |
workspace_backup_show |
Read | Show the backup state of one stored original by content OID. Changes nothing. Requires organization owner or admin. |
workspace_backup_retry |
Adds | Grant another retry budget to an original backup that ran out of attempts, so the backup copy resumes. Changes no files. Requires organization owner or admin. |
workspace_retention_show |
Read | List the workspace's version retention policies. With no policy every file version is kept. Changes nothing. Requires organization owner or admin. |
workspace_retention_set |
Changes or removes | Set how long past file versions are kept for a file, under a folder or in the whole workspace. A past version stays while it is one of the newest keepVersions versions of its file or was replaced less than keepDays ago; with both, either keeps it. Current files on every branch are never removed. With neither limit every version is kept, overriding a parent policy. A stricter setting starts after 7 days; then past versions outside the limits are deleted permanently. Confirm with the user before setting a policy. Requires organization owner or admin. |
workspace_retention_clear |
Changes or removes | Remove a file's, folder's or the workspace's retention policy so it follows its parent or the organization default again, which can make past versions eligible for deletion. Takes effect after 7 days. Requires organization owner or admin. |
workspace_retention_explain |
Read | Show the retention rule that applies to a file, folder or the workspace, and whether it comes from that path, a parent, the workspace or the organization default. Changes nothing. Requires organization owner or admin. |
org_retention_show |
Read | Show the organization's default version retention, which applies wherever no workspace, folder or file policy is set. Null limits keep every version. Changes nothing. Requires organization owner or admin. |
org_retention_set |
Changes or removes | Set the organization's default version retention. A past version stays while it is one of the newest keepVersions versions of its file or was replaced less than keepDays ago; with both, either keeps it. Current files on every branch are never removed. With neither limit every version is kept, which is recommended. A stricter setting starts after 7 days, then past versions outside the limits in every workspace without its own policy are deleted permanently. Confirm with the user first. Requires organization owner or admin. |
workspace_retention_prune |
Changes or removes | Permanently delete past file versions under a folder or the whole workspace now. A past version stays while it is one of the newest keepVersions versions of its file or was replaced less than keepDays ago; with both, either keeps it. Current files on every branch are never removed. Removes at most 100 versions per call; repeat while remaining is true. Deleted versions cannot be recovered: run with dryRun first and confirm with the user. Requires organization owner or admin. |
file_stat |
Read | Show metadata for one file or folder on a branch: resource ID, kind, size, content OID and revision. Changes nothing. Requires read access to the path. |
file_list |
Read | List one page of the files and folders the caller can see inside a folder. Changes nothing. Requires read access to the folder or to items inside it. |
file_entries |
Read | List where the caller can start browsing a workspace: the root when they can read it, otherwise the topmost folders and files shared with them, with their paths. Changes nothing. Requires access to the workspace or something in it. |
file_read |
Read | Read one file at a pinned revision. Small text files come back inline (download.kind text), empty files as empty, anything else as a short-lived signed download URL. Changes nothing. Requires read access to the file. |
path_read |
Read | Read a file with its content, or a folder's entries depth first with their contents, at one revision. UTF-8 text comes back as text and other bytes as base64. A folder page that ends early returns nextCursor, pinned to the same revision. With since, a folder read returns only what changed after that revision and the paths it removed. Changes nothing. Requires read access to the path. |
path_write |
Changes or removes | Create, overwrite and delete up to 100 files in one new revision on a branch, main by default. Every path needs a precondition in expected, or give baseRevisionSha or expectedHeadSha. A path that does not match refuses the whole write with WRITE_CONFLICT and its current hash. Returns the new revisionSha and each file's sha256. Earlier versions stay in history unless retention removes them. Requires write access to each path on the branch. |
file_history |
Read | List the first-parent history of one resource on a branch, including deleted versions, with who pushed each version and its message. actor and message are null without read access to the whole workspace. Page with after. Changes nothing. Requires read access to the resource. |
revision_show |
Read | Show one revision on a branch: when it was made, who pushed it, its message and the changed paths you can read. actor and message are null without read access to the whole workspace. Changes nothing. Requires read access to the branch. |
revision_diff |
Read | List the paths that changed between two revisions of a branch. Changes nothing. Requires read access to the branch; paths the caller cannot read are left out. |
branch_list |
Read | List one page of the workspace's branches the caller can see. Page with after. Changes nothing. Requires access to the workspace. |
branch_show |
Read | Show one branch: head revision, scope, visibility, collaborators, version and policy epoch. Changes nothing. Requires read access to the branch. |
branch_history |
Read | List the branch's revisions, newest first, with who pushed each and its message. actor and message are null when permissions is partial. Page with after. Changes nothing. Requires read access to the branch. |
branch_compare |
Read | List the resources whose visible state differs between a branch and another branch (main by default), with before (target) and after (source) states. Changes nothing. Requires read access to both branches. |
branch_merge_plan |
Read | Plan merging source into target (main by default): every changed entry, conflicts, and whether the merge can proceed. Use conflict_list to get an approvable draft. Changes no files or branches. Requires read access to both branches. |
branch_merge_approve |
Changes or removes | Merge a branch into its target, usually main, using an approval draft from conflict_list or conflict_resolve, then wait for the merge to commit. Adds, overwrites and deletes files on the target branch. The draft pins both heads and the plan digest, so a moved branch fails with HEAD_MOVED. Requires write access to every changed path on the target, and admin for whole-folder deletions. |
branch_create |
Adds | Create a new branch from another branch (main by default), optionally scoped to one folder, and wait for it to commit. Without a name the server applies the user's branch-name template. The caller becomes its admin. Changes nothing that already exists. Requires read access to the source content. |
branch_settings |
Changes or removes | Change a branch's visibility or default collaborator access, which changes who can see or edit it. Omitted settings keep their values; omitted expectedVersion and expectedPolicyEpoch come from a fresh read. main cannot be changed this way. Requires branch admin. |
branch_archive |
Changes or removes | Archive a branch. It disappears from listings and can no longer be changed or merged. Requires branch admin. |
branch_collaborator |
Changes or removes | Add a branch collaborator or change their role (read, write or admin). role remove takes the collaborator off the branch and removes their access. Requires branch admin. |
conflict_list |
Read | List the conflicts between a branch and its merge target (main by default). Returns a draft that pins both heads; pass it to conflict_show, conflict_resolve and finally branch_merge_approve. Changes nothing. Requires read access to both branches. |
conflict_show |
Read | Show one conflict with its base, target and source sides and a target-to-source text diff. The diff is available only when both sides are small text files returned inline. Changes nothing. Requires read access to both branches. |
conflict_export |
Read | Return the base, target and source originals of one conflict: inline text for small files, otherwise a short-lived signed download URL. Changes nothing. Requires read access to both branches. |
conflict_resolve |
Read | Record a whole-file choice for one conflict in the draft: take source, target or delete. Nothing changes on the server; the result carries the updated draft and the conflicts that remain. Requires read access to both branches. |
operation_show |
Read | Show the state of a content operation such as a publication, branch creation or merge. Changes nothing. Requires being the operation's actor. |
operation_cancel |
Changes or removes | Cancel a content operation that has not committed yet, such as a pending push or merge. Its changes are discarded. Requires being the operation's actor. |
operation_incident |
Read | Inspect the recovery state of a blocked publication before requesting a fence. Changes nothing. Requires organization owner or admin. |
operation_fence |
Changes or removes | Request an audited recovery fence for a blocked publication, which can end that publication without committing it. Positive Git observation, not this request, decides the result. Requires organization owner or admin. |
upload_show |
Read | Show the verification state of an uploaded content candidate. Changes nothing. Requires being the upload's actor. |
upload_retry_verification |
Adds | Grant another verification budget to sealed upload bytes paused by their budget, so verification resumes. Hash mismatches cannot be retried. Changes no files. Requires being the operation's actor. |
access_show |
Read | Show the direct grants and policy epoch of one resource. Changes nothing. Requires admin on the resource or a parent folder, or organization owner or admin. |
access_list |
Read | List the direct grants on a workspace path on main. Changes nothing. Requires admin on the path or a parent folder, or organization owner or admin. |
access_explain |
Read | Explain a user's effective role on a path (default /) or on a branch, and every grant behind it. Give path or branch, not both. user is a user ID or member email and defaults to the caller. Changes nothing. Explaining another user requires admin on the path or organization owner or admin. |
access_invite |
Changes or removes | Invite an email address to the organization as a member with one content role on up to 20 workspace paths. Creates a pending invitation and sends an invitation email to that address. Requires admin on each path. |
access_grant |
Changes or removes | Give an organization member a content role (read, write or admin) on one resource, replacing any direct role they already have there. Requires admin on the resource or a parent folder, or organization owner or admin. |
access_revoke |
Changes or removes | Remove a member's direct grant on one resource. They keep access only through other grants, which the result reports. Requires admin on the resource or a parent folder, or organization owner or admin. |
token_create |
Adds | Mint a bearer token that acts as you, limited to up to 10 folders of one workspace and to a role. The token reads, writes, searches and recalls memory only inside those folders, on main, and cannot manage the workspace, organization or billing. Missing folders are created. Returns the bearer value once in credential; a retry with the same idempotencyKey returns null there. Requires admin on every folder, so a scoped token mints only inside its own folders and only when its role is admin; a minted token never outlives the token that minted it. |
token_list |
Read | List a workspace's unrevoked scoped tokens that you manage, 100 per page: all of them for a workspace admin, otherwise those on folders where you have admin, and always the token this call runs under. Bearer values are never returned. Changes nothing. |
token_revoke |
Changes or removes | Revoke a scoped token and every token minted from it. Requests with them fail at once. Requires admin on the workspace or on each of the token's folders; a scoped token may revoke itself. |
version |
Read | Show this server's version and the API capabilities: protocol version, formats, features and limits. Changes nothing. No permission needed beyond a valid connection. |
skills_list |
Read | List the agent skills bundled with Wiele. Changes nothing. |
skills_print |
Read | Return the SKILL.md instructions of one bundled agent skill, such as wiele-conflicts. Changes nothing. |
The four search tools, search_query, search_status, search_index and search_disable, are hidden while server-side search is off. The memory tools, memory_recall, memory_answer, memory_status, memory_enable, memory_languages and memory_languages_set, are listed only on servers with memory on.