MCP & Agents

Lumen exposes its entire content API over the Model Context Protocol. Grant an agent a signed JWT and it manages pages, components, forms, and tables through the same service layer as the REST API.

Connecting a client

The MCP server lives at /mcp (Streamable HTTP transport, JSON-RPC 2.0) and uses the same JWT auth as the API:

npm run jwt:sign -- --sub admin --exp 365d

# opencode
opencode mcp add lumenpages-cms \
  --url http://localhost:8787/mcp \
  --header "Authorization=Bearer <token>"

# Claude Code
claude mcp add --transport http lumenpages-cms http://localhost:8787/mcp \
  --header "Authorization: Bearer <token>"

Manual configuration (Claude Desktop, Cursor) uses the same URL and header in each client's mcpServers config. For production, replace http://localhost:8787 with your deployed Worker URL.

Available tools

35+ tools cover every content type, plus five dynamic CRUD tools per custom table:

Entity	Tools
Pages	`list_pages`, `get_page`, `create_page`, `update_page`, `delete_page`
Layouts	`list_layouts`, `get_layout`, `create_layout`, `update_layout`, `delete_layout`
Components	`list_components`, `get_component`, `create_component`, `update_component`, `delete_component`
Forms	`list_forms`, `get_form`, `create_form`, `update_form`, `delete_form`
Form entries	`list_form_entries`, `delete_form_entry`
Webhooks	`list_webhooks`, `get_webhook`, `create_webhook`, `update_webhook`, `delete_webhook`
Settings	`list_settings`, `get_setting`, `upsert_setting`, `delete_setting`
Files	`list_files`, `create_upload_url`, `get_file`, `delete_file`
Custom tables	`list_custom_tables`, `describe_custom_table`, `create_custom_table`, `drop_custom_table` + 5 CRUD tools per table

Create/update tools accept the same fields documented in the Building Blocks pages, with identical validation to the HTTP API — JSON schemas, field rules, and the SQL guard all apply.

Working with agents

Describe outcomes, not operations — "build a blog with posts and tags" works better than listing table columns.
Review in the browser — agents change content, not code; refresh the page to see the result.
Keep tokens scoped and rotated — an admin JWT is a full-access credential. Issue per-agent tokens with expiry.
Use snapshots — lumenpages-cms db snapshot before letting an agent make sweeping changes.

Notes

MCP respects the API_ENABLED flag — disabled when API_ENABLED=false.
The same JWT works for both /api and /mcp.
File uploads go through the signed-URL flow — the agent mints a PUT URL and uploads bytes directly.