Guides / MCP server

Guides

MCP server

Connect Claude Code, Codex, Cursor and other MCP clients to Wiele's remote MCP endpoint with a bearer token. Includes the full tool list.

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, adds or changes 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 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.