The MCP server
Last updated
Weald MCP is the server the Mac app runs so any coding agent can read and change the project record: list tickets, move a card across the board, report progress, comment, and raise a question a person has to answer. It speaks the Model Context Protocol over streamable HTTP at http://127.0.0.1:47921/mcp, so an agent that speaks MCP at all is compatible with no adapter and no plugin. Weald is the server and the agent is the client, which is why nothing here needs an account, a token or an internet route.
The picture above is the calls and their consequence side by side. A card outlined in ink is one an agent is holding, the rule under a title is weald_board_progress reporting, and the last move is a person: an agent lands work in review, and a human closes it.
What it is for
An agent that reports through Weald MCP puts its work where the team already looks. The board moves while the run is happening rather than after it, a question lands in a queue that survives an app restart, and the whole trail stays with the ticket and travels over git.
Nothing is polled. The app is watching .weald and its own event log, so a call is on screen in the time it takes to write a file.
The calls that move a board
These are the core tier: the reporting contract, and the smallest surface a headless run needs.
| Tool | What it does |
|---|---|
weald_list_tickets | List a project's tickets, optionally filtered by status |
weald_get_ticket | Read one ticket in full, by id |
weald_create_ticket | File a real ticket, with no approval gate |
weald_update_status | Move a card between columns and append an activity note |
weald_board_progress | Report percent and a step line on the ticket you were handed |
weald_run_progress | Move the progress bar a person is watching for this run |
weald_comment_ticket | Post a comment that stays with the ticket forever |
weald_ask | Put a question in the Needs You queue until somebody answers it |
weald_notify | Send one desktop notification with tappable actions |
weald_log_event | Append a freeform line to the project timeline |
Percent never goes backwards, and a status change is a real column change: use progress for how far along you are, and status for where the card belongs.
Three tiers, one callable surface
The whole surface is about twenty-eight tools, and every description plus schema is charged to the agent's context window on every turn whether or not it calls one. So tools/list serves a tier while tools/call stays ungated: a tool outside the tier still runs when an agent names it.
| Tier | Advertises |
|---|---|
core | Tickets, status, progress, comments, asks. Smallest context cost |
standard | The default. Core plus tray status, quick chat, views and widget mounting |
all | Every tool, including the widget authoring toolkit |
weald_tools is advertised at every tier, which is what keeps tiering lossless. It lists every tool with a one-line summary, marks the ones this connection did not advertise, and returns full schemas on request so an agent can call a hidden tool correctly the first time.
Pick a tier per connection with a query parameter, http://127.0.0.1:47921/mcp?tools=core, or set the default in the MCP section of Settings. Clients cache schemas at the handshake, so a change takes effect when the agent reconnects.
Point an agent at it
Weald does not edit another tool's configuration for it. The app shows the one-liner and the config path, and you decide.
claude mcp add --transport http weald http://127.0.0.1:47921/mcp
Anything else that speaks streamable HTTP takes the same URL in its own config, under whatever key it calls a server list. Codex, Cursor, OpenCode, opencode, Gemini CLI, Amp, Aider and Crush are all built in, alongside agents you define yourself.
What a call may not do
The socket is loopback only and carries no auth token, because it is not reachable from off the machine. Authority comes from a delegation your device issues, which can narrow that device's authority and never widen it, and an agent's first connection asks you once, naming the workspace, the groups, the capabilities and the expiry.
- Three capabilities cannot be delegated at all: admitting members, revoking members, and admin authority.
- A ticket transition is its own capability, so an agent can be allowed to move a card to review without being allowed to move it to done.
- Model-drafted suggestions are staged and need approval. A sanctioned agent's writes apply immediately, and the
originfield on a ticket records which was which.
A remote teammate cannot start an agent on your machine, and nothing in this server is reachable from the relay. Weald MCP is local by construction, which is the reason it needs no key of its own.