Enfyra MCP Server

Manage Enfyra instances from MCP-compatible coding tools such as Codex, Claude Code, Cursor, MCP Inspector, and other STDIO MCP hosts.

This package is the MCP bridge only. Assistant rules, schema behavior, dynamic script guidance, and examples are served through the MCP server itself from src/lib/mcp-instructions.js, src/lib/mcp-examples.js, and tool descriptions in src/mcp-server-entry.mjs.

Quick Start

From your project root:

npx @enfyra/mcp-server config

The config command writes project config for Codex, Claude Code, and Cursor. It preserves other MCP servers and replaces only the enfyra entry.

Interactive setup asks for your Enfyra app/admin URL, then guides you to the token page when needed and asks for ENFYRA_API_TOKEN.

# Non-interactive, all supported clients
npx @enfyra/mcp-server config --yes \
  --app-url http://localhost:3000 \
  -t efy_pat_your-token

# One or more clients
npx @enfyra/mcp-server config --codex
npx @enfyra/mcp-server config --cursor --claude-code

Equivalent in this repo:

yarn mcp:config

Choose A Client

Client	Command	Project config
Codex	npx @enfyra/mcp-server config --codex	.codex/config.toml
Claude Code	npx @enfyra/mcp-server config --claude-code	.mcp.json
Cursor	npx @enfyra/mcp-server config --cursor	.cursor/mcp.json
MCP Inspector / other hosts	Paste the shared STDIO config below	Host-specific mcpServers config

Codex setup

npx @enfyra/mcp-server config --codex

Generated project config:

[mcp_servers.enfyra]
command = "npx"
args = ["-y", "@enfyra/mcp-server"]

[mcp_servers.enfyra.env]
ENFYRA_API_URL = "http://localhost:3000/api"
ENFYRA_API_TOKEN = "efy_pat_your-token"

The writer replaces only [mcp_servers.enfyra] and [mcp_servers.enfyra.env]. Other Codex config and other MCP servers are preserved.

Open this folder in a new Codex session and approve the project MCP config if prompted. The setup command only writes .codex/config.toml; it does not ship or create .codex/skills.

Official reference: Codex config.

Claude Code setup

npx @enfyra/mcp-server config --claude-code

Project config is written to .mcp.json. MCP server definitions do not belong in .claude/settings.json.

Claude Code also supports its own CLI:

claude mcp add --transport stdio --scope project \
  --env ENFYRA_API_URL=http://localhost:3000/api \
  --env ENFYRA_API_TOKEN=efy_pat_your-token \
  enfyra -- npx -y @enfyra/mcp-server

Scope precedence when the same server name exists in multiple places is local, then project, then user. Project-scoped .mcp.json may require approval in Claude Code.

Official references: Claude Code MCP and Claude Code settings.

Cursor setup

npx @enfyra/mcp-server config --cursor

Cursor project config is written to .cursor/mcp.json. Global config is ~/.cursor/mcp.json on macOS/Linux or %USERPROFILE%\.cursor\mcp.json on Windows.

After edits, restart Cursor or reload MCP, then confirm the server under Cursor MCP settings. Use MCP logs if the server fails to start.

Official reference: Cursor MCP.

Other MCP hosts and MCP Inspector

Use the shared STDIO config with any host that accepts an mcpServers JSON block:

{
  "mcpServers": {
    "enfyra": {
      "command": "npx",
      "args": ["-y", "@enfyra/mcp-server"],
      "env": {
        "ENFYRA_API_URL": "http://localhost:3000/api",
        "ENFYRA_API_TOKEN": "efy_pat_your-token"
      }
    }
  }
}

ENFYRA_API_TOKEN is a programmatic token from the Enfyra admin UI /me. It is not a JWT; the MCP server exchanges it through POST {ENFYRA_API_URL}/auth/token/exchange before calling Enfyra REST APIs.

Official reference: MCP Inspector.

Config Command

npx @enfyra/mcp-server config [options]

Option	Use
--app-url	Set the Enfyra app/admin URL
--api-token, -t	Set ENFYRA_API_TOKEN
--yes	Non-interactive mode for CI/scripts
--global	Write global/user config instead of project config
--reconfig	Prompt for target clients again and replace the existing enfyra entry
--codex	Write Codex config
--claude-code, --claude	Write Claude Code config
--cursor	Write Cursor config
-h, --help	Show CLI help

Without a target flag, interactive mode asks which client to configure. Non-interactive mode defaults to all supported clients.

Environment

Variable	Description	Default
ENFYRA_APP_URL	App/admin URL used by setup	http://localhost:3000
ENFYRA_API_URL	Runtime API base written into MCP client config	Generated by setup
ENFYRA_API_TOKEN	Programmatic token from the Enfyra admin UI /me	Required

