Docs

MCP servers

Mework is an MCP client: you declare servers in mcp.json, choose which ones a conversation uses, and their tools become tools the model can call. Mework connects to stdio and Streamable HTTP servers and uses only their tools, not their prompts or resources.

Where mcp.json lives

Level File Used by
Global ~/.mework/mcp.json (Windows: %USERPROFILE%\.mework\mcp.json) Every conversation
Workspace <workspace>/.mework/mcp.json Conversations that include that workspace

A conversation can select from the global servers and those of all its workspaces. A server belongs to a machine, not to a workspace:

  • A workspace's servers run on that workspace's machine. For a workspace on WSL or an SSH machine, Mework reads its mcp.json there, starts its stdio servers there, and reaches its HTTP servers through that machine's network. Such a server may be used for work in any of the conversation's workspaces on that machine.
  • Global servers start and connect from this computer.

When the conversation's workspaces are not all one folder on this computer, the system prompt tells the model, for each selected server, which machine it runs on and which of the conversation's workspaces are on that machine, or that none is.

When the conversation works in an isolated worktree of a workspace, that workspace's mcp.json is still read from its own folder. The temporary project's scratch folder has no .mework; a conversation there gets the global servers and those of the workspaces it attached.

Format

The format is the same as Claude Code's .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
    }
  }
}
  • Each key under mcpServers is a server name, made of ASCII letters, digits, - and _.
  • Mework ignores the whole file if it is not valid JSON or the servers are not under mcpServers. A UTF-8 byte-order mark at the start is fine.
  • An entry that fails its checks is listed as Unavailable, with the reason in its tooltip; the rest of the file still works. While a conversation has an unavailable server selected, every run fails.

Keys

Key For What it does
type both "stdio" or "http" (also "streamable-http", "streamable_http"). If omitted, an entry with command is stdio; a url without type is unavailable. sse, ws and sdk are not supported.
command stdio Required. The program to start, run directly — never through a shell.
args stdio Arguments, as an array of strings.
env stdio Variables to set for the server, as strings. They override inherited values.
envPassthrough stdio Names of environment variables to pass on (see Server environment).
cwd stdio Working directory, as an absolute path to an existing folder. If omitted, a workspace's server starts in its own workspace's folder, or the conversation's worktree of it; a global server starts in the conversation's first workspace on this computer, or your home folder when none of its workspaces is here. Relative paths in command and args resolve against it.
workspace stdio Read only in ~/.mework/mcp.json. true declares that the server works on a workspace's files or depends on the folder it runs in (see Servers that work in a workspace).
registryUrl stdio A package registry URL for launchers such as npx, bunx, uvx and pip. A registry variable you set in env wins.
url http Required. An https:// address, or http:// for loopback and private-network hosts only. No user name and no #fragment.
headers http Request headers. Headers that HTTP or MCP manages, such as host, content-type or mcp-session-id, make the entry unavailable.
timeoutSeconds both Per-call timeout in seconds. Default 45, maximum 300.
timeout both Claude Code's per-call timeout in milliseconds. timeoutSeconds wins.
longRunning both true raises the default call timeout to 300 seconds.
description both Shown in the list and to the model.
disabledTools both Tool names, as the server spells them, to leave out.
disabledAutoApproveTools both Tool names that ask for approval on every call, at every security level.

An entry with oauth or headersHelper is unavailable: Mework does not run sign-in flows or header scripts, so put a token in headers instead. Keys Mework does not know are ignored, including other clients' "disabled": true, autoApprove and alwaysAllow. To turn a server off, untick it.

Servers that work in a workspace

A global stdio server with "workspace": true follows the conversation's workspaces on this computer:

  • With two or more of them, each of the server's tools gets a workspace parameter: an integer, one of those workspaces' numbers, by default the first. Each call goes to an instance of the server started in that workspace's folder, in place of cwd, and Mework removes the parameter before the call reaches the server.
  • With only one, the server starts there like any other global server, and its tools get no extra parameter.
  • A tool whose own schema already has a workspace property keeps its schema as it is, and its calls go to the first workspace.

Environment variables in values

${VAR} and ${VAR:-default} are replaced in command, args, env values, url and headers values, but not in cwd; an unset variable with no default makes the entry unavailable. The values come from Mework's own environment, which on macOS includes what your login shell exports (~/.zprofile, ~/.zshrc); restart Mework after changing a variable. In the mcp.json of a WSL or SSH workspace, they come from that machine's environment and the workspace's Environment variables (see Workspaces).

Server environment

