Documentation
AI agents
Translated from the Portuguese original. Labels from the CLI and the admin panel stay in Portuguese, as you will see them.
Rubrica was made to work with agents such as Claude Code and Codex. They don't edit the database "from outside": they use a local MCP server that talks to your project's Convex with the login of a panel user and shows a preview before writing.
How it works
agent (Claude Code, Codex) ──stdio──▶ rubrica mcp ──HTTPS──▶ project's Convex
└─ token in ~/.config/rubrica/ (logged-in user's role)
- The server runs on your machine, starts with the agent and closes with it. There is no hosted server.
- The tools come from the same fields and rules that apply in the panel and the backend.
- The permissions of the role of the logged-in user apply. A
blog-editoraccount can only touch posts and media, even if the agent asks for something else. - Every tool that writes starts as a preview (
dryRunon by default): the agent shows the before and after, and only with your "ok" repeats the call to write.
Set up
A project created by create-rubrica already comes with the .mcp.json ready (no secrets, safe to commit):
{
"mcpServers": {
"rubrica": { "command": "npx", "args": ["rubrica", "mcp"] }
}
}
In Claude Code you can also use claude mcp add rubrica -- npx rubrica mcp. In Codex, in ~/.codex/config.toml:
[mcp_servers.rubrica]
command = "npx"
args = ["rubrica", "mcp"]
env = { RUBRICA_PROJECT = "/path/to/project" }
To talk to the published site, add "--producao" to the args, in a separate server (rubrica-producao), so you never mix the two up.
Login
The login is yours, in your terminal. The password is typed there, without echo, and never goes through the agent:
npx rubrica mcp login # asks for email and password
npx rubrica mcp login --producao # the published site's Convex
npx rubrica mcp whoami # project, database, account and role
npx rubrica mcp logout
In Claude Code, you can type ! npx rubrica mcp login in the prompt itself. The token lives in ~/.config/rubrica/, outside the repository, one per project and per database (development and production have separate logins), and renews on its own.
Tip: for content work, sign in with a content-editor or blog-editor account. root only when needed.
What the agent can do
| Area | Examples |
|---|---|
| Account and environment | See the project, the database (development or production), the role, the plugins, the theme and the block catalog |
| Building pages | The site's real catalog (core blocks and your own, from src/blocks/), with when to use each block, what it pairs with and your theme's variants; the theme's recipes (the list of blocks of each standard page, like "About us" or "Services") |
| Site | Read and change settings (name, appearance, navigation, social links), turn plugins on and off, publish (triggers the build) |
| Pages and blocks | List, create (always as draft), change title, path and SEO; add, edit fields, move, hide and remove blocks |
| Collections | List, read, create (draft), edit, publish and remove posts, projects, services, testimonials, FAQ, résumé, team and plans |
| Proposals | List, read, create and edit commercial proposals (with an optional link password that is never returned in answers), with the proposals plugin on |
| Interface texts | See and customize texts per language |
| Media | List the library and upload images from a local path |
| Contacts | See requests and change the status (with the contact plugin on) |
There are also ready prompts (montar-pagina, traduzir-conteudo, revisar-antes-de-publicar) and read-only resources, like the writing guide, the block catalog and the recipes. montar-pagina starts from the theme's recipe when the page is of a known type and proposes the list of blocks before writing.
The MCP reads the theme installed in the project (the one in astro.config.ts) to know each block's variants: a variant the theme doesn't have is refused, with the list of the ones that exist.
The complete reference of tools, roles and variables is in docs/v2/mcp.md (in Portuguese).
Example: change the opening button in both languages
- The agent reads the page:
pages_get { "page": "/" }and finds theheroblock. - It calls
block_update_fieldswith the texts inpt-BRanden. A preview comes back with the before and after, and warnings (for example, "text filled inpt-BRand empty inen"). - You approve. The agent repeats the call with
dryRun: false.
Writing does not publish: the static site only changes at the next build. The agent only triggers publishing (site_publish) when you ask.
Security
- The server runs as your process, with the user's login and role. In production, always read the preview: the content changes immediately in the database.
- The MCP does not use
convex dev|deploy|run|import: only the project's public functions, with the user's role. - Tokens and passwords never appear in answers, resources or error messages.
- A proposal password is a tool argument (the backend stores only the hash) and goes through the conversation with the agent. If that is a concern, create the proposal without a password and set it in the panel.
- Image upload reads a local file (images only, checked by content). Restrict the agent's file system access if that is a concern.
Skills: the "how to write"
Skills hold the right way to write each thing and write through the MCP. They live in .agents/skills/ (with shortcuts in .claude/skills/):
| Request | Skill |
|---|---|
| Tone of voice, voice interview, the personal part of About | rubrica-voz |
| Presentation, "about me", home phrase, principles | rubrica-apresentacao |
| A project case study | rubrica-case |
| Résumé | rubrica-curriculo |
| A blog post from scratch | rubrica-blog |
| Review a text before it goes on the site | rubrica-pilar |
AGENTS.md
The project ships an AGENTS.md (and a CLAUDE.md that imports it) with the rules for any agent: what is content and what is code, which commands the agent runs and which belong to the person (setup, config, publicar, senha), the two databases and the care around anything that writes to production. Once created it is yours: update doesn't rewrite it, so adjust it freely.