How-to

Connect AI agents with MCP

Every WREN server has a built-in Model Context Protocol endpoint at /mcp. Agents can read and query your data, write content and files to a preview label, and, once you say so, release a whole site in one transaction.

How it works

  • Two endpoints.
    • https://<host>/mcp is for your own agents. The org comes from the API key, exactly like the REST API, so an agent sees and changes only what its key may.
    • https://<host>/orgs/{slug}/mcp is bound to one org; it's what a custom domain's /mcp maps to. Without a key it's public and read-only, and ?tree=mysite scopes it to the one site that domain shows. With a key it gives the full tools, but only for keys of that org. See AI agents on your domain.
  • Same rules as the API. Every tool calls the REST API internally, so permissions, label filters and org isolation are enforced by the same code.
  • Preview first. Write tools label new versions preview by default. Going live is a separate tool (promote_tree), marked destructive so clients ask before running it.
  • Read-only mode. /mcp?readonly=1 exposes only the read tools.
  • Transport: Streamable HTTP (stateless JSON responses), protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.

Connect a client

Create an API key first (Admin UI → API Keys, or wren keys create). Use a dedicated key per agent so you can revoke it on its own.

Claude Code

bash
claude mcp add --transport http wren https://wren.aemwip.com/mcp \
  --header "Authorization: Bearer $WREN_API_KEY"

Cursor (.cursor/mcp.json)

json
{
  "mcpServers": {
    "wren": {
      "url": "https://wren.aemwip.com/mcp",
      "headers": { "Authorization": "Bearer ${env:WREN_API_KEY}" }
    }
  }
}

VS Code (.vscode/mcp.json)

json
{
  "inputs": [{ "id": "wren-key", "type": "promptString", "description": "WREN API key", "password": true }],
  "servers": {
    "wren": {
      "type": "http",
      "url": "https://wren.aemwip.com/mcp",
      "headers": { "Authorization": "Bearer ${input:wren-key}" }
    }
  }
}

Clients that only support local (stdio) servers

Bridge with mcp-remote:

json
{
  "mcpServers": {
    "wren": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://wren.aemwip.com/mcp", "--header", "Authorization:Bearer ${WREN_API_KEY}"],
      "env": { "WREN_API_KEY": "wren_…" }
    }
  }
}

Client config formats change often. If a snippet doesn't work, check your client's MCP docs for "remote HTTP server with headers". The endpoint and header are the only WREN-specific parts.

Tools

ToolWhat it doesRead-only
whoamiOrg (id, name, slug), role, rules, public URL patternsyes
list_collectionsCollections in the orgyes
query_documentsFilter, project, aggregate, read at a label; cursor pagingyes
get_documentBy id or natural key, at a label or versionyes
list_versions, diff_versionsHistory and what changedyes
list_tree, read_fileTrees, paths, and file content at a labelyes
write_documentUpsert by key, update by id, or create; labels the version previewno
write_fileWrite a file at a tree path as a new version; labels it previewno
set_labelPoint a label at a version of one documentno (destructive)
promote_treeRelease a whole tree in one transactionno (destructive)

The safe workflow

  1. Make the site's public rule filter on published (see Publish a site). This is what keeps agent edits private until release.
  2. The agent writes with write_file and write_document. New versions are labelled preview, and visitors don't see them.
  3. You (or the agent) check with read_file / get_document at label preview, or with diff_versions.
  4. You approve, and the agent calls promote_tree. Every page goes live at the same moment, and rollback is another promote.

Let agents write to a preview label; let humans promote. For data that should be live immediately (scores, feeds), use a collection whose public rule has no label filter. Agent writes there are public as soon as they're made.

Several orgs

A key belongs to one org. To work in two orgs, add the endpoint twice with different keys and names, for example wren-tournaments and wren-clubhub. The agent sees them as two separate servers.

Safety checklist

  • One key per agent; revoke it when you're done (wren keys revoke).
  • Use /mcp?readonly=1 for agents that only need to answer questions.
  • To limit what a key can touch, give it key:<keyId> permission rules, for example write access to one collection only. The org owner's keys bypass all rules, so for a restricted agent use a key created by a member account.
  • Keep promote_tree behind a human confirmation; MCP clients show the destructive hint for it.
  • Everything an agent writes is versioned. Nothing is overwritten, and diff_versions shows exactly what it changed.