What the MCP create_page call actually sends
What a goatboat MCP create_page call actually sends, hop by hop from the agent's arguments to the proposal request.
When an agent creates a page through the goatboat MCP server, it does not send a markdown file with front matter. It sends a small JSON object, and the body is one string field inside it. This page follows one call (create_page) from the agent to the database.
The short answer
Pure JSON at every hop. The only non-JSON content is the page body, which is markdown carried as a JSON string.
Hop 1: agent to VS Code
The agent emits a structured tool call: a tool name plus named arguments matching the tool's input schema. For create_page the fields are:
VS Code shows the tool under a prefixed name (mcp_goatboat2_create_page). The server itself calls it create_page.
Hop 2: VS Code to the MCP server
VS Code starts the server as a local process (npm run mcp, transport stdio) and talks to it over stdin and stdout using JSON-RPC 2.0, one JSON message per line:
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "create_page",
"arguments": {
"path": "/docs/example",
"title": "Example",
"reason": "Why this page exists",
"body": "# Example\n\nFirst paragraph.\n\n## Section\n\nMore text."
}
}
}Because the body is a JSON string, newlines travel as \n and quotes as \". The receiving side decodes them back into real markdown. Nothing is lost, but the raw wire text is not readable as markdown.
The server's own stdout is the protocol channel, which is why it must never console.log.
Hop 3: MCP server to goatboat
The server checks the arguments against its schema, then builds a different object. It adds fields the agent never supplies:
Then it sends one HTTP request:
POST {GOATBOAT_URL}/api/proposals
authorization: Bearer <agent token>
content-type: application/json{
"author": "mcp-agent",
"reason": "Why this page exists",
"ops": [
{
"op": "createContent",
"input": {
"parentId": "<uuid of /docs>",
"slug": "example",
"type": "page",
"title": "Example",
"body": "# Example\n\nFirst paragraph.\n\n## Section\n\nMore text.",
"format": "md",
"status": "draft"
}
}
]
}The agent token lives in the server's environment. The agent never sees it and cannot send it. The same applies to author, parentId, format and status: the agent can't override them.
The proposal is stored as pending. Nothing is created in content until the owner approves it, at which point goatboat runs createContent with that input.
Hop 4: the answer back
Goatboat replies with JSON. The server reshapes it and returns it as the tool result, which is JSON pretty-printed into a text block:
{
"content": [
{
"type": "text",
"text": "{\n \"proposal\": \"<uuid>\",\n \"status\": \"pending\",\n \"review\": \"https://…/proposals/<uuid>\",\n \"note\": \"Nothing has changed yet. …\"\n}"
}
]
}So the result is JSON inside a string inside JSON. The agent reads the inner text and relays the review link.
On failure the server returns isError: true with a plain-text message, such as the status code and validation issues from goatboat.
What this means in practice
- No metadata travels inside the body. Title, description and type are separate fields. A
---front matter block inbodywould be stored as literal text. - Everything the agent controls is five fields. Everything else is fixed or filled in by the server.
- The agent never has database access or a write token. Its only effect is a pending proposal.
- Updates follow the same pattern with different tools and ops:
update_body,update_page_meta,publish_pageandmove_pageeach build a single-op proposal.
Related
- MCP read report: pages without a description
An agent's report from one filtered list_pages call: which /docs pages lack a description, and what that proves.
- Proposing complete, published pages
Agents can now propose a new page with its description, tags, project and section, published on approval. What changed, and the security questions that come with it.
- Routes as data
Proposal: give every page, including TSX ones, a row in the content database.
- Content tree
Every node nested under its parent. Paths, and so URLs, come from this tree.