A stdio server does not inherit Mework's environment. It starts empty and receives, in this order:

  1. PATH, PATHEXT, SystemRoot, WINDIR, COMSPEC, TEMP, TMP, TMPDIR, HOME, USERPROFILE, APPDATA, LOCALAPPDATA, PROGRAMDATA, ProgramFiles, ProgramFiles(x86), XDG_CACHE_HOME, XDG_CONFIG_HOME; on macOS also USER, LOGNAME, SHELL, TERM, LANG, LC_ALL, LC_CTYPE, SSH_AUTH_SOCK, and http_proxy, https_proxy, all_proxy, no_proxy in either case.
  2. The variables named in envPassthrough.
  3. env.

For a server declared in a WSL or SSH workspace, the environment comes from that machine instead of this computer, plus the workspace's Environment variables.

envPassthrough refuses names starting with MEWORK_, ANTHROPIC_, OPENAI_, CLAUDE_, CODEX_, AWS_, AZURE_, GOOGLE_, GEMINI_ or DEEPSEEK_, so credentials are never handed on by accident. To give a server one of them on purpose, write it in env, for example "env": { "AWS_PROFILE": "${AWS_PROFILE}" }.

Choose servers for a conversation

  1. Open More options → Conversation settings → MCP (see Conversation settings).
  2. Tick the servers this conversation should use.

The list refreshes by itself shortly after you save mcp.json; Rescan refreshes it at once, and runs always use the file on disk. The list has a Global section, then one section per workspace (see Conversation settings). The folder button on a section's heading, Open the global config folder or Open the config folder of {path}, shows that level's mcp.json, creating the .mework folder if needed. For a WSL or SSH workspace, it opens that folder on its machine in the Files pane.

Test connection — the plug icon on an available row — starts the server once and lists its tools. If it fails, the row's tooltip shows the error and the last five lines the server wrote to stderr.

  • Changing the selection while the model's prompt cache is warm is drawn orange and asks once.
  • On a model without Mid-conversation tools (see Model properties), the selection is frozen (gray) after the first request. A Dangling row can still be unticked.
  • The trash-can button, pressed again when it reads Confirm, removes only that server's entry from its mcp.json. Conversations that selected it show it as Dangling, and every run fails, naming it, until you untick it.
  • The built-in mework preset selects no servers.

What happens each turn

At the start of every turn, Mework connects to each selected server and asks for its tools. If a server in mcp.json cannot be reached, or is dropped for going over a limit, the turn shows a notice naming the server and the reason; the other servers' tools are still offered. A selected server whose entry is gone from mcp.json is Dangling and fails the run instead.

Each conversation gets its own server process or connection, so three conversations using one stdio server run three copies of it. It closes after 30 minutes idle; a changed entry starts a fresh one on the next turn.

A result over 64 KiB is refused, not cut short — images and base64 data reach that quickly. A result with isError: true counts as a failed call.

Tool names

The model sees each tool as mcp__<server>_<hash>__<tool>__<hash>: the server name shortened to 12 lowercase letters, digits and _, the tool name to 18, and two 10-digit hex hashes that change if you rename the server or move its mcp.json.

To match every tool of one server in a hook, use ^mcp__<shortened server name>_.

Tool discovery

The Tool discovery switch at the bottom of the MCP page decides how tools are declared:

  • All declared (off): every selected server's tool schemas go out with every request.
  • On demand (on): no MCP schemas are sent. The model gets a list of tool names and loads the ones it needs with tool_search, from the next step on.

The built-in mework preset turns discovery on. It needs a model with Mid-conversation tools; without it the switch is disabled. Changing it while the cache is warm is drawn orange. Subagents use the parent's setting.

Approvals

At the Manual and Accept edits security levels, every MCP call asks. At Full access, calls run without a card, except the tools in the last point below.

  • MCP cards are always marked high risk, and Always allow is never offered.
  • A PreToolUse or PermissionRequest hook can approve a call in your place.
  • Some tools ask on every call, even at Full access, and no hook can skip them: tools the server marks with _meta["anthropic/requiresUserInteraction"], and tools you list in disabledAutoApproveTools.

Limits

What Limit
One call 45 s by default; up to 300 s
Listing tools, all servers together, per turn 60 s
Tools per turn 2,048
Tool schemas of one server 512 KiB
Tool schemas of all servers 2 MiB
Result of one call 64 KiB

Troubleshooting

The server is not listed. Check that the file is valid JSON with servers under mcpServers. For a WSL or SSH workspace, the workspace's mcp.json must be on that machine. An old .naiword/mcp.json is read only when there is no .mework/mcp.json beside it; after moving it, tick the servers again.

Its tools never show up. The turn's notice gives the reason, and Test connection shows what the server wrote to stderr. A server sees only the variables under Server environment. If a server is over a schema limit, leave some of its tools out with disabledTools.

Edit this page on GitHub