MCP server | Wiele docs

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.json or config.toml that 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, writes or removes data.

How tools behave

organization is required on most tools. There's no default organization over MCP.
workspace takes an ID, slug or name, and path also accepts WORKSPACE:/path. branch defaults to main.
Tools that change something take an optional idempotencyKey (a UUIDv7). Without one the server generates a key and returns it in the result's _meta under io.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. 0 returns at once. A wait that runs out fails with OPERATION_PENDING; call again with the same key, or check with operation_show.
Merge drafts travel as JSON. conflict_list returns a draft; pass it to conflict_show and conflict_resolve, then to branch_merge_approve as approval.
Failures come back as tool results with isError: true and { 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_read returns file content inline up to 1 MiB, and folder contents up to 768 KiB per page with 256 KiB per file. file_read returns text inline up to 64 KiB. Larger files come back as a short-lived signed download URL.
path_write changes up to 100 paths, 512 KiB per file.
conflict_show shows 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 user, session expiry and username behind this connection's credential. Same data as `wiele auth status --json`.
`settings_list`	Read	List the signed-in user's account settings with their version.
`settings_get`	Read	Read one account setting (username or branch-name-template), or all settings when key is omitted.
`settings_set`	Write	Set username or branch-name-template. The server checks the current settings version, so a concurrent change fails instead of being overwritten.
`settings_reset`	Write	Reset username or branch-name-template to its default.
`onboarding_status`	Read	Show whether the user still has to create a first organization or accept pending invitations, and list those invitations.
`onboarding_complete`	Write	Finish onboarding with exactly one choice: name creates a default organization, invitationIds accepts pending invitations.
`org_list`	Read	List one page of the organizations the signed-in user belongs to.
`org_show`	Read	Show one organization by ID or slug, including the caller's role.
`org_create`	Write	Create an organization owned by the signed-in user. The slug defaults to the name in lowercase ASCII, so "Łódź Klienci" becomes lodz-klienci.
`org_leave`	Removes data or access	Remove the signed-in user's own membership. expectedVersion is the membership version from org_member_list.
`org_member_list`	Read	List one page of organization members with their roles and versions.
`org_member_set_role`	Write	Change an organization member's role to owner, admin or member.
`org_member_remove`	Removes data or access	Remove a member from the organization, revoking their access to its workspaces.
`org_invite`	Write	Invite an email address to the organization with an organization role and optional content grants (up to 20 resource or branch targets).
`org_invitation_list`	Read	List one page of the organization's invitations as an organization admin.
`org_invitation_show`	Read	Show one organization invitation with its state, targets and version.
`org_invitation_accept`	Write	Accept an invitation addressed to the signed-in user. Pending invitations are listed by onboarding_status.
`org_invitation_reject`	Removes data or access	Reject an invitation addressed to the signed-in user.
`org_invitation_revoke`	Removes data or access	Revoke a pending invitation as an organization admin. The invitee can no longer accept it.
`org_invitation_resend`	Write	Send a pending invitation's email again as an organization admin.
`org_rename`	Write	Rename the organization as an owner or admin. The slug stays the same. Logos are set in the web app or with wiele org logo set.
`org_logo_clear`	Write	Remove the organization's logo as an 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.
`org_usage`	Read	Show files, size, open copies and daily pushes per workspace. Organization totals and stored version sizes are for owners and admins.
`billing_status`	Read	Show the organization's subscription state, plan, trial and period end, members against the plan's limit, and the retained storage that billing counts, every kept file version included. Fails with NOT_FOUND when the server does not bill.
`billing_checkout`	Write	Create a Stripe Checkout link for an organization owner or admin. A person opens it in a browser to add a card; the subscription starts after Stripe confirms it. New organizations get a 7-day trial. Never complete payment on the user's behalf.
`billing_plan`	Write	Move the organization's existing subscription to another plan, for an organization owner or admin. Stripe prorates the monthly price. Starter allows at most 3 members.
`billing_portal`	Write	Create a short-lived Stripe Customer Portal link where an organization owner or admin updates the card, views invoices or cancels.
`workspace_list`	Read	List one page of the organization's workspaces the caller can see.
`workspace_show`	Read	Show one workspace, including its initialization state and version.
`workspace_create`	Write	Create a 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.
`workspace_retry`	Write	Resume a blocked workspace initialization and wait until it is ready. Exhausted Git sends allow observation only; exhausted provisioning receives five further attempts.
`workspace_archive`	Removes data or access	Archive a workspace as an organization admin. Members lose access to its files.
`workspace_visibility`	Write	Make a workspace public to every organization member, with read or write access, or private to people with a grant, as a workspace admin.
`workspace_usage`	Read	Show workspace storage use and original backup coverage as an organization admin.
`workspace_backup_show`	Read	Show the backup state of one stored original by content OID.
`workspace_backup_retry`	Write	Resume an original backup after its retry budget is exhausted.
`workspace_retention_show`	Read	List the workspace's version retention policies, for an organization owner or admin. With no policy every file version is kept.
`workspace_retention_set`	Write	Set how long past file versions are kept for a file, under a folder or in the whole workspace, for an organization owner or admin. 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; the old one protects versions until then. Confirm with the user before setting a policy.
`workspace_retention_clear`	Write	Remove a file's, folder's or the workspace's retention policy so it follows its parent or the organization default again, for an organization owner or admin. Takes effect after 7 days.
`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.
`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.
`org_retention_set`	Removes data or access	Set the organization's default version retention, for an organization owner or admin. 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 for good. Confirm with the user first.
`workspace_retention_prune`	Write	Delete past file versions under a folder or the whole workspace now, for an organization owner or admin. 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.
`file_stat`	Read	Show metadata for one file or folder on a branch: resource ID, kind, size, content OID and revision.
`file_list`	Read	List one page of the files and folders the caller can see inside a folder.
`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.
`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.
`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.
`path_write`	Write	Write and delete up to 100 paths in one revision. 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. Retrying with the same idempotencyKey returns the original result.
`file_history`	Read	List the first-parent history of one resource on a branch, including deleted versions. Page with after.
`revision_show`	Read	Show one revision on a branch: when it was made, its parents and the changed paths.
`revision_diff`	Read	List the paths that changed between two revisions of a branch.
`branch_list`	Read	List one page of the workspace's branches the caller can see. Page with after.
`branch_show`	Read	Show one branch: head revision, scope, visibility, collaborators, version and policy epoch.
`branch_history`	Read	List the branch's revisions, newest first. Page with after.
`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.
`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.
`branch_merge_approve`	Write	Merge a branch using an approval draft from conflict_list or conflict_resolve, then wait for the merge to commit. The draft pins both heads and the plan digest, so a moved branch fails with HEAD_MOVED.
`branch_create`	Write	Create a 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.
`branch_settings`	Write	Change a branch's visibility or default collaborator access. Omitted settings keep their values; omitted expectedVersion and expectedPolicyEpoch come from a fresh read.
`branch_archive`	Removes data or access	Archive a branch. It disappears from listings and can no longer be changed.
`branch_collaborator`	Removes data or access	Add a branch collaborator or change their role (read, write or admin). role remove takes the collaborator off the branch and removes their access.
`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.
`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.
`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.
`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.
`operation_show`	Read	Show the state of a content operation such as a publication, branch creation or merge.
`operation_cancel`	Removes data or access	Cancel a content operation that has not committed yet.
`operation_incident`	Read	Inspect the recovery state of a blocked publication before requesting a fence.
`operation_fence`	Removes data or access	Request an audited recovery fence for a blocked publication. Positive Git observation, not this request, decides the result.
`upload_show`	Read	Show the verification state of an uploaded content candidate.
`upload_retry_verification`	Write	Resume verification of sealed upload bytes paused by its budget. Hash mismatches cannot be retried.
`access_show`	Read	Show the direct grants and policy epoch of one resource as a source admin.
`access_list`	Read	List the direct grants on a workspace path on main, as a source 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.
`access_invite`	Write	Invite an email address to the organization as a member with one content role on up to 20 workspace paths.
`access_grant`	Write	Grant an organization member a content role (read, write or admin) on one resource.
`access_revoke`	Removes data or access	Remove a member's direct grant on one resource.
`version`	Read	Show this server's version and the API capabilities: protocol version, formats, features and limits.
`skills_list`	Read	List the agent skills bundled with Wiele.
`skills_print`	Read	Return the SKILL.md instructions of one bundled agent skill, such as wiele-conflicts.

The four search tools, search_query, search_status, search_index and search_disable, are hidden while server-side search is off.