For normal apps and demos, enter the app/admin URL such as http://localhost:3000 or https://demo.enfyra.io. Treat the direct Enfyra backend host as private infrastructure unless you are debugging Enfyra core/server internals.

Common Examples

Use get_enfyra_examples from the MCP tool list when asking an LLM to generate implementation patterns. It returns focused examples for:

• SSR app auth and proxy setup
• OAuth provider setup
• schema, columns, relations, indexes, and validation
• query filters, sorting, fields, deep relations, and aggregates
• handlers, hooks, permissions, and RLS
• websocket gateways and events
• flows
• files and storage
• Enfyra admin extensions

Runtime Safety

The MCP server includes safety guards for LLM callers:

• Generic record mutations validate fields against live metadata.
• Script-backed records validate sourceCode through /admin/script/validate before saving.
• validate_dynamic_script checks handler, hook, flow, websocket, GraphQL, and bootstrap script source without saving.
• validate_extension_code checks Enfyra admin extension code through /enfyra_extension/preview without saving.
• compiledCode is generated from sourceCode and may differ textually because macros are expanded; the MCP server never accepts hand-written compiledCode.
• JSON responses include compressionStats with estimated token savings. Arrays of objects are converted to columnar form only when the compact shape is smaller than raw JSON.
• Relation tools reject physical FK/junction names and resolve table ids from exact table names or aliases before schema mutation.
• Generated code should use relation property names such as conversation, sender, and member instead of physical FK fields such as conversationId, senderId, or memberId.
• Custom route tools reject mainTableId unless the route is the canonical table route.
• Platform operation tools such as api_endpoint_workflow, create_api_endpoint, enable_route, disable_route, delete_route, public_route_methods, add_route_methods, set_table_graphql, ensure_guard, ensure_field_permission, ensure_column_rule, ensure_websocket_event, choose_flow_step_tool, fixed-type flow step tools, ensure_menu, ensure_page_extension, ensure_global_extension, and ensure_widget_extension resolve metadata ids and validate code before saving.
• Schema changes are serialized.
• Destructive deletes return a preview before requiring confirm=true.

Query Notes

Use explicit fields in read tools. Include mode is the default, such as fields=id,email. Any excluded field switches that scope to exclude mode: fields=-compiledCode returns all readable fields except compiledCode, and fields=id,-compiledCode still means all except compiledCode. Dotted exclusions such as fields=-owner.avatar work for relation fields when the relation exists in metadata. Every list/query call must pass either limit for a bounded page or all: true for a complete list. When a caller needs every matching row, pass all: true to query_table, get_all_routes, or get_all_tables; the tool should not choose an arbitrary page size like 30 or 50.

Enfyra URL Pattern

Generated apps should use a same-origin proxy:

export default defineNuxtConfig({
  routeRules: {
    "/enfyra/**": {
      proxy: {
        to: `${process.env.ENFYRA_API_URL}/**`,
        fetchOptions: { redirect: "manual" }
      }
    }
  }
})

Browser code then calls:

POST /enfyra/login
GET  /enfyra/me
POST /enfyra/logout
GET  /enfyra/<table>

Do not create custom login/logout/me routes that manually set Enfyra token cookies when the proxy is enough.

Tool Summary

The MCP server exposes tools for metadata discovery, examples, query/CRUD, method management, route lifecycle, route access audit/grant, routes, handlers, hooks, tables, columns, relations, cache reloads, logs, users, roles, packages, menus, extensions, scripts, flows, websocket, files, and get_enfyra_api_context.

Routes have two separate controls. isEnabled controls runtime registration: disabled routes return 404. Use enable_route and disable_route for this lifecycle. publicMethods controls anonymous access for enabled routes; use public_route_methods and private_route_methods for that access boundary.

Admin app page paths and API paths are different surfaces. A page extension path such as /cloud/projects/:id is a UI route unless an enabled Enfyra API route with that exact path exists. Use test_rest_endpoint only for actual API routes under ENFYRA_API_URL; verify page extensions through the app URL/browser or extension/menu metadata.

For authenticated route access, use audit_route_access before changing permissions and ensure_route_access to grant access by route path plus role/user. For production script edits, use trace_metadata_usage, get_script_source, and patch_script_source so changes are targeted, hash-checked, and validated.

Security

Treat permission and security as the first step for every change: decide public/private methods, authenticated route access, owner/tenant scope, and field exposure before creating handlers, flows, extensions, or UI.

API calls use exchanged JWTs and Enfyra permissions are still enforced server-side. Keep ENFYRA_API_TOKEN out of committed config unless the project intentionally uses environment interpolation or another secret-management path.