Skip to content
covey

An agent is supposed to leave a comment on a GitLab issue, and the comment reads "Deployment only runs after the merge, when: 'manual' stays set". Through the shell, the model has to build a curl call whose JSON body sits inside single quotes. The first single quote in the comment text closes that string early, and the call either fails or sends something other than what was meant.

Whether agents should call their tools through the Model Context Protocol instead has been argued for a while. In March 2025 bschmidt44 asked on Hacker News "Why MCP instead of just HTTP?", with the objection that language models have far more training data about fetch than about a new protocol. In August 2025 Mario Zechner wrote that practitioners are usually sceptical, because many MCP servers flood the context window or offer dozens of tools, and that he let his coding agents call command-line tools directly.

covey answers the question at the one place where an agent reaches a target system at all: the local action proxy in the sandbox.

The shell route loses turns to quoting

By default a covey agent issues a target action as a shell command, curl -s -X POST http://localhost:$COVEY_ACTION_PORT/actions/<system>/<action> -d '<json>' against the action proxy, and reads the answer off stdout. That works. It also means the model writes JSON into a quoted shell string, where every quote and every brace in a parameter is a chance to get it wrong. A wrong call costs a turn against the run's turn limit (which the Claude Code adapter passes as --max-turns).

The comment about the merge is exactly that case. The error sits in the wrapping of the content.

Two doors lead into the same room

So the same proxy takes actions a second time, as an MCP tool server at POST /mcp. It answers four methods (initialize, ping, tools/list and tools/call), and anything else gets an error that starts with "method not found". On this route the runtime hands the parameters over as a JSON object, and there is no shell between the model and the proxy. The quote in when: 'manual' is then an ordinary character inside a JSON string (RFC 8259 escapes only the double quote, the backslash and control characters).

Behind both doors sits one function. For an action on a target system it makes the guard-rail decision, runs the action with brokered credentials and writes it into the run's recording. Placeholders of the form {{secret:<key>}} are resolved only after the guard-rail decision, before the plugin sees the parameters, whichever door the call came through.

A denied action comes back on the MCP route as status: denied inside the result. The runtime reads it as an answer and keeps treating the tool as working.

One tool per target system instead of one per action

The tool list holds one tool for each target system that the organisation has enabled and the agent's ACCESS.md grants.

On top of that comes a tool called covey for the platform's own actions (notes, wiki and tasks, among others). Every tool takes two fields: the action's name as action and its parameters as an object params. A target system's tool carries the plugin's own documentation as its description, the same text that otherwise stands in the system prompt.

A schema per action would have been the obvious design, and covey leaves it out on purpose because the plugins describe their actions in prose. A schema maintained next to that prose would be a second source of truth that drifts from the first.

Zechner arrived at the same shape for his own tool: a single tool instead of one per command. The price is that the runtime does not check an action's parameter names against a schema, so the model still takes them from the description.

The MCP route has to be switched on

The switch is COVEY_ACTION_MCP=1 in the .env, followed by a restart. It is opt-in because a failed handshake would take every target action of a run with it. The operations docs therefore suggest watching one agent's recording for a run afterwards, where the actions show up as mcp__covey tool calls instead of Bash. The shell route stays open either way, so an agent config that describes the curl call keeps working.

For Claude Code the adapter passes the proxy with --mcp-config and adds mcp__covey to the same --allowedTools list. Without that entry a headless run would ask on every action for a permission that only a person at a screen could give.

The Claude Code adapter passes the MCP document on, and so does an adapter that runs Claude Code as its harness against a different base URL. Another adapter's spec says it does not pass the document, so agents on that one reach target systems through the shell.

For the agent with the GitLab comment, MCP or shell comes down to how the call is wrapped. Which action it may run, with which credentials and with which entry in the recording is decided in both cases by the same code in the proxy.

Back to all posts