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:

FieldRequiredNotes
pathyesLowercase letters, numbers and hyphens, e.g. /docs/mvp. The parent must exist.
bodyyesMarkdown, no front matter.
titlenoDefaults to the body's first # heading, then to the slug.
typenopage, post, link or image. Defaults to page.
reasonnoShown to the owner on the review screen. Defaults to Create <path>.

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:

json
{
  "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:

FieldWhere it comes from
authorGOATBOAT_AGENT_NAME env var, default mcp-agent
parentIdLooked up by fetching the page at the parent path
slugLast segment of path
formatAlways md
statusAlways draft
titleFrom the argument, else the first heading, else the slug

Then it sends one HTTP request:

text
POST {GOATBOAT_URL}/api/proposals
authorization: Bearer <agent token>
content-type: application/json
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:

json
{
  "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 in body would 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_page and move_page each build a single-op proposal.
  • 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.