MCP Server

Every Codenull application exposes a remote MCP (Model Context Protocol) server at:

POST https://MY_APPLICATION_DOMAIN/api/mcp

Through it, any MCP-compatible AI agent can explore your application (features, hooks, entities, menus, roles) and — depending on the permissions you grant — create and update configuration, running through the exact same resolvers, validations and audit trail as the visual builder.

1. Create an MCP API key

MCP access is authenticated with personal API keys (cnk_...), bound to your user and this application, with explicit scopes and an expiration date. Create one with a GraphQL mutation against https://MY_APPLICATION_DOMAIN/graphql (authenticated as your user):

mutation {
  createMcpApiKey(
    name: "Claude Code - my laptop"
    scopes: ["config:read", "features:write"]
    expiresInDays: 90
  ) {
    apiKey # shown ONLY once — store it securely
    key {
      _id
      keyPrefix
      scopes
      expiresAt
    }
  }
}

The apiKey value is returned only once. Codenull stores a hash and cannot recover it. Anyone holding the key can act as your user within its scopes — treat it like a password.

List your keys with the mcpApiKeys query and revoke one at any time with revokeMcpApiKey(_id: "...").

Scopes

Scope	Allows	Notes
`config:read`	Explore features, hooks, entities, menus, roles, env var names, GraphQL schema, authoring guides	Env var values are never exposed
`features:write`	Create/update features (standard and custom code)
`tables:write`	Create tables, update metadata, add fields
`menus:write`	Create/replace navigation menus
`hooks:write`	Create/update hooks	Admin-only grant. Hook code is server-side JavaScript executed by the backend — this scope is equivalent to code execution on your application. Grant it only to keys you fully control.
`roles:write`	Change which roles see each feature	Admin-only grant
`env:write`	Create/update environment variables	Admin-only grant
`config:delete`	Delete features/hooks (each call requires an explicit `confirm: true`)	Admin-only grant

Creating keys requires the AI Designer agent permission on your role. Effective permissions are re-evaluated on every request as the intersection of the key’s scopes and your current role permissions — if your user is disabled or demoted, the key stops working within a minute. Admin-only scopes (hooks:write, roles:write, env:write, config:delete) additionally require that the key’s user still is an admin at request time: losing the admin role deactivates those scopes immediately, even on existing keys.

2. Connect your agent

The key travels in the Authorization header. No OAuth flow is required. Name the server per application — codenull-<app-name> — so connecting several Codenull applications at the same time doesn’t collide on the name (the keys panel generates the snippets with this convention already). The examples below use codenull-myapp.

Claude Code
Claude Desktop
Cursor
Codex (CLI, app & IDE)
MCP Inspector

claude mcp add --transport http codenull-myapp https://MY_APPLICATION_DOMAIN/api/mcp \
  --header "Authorization: Bearer cnk_YOUR_KEY"

Claude Desktop’s custom connectors don’t support custom Authorization headers yet, so the connection goes through the mcp-remote stdio bridge (requires Node.js installed). Add to claude_desktop_config.json — on macOS at ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows at %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "codenull-myapp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://MY_APPLICATION_DOMAIN/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer cnk_YOUR_KEY"
      }
    }
  }
}

Then fully quit and reopen Claude Desktop — the tools appear under the tools icon. Passing the key via env (instead of inline in args) avoids a known mcp-remote bug on Windows with spaces in arguments.

Add to ~/.cursor/mcp.json (or the project’s .cursor/mcp.json):

{
  "mcpServers": {
    "codenull": {
      "url": "https://MY_APPLICATION_DOMAIN/api/mcp",
      "headers": {
        "Authorization": "Bearer cnk_YOUR_KEY"
      }
    }
  }
}

The Codex CLI, the Codex desktop app and the IDE extension all share the same MCP configuration in ~/.codex/config.toml. Add:

