MCP server setup

The OpenApp MCP server lets coding agents discover organizations, devices, and entities, and — with explicit opt-in — run controlled writes (entity actions, invites, scripting).

Source: packages/openapp-mcp in the OpenApp repository (README.md in that package).

Environment variables

Variable	Required	Description
OPENAPP_API_KEY	Yes	API key (Authorization: Bearer)
OPENAPP_API_BASE	No	Default https://api.openapp.house/api/v1
OPENAPP_ORG_ID	For device/entity lists and all writes	Organization ULID (X-Org)
OPENAPP_MCP_ALLOW_WRITES	For phase 2 tools	Set to 1 only after org policy review

Never commit keys to mcp.json — use env vars or your client’s secret store.

Phase 1 tools (read-only)

Tool	Maps to
openapp_list_orgs	GET /orgs
openapp_list_devices	GET /devices
openapp_list_entities	GET /entities
openapp_get_entity	GET /entities/{id}
openapp_describe_action	Static catalog + OpenAPI pointer

Phase 2 tools (opt-in writes)

Disabled unless OPENAPP_MCP_ALLOW_WRITES=1.

Tool	Maps to	Guardrails
openapp_execute_entity_action	POST /entities/{id}/actions/{action_id}	Physical effect; require explicit action_id
openapp_create_invitation	POST /integrations/{id}/access-invites	valid_from / valid_to required
openapp_scripting_execute	POST /scripting/execute	Provisioning only; role-gated on API

See Agent-relevant API.

Build and run locally

From the repository root:

cd packages/openapp-mcp
npm install
npm run build
OPENAPP_API_KEY='v1_openapp_…' OPENAPP_ORG_ID='01H…' npm start

For write tools:

OPENAPP_MCP_ALLOW_WRITES=1 OPENAPP_API_KEY='…' OPENAPP_ORG_ID='…' npm start

Cursor mcp.json example

Use an absolute path to the built entrypoint on your machine:

{
  "mcpServers": {
    "openapp": {
      "command": "node",
      "args": ["/path/to/openapp2/packages/openapp-mcp/dist/index.js"],
      "env": {
        "OPENAPP_API_BASE": "https://api.openapp.house/api/v1",
        "OPENAPP_API_KEY": "<from-dashboard>",
        "OPENAPP_ORG_ID": "<ulid>"
      }
    }
  }
}

Add "OPENAPP_MCP_ALLOW_WRITES": "1" only when operators approve physical actions from agents.

Package publication as @openapp/mcp-server on npm is planned; until then, build from source.

Safety

• Read-only tools still reveal org structure — scope API keys minimally.
• Write tools unlock doors, create guest links, or run scripts — keep human in the loop in agent UIs.
• Physical unlocks: Build an access-control agent.

---

← go2rtc live view · Agents overview