MCP server setup

The OpenApp MCP server lets coding and operator agents discover organizations and entities, resolve doors by name, inspect audit and policies, and — with explicit opt-in — run controlled writes (propose_action / confirm_action, invites). Hosted MCP never exposes scripting_execute.

Source: packages/openapp-mcp (@openapp/mcp-server on npm) and the hosted JSON-RPC endpoint POST /api/v1/mcp.

Hosted MCP (OAuth)

Production agents should use the remote server:

• URL: https://mcp.openapp.house (proxied as POST /api/v1/mcp on the API host)
• Auth: OAuth client openapp-mcp (Hydra). Use client credentials for a named Agent principal, or an authorization-code user consent flow.
• Org: send X-Org with every call.
• Protected-resource metadata: /.well-known/oauth-protected-resource

Trimmed OpenAPI for Custom GPTs: openapp-openapi-agent.json (resolve, preview/execute, invites, audit — not the full spec).

Environment variables (local stdio / HTTP)

Variable	Required	Description
OPENAPP_API_KEY	Yes	API key (Authorization: Bearer), preferably an Agent credential
OPENAPP_API_BASE	No	Default https://api.openapp.house/api/v1
OPENAPP_ORG_ID	For device/entity/audit lists and all writes	Organization ULID (X-Org)
OPENAPP_MCP_ALLOW_WRITES	For write tools	Set to 1 only after org policy review
OPENAPP_MCP_ALLOW_SCRIPTING	Local stdio only	Set to 1 and writes enabled to expose openapp_scripting_execute. Ignored on hosted MCP and openapp-mcp-http.

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

Read tools

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_resolve	POST /orgs/{id}/resolve
openapp_list_audit_events	GET /orgs/{id}/audit/events (30-day hot window; requires OPENAPP_ORG_ID)
openapp_list_policies	GET /orgs/{id}/policies
openapp_list_webhooks	GET /orgs/{id}/webhooks
openapp_list_invites	GET /integrations/{id}/access-invites
openapp_describe_action	Static catalog + OpenAPI pointer
openapp_propose_action	POST /entities/{id}/actions/{action_id}/preview

Write tools (opt-in)

Disabled unless OPENAPP_MCP_ALLOW_WRITES=1 (hosted MCP still enforces Cedar, confirmation mode, and agent tool allow-lists).

Tool	Maps to	Guardrails
openapp_confirm_action	POST /entities/{id}/actions/{action_id} + X-OpenApp-Confirm	Two-phase physical write
openapp_execute_entity_action	Same action surface; optional Idempotency-Key	Prefer propose then confirm
openapp_create_invitation	POST /integrations/{id}/access-invites	valid_from / valid_to required
openapp_revoke_invite	POST /integrations/{id}/access-invites/{id}/revoke	Operator job
openapp_audit_export	POST /orgs/{id}/audit/exports	Kickoff only
openapp_scripting_execute	POST /scripting/execute	Local stdio only with OPENAPP_MCP_ALLOW_SCRIPTING=1

See Agent-relevant API and Query access and audit activity.

npm / local stdio

npx -y @openapp/mcp-server

From the repository:

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

Local streamable HTTP (no scripting):

OPENAPP_API_KEY='…' OPENAPP_ORG_ID='…' npm run start:http

Cursor mcp.json example

{
  "mcpServers": {
    "openapp": {
      "command": "npx",
      "args": ["-y", "@openapp/mcp-server"],
      "env": {
        "OPENAPP_API_BASE": "https://api.openapp.house/api/v1",
        "OPENAPP_API_KEY": "<agent credential from dashboard>",
        "OPENAPP_ORG_ID": "<ulid>"
      }
    }
  }
}

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

Installable job skills (STR checkout, guest invite, audit investigation) live in packages/openapp-skills/ and .cursor/skills/.

Safety

• Read-only tools still reveal org structure and recent audit events — 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