[mcp_servers.codenull-myapp]
url = "https://MY_APPLICATION_DOMAIN/api/mcp"
http_headers = { "Authorization" = "Bearer cnk_YOUR_KEY" }

To keep the key out of the file, you can reference an environment variable instead:

[mcp_servers.codenull-myapp]
url = "https://MY_APPLICATION_DOMAIN/api/mcp"
bearer_token_env_var = "CODENULL_MCP_KEY" # must contain the raw cnk_... key

Restart the desktop app (or the CLI session) after editing for the server to load.

codex mcp add only supports STDIO servers — for remote HTTP servers like this one, edit config.toml directly. Use the global ~/.codex/config.toml: the desktop app is known to ignore project-scoped .codex/config.toml files.

For debugging:

npx @modelcontextprotocol/inspector

Transport: Streamable HTTP, URL: https://MY_APPLICATION_DOMAIN/api/mcp, and add the Authorization header.

The server is stateless: only POST /api/mcp is served. Tools your key’s scopes don’t allow are not even listed. Claude.ai custom connectors currently require OAuth and are not yet supported — use Claude Code, or Claude Desktop through the mcp-remote bridge (tab above).

No extra setup, rules files or skills are needed on the agent side: the server ships its own playbook via the MCP instructions field during the connection handshake, so any compatible client (Claude Code, Cursor, Codex) automatically teaches its model the Codenull working method — explore first, read the authoring guide and schema, validate, then create.

3. Available tools

Discovery (config:read) — list_features, get_feature_details, list_hooks, get_hook_details, list_entities, get_entity_details, list_menus, list_roles, list_environment_variables, get_graphql_schema, get_feature_authoring_guide, validate_feature_code, validate_hook_code. Writing — create_feature / update_feature / edit_feature_code (features:write), create_hook / update_hook / edit_hook_code (hooks:write), create_table / update_table / add_table_field (tables:write), upsert_menu (menus:write), grant_feature_access (roles:write), set_environment_variable (env:write), delete_feature / delete_hook (config:delete, require confirm: true).

See what the agent changed, line by line. When modifying existing code, agents are instructed to use edit_feature_code / edit_hook_code, which take old_str/new_str patches — so the tool call itself shows exactly what changes. The server applies the patches to the current code, validates the result, persists it, and returns a unified diff of what was actually written (also returned by update_feature/update_hook when replacing code in full). If a patch doesn’t match the current code, the edit is rejected instead of overwriting the file with a stale version.

A typical flow the agent follows to create a custom feature:

get_feature_authoring_guide — learns the allowed modules (antd, Apollo hooks, dayjs…), the runtime rules, and your application’s configured theme (colors + shell CSS variables), used as the base palette when you don’t ask for specific colors — explicit color requests always take precedence.
get_graphql_schema + get_entity_details — learns your data model.
validate_feature_code — dry-run validation of the JSX (never executed server-side). Also returns informational warnings when the code uses fixed hex colors or Tailwind color classes (fine if you asked for them; otherwise the theme is the default).
create_feature — persists through the same resolver the builder uses (id validation, default permissions, versioning).

4. Usage examples

Once connected, you talk to your agent in natural language — it discovers and calls the MCP tools on its own. These are real prompts you can paste into Claude Code or Cursor, with the tool sequence the agent typically runs.

Explore an application you don’t know

“Connect to my Codenull app and give me an overview: what entities, features and hooks does it have?”

The agent calls list_entities, list_features and list_hooks, then summarizes your data model, screens and server-side logic. Requires only config:read.

Create a table and a screen for it

“Create a Cliente table with fields Nombre (text, required), Correo (text, unique) and FechaRegistro (date). Then build a screen to list and create clients, and add it to the side menu.”

Typical sequence:

get_entity_details on an existing table — to copy your field type conventions.
create_table — creates Cliente with the fields (tables:write).
get_feature_authoring_guide + get_graphql_schema — learns the runtime rules and the generated Cliente CRUD operations.
validate_feature_code then create_feature — a custom feature with an antd table + creation form wired to useQuery/useMutation (features:write).
upsert_menu — adds the /feature/clientes entry to the side menu (menus:write).

Add a validation hook

“Add a beforeSave validation on the Facturas table: reject any invoice whose Total is negative. Follow the same style as the existing hooks.”

Sequence: list_hooks + get_hook_details (to mimic your patterns) → validate_hook_code (syntax + rules dry-run) → create_hook with type: "beforeSave" and the table’s tableId. Requires hooks:write (admin-granted).

Modify an existing feature

“In the feature ventas_dashboard, add a date-range filter and a card with the month’s total.”

Sequence: get_feature_details (reads the current customCode) → validate_feature_code → update_feature. Updates run through the same versioning flow as the builder — pass status: "draft"/"published" if you use draft versions.

Grant access to a role

“Make the new Clientes screen visible to the Ventas role, plus Admin.”

Sequence: list_roles + list_features (to resolve ids) → grant_feature_access with the feature _id and the role ids (roles:write).

Calling the server without an agent (raw JSON-RPC)

The endpoint speaks standard MCP over Streamable HTTP, so you can also script it directly:

# List the tools your key can use
curl -s https://MY_APPLICATION_DOMAIN/api/mcp \
  -H "Authorization: Bearer cnk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call a tool
curl -s https://MY_APPLICATION_DOMAIN/api/mcp \
  -H "Authorization: Bearer cnk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_features",
      "arguments": { "query": "ventas" }
    }
  }'

Destructive tools (delete_feature, delete_hook) refuse to run unless the agent passes confirm: true — agents are instructed to ask you before confirming. If a tool you expect is missing from tools/list, your key lacks that scope (or you lost the role permission backing it).

Security model

Keys: 256-bit entropy, SHA-256 hashed at rest, mandatory expiry (max 365 days), revocable, lastUsedAt tracking. The cnk_ prefix makes leaked keys easy to detect with secret scanners.
Tenant isolation: each deployment serves one application; keys are bound to it and rejected elsewhere.
Attribution: every mutation records your user as the author, same as in the builder.
Audit: every tool call is logged (mcp_audit_logs) with redacted arguments — env var values and API keys never reach the log; long code payloads are stored as a preview plus SHA-256 hash. Entries are retained for one year.
Rate limits: 60 requests/minute per key; failed authentication is limited per IP. Limits are tracked per server instance, so with N replicas the effective ceiling is N× the stated value.
Payload limits: 2 MB per request, 200 KB per hook, 1 MB per feature code.
Prompt-injection guard: read-tool responses are wrapped with a note marking application content as data, not instructions.

hooks:write deserves special care: hook content is JavaScript executed by your application’s backend. A leaked key with this scope means remote code execution. Only admins can grant it, and every hook write is audited with a hash of the exact code persisted. Application owners receive an email notification on every hook creation and modification, whichever entry point was used (visual builder or MCP).

Get Started

Configurations

Agents

Environments

Reference

1. Create an MCP API key

Scopes

2. Connect your agent

3. Available tools

4. Usage examples

Explore an application you don’t know

Create a table and a screen for it

Add a validation hook

Modify an existing feature

Grant access to a role

Calling the server without an agent (raw JSON-RPC)

Security model

​1. Create an MCP API key

​Scopes

​2. Connect your agent

​3. Available tools

​4. Usage examples

​Explore an application you don’t know

​Create a table and a screen for it

​Add a validation hook

​Modify an existing feature

​Grant access to a role

​Calling the server without an agent (raw JSON-RPC)

​Security model

1. Create an MCP API key

Scopes

2. Connect your agent

3. Available tools

4. Usage examples

Explore an application you don’t know

Create a table and a screen for it

Add a validation hook

Modify an existing feature

Grant access to a role

Calling the server without an agent (raw JSON-RPC)

Security model