Skip to Content
🚀 We just launched! Please star us on Github!
DocumentationAdmin & ManagementModel Context Protocol

Model Context Protocol (MCP)

Smart Panel’s Model Context Protocol module lets trusted AI agents inspect and control one installation through a small, explicitly registered catalog. It is disabled by default, supports installation-local static credentials and an opt-in browser-mediated OAuth profile, and never turns the REST or OpenAPI surface into agent tools automatically.

Use static bearer credentials only on a trusted LAN or VPN. Remote OAuth access requires a canonical public HTTPS URL, a valid certificate, and an explicitly trusted reverse proxy. Do not enable OAuth on a direct, unencrypted backend listener.

The endpoint for an installation is:

https://<installation-host>/api/v1/modules/mcp

Choose an Authorization Profile

ProfileIntended networkAuthenticationOperational behavior
Static bearerTrusted LAN or VPNOne-time installation-local token copied to the agent hostFinite credential; rotate or revoke it from MCP clients
OAuthRemote access through public HTTPSBrowser login and explicit owner/administrator consentShort-lived access token; optional refresh; manage clients, grants, and token families

The profiles coexist and use separate credential types. Enabling, disabling, or revoking OAuth does not convert or invalidate static credentials. Disabling the complete MCP module closes both profiles.

Before You Begin

  • Sign in as an owner or administrator. Other roles cannot configure MCP or manage its clients.
  • Decide which agent and device will hold the credential. A credential is shown only once.
  • Start with read unless the agent genuinely needs to change device state.
  • Confirm the hostname identifies the intended Smart Panel installation before creating a client.

Enable MCP

Open the module configuration

Go to Config → Modules → Model Context Protocol in the Admin UI.

Choose the installation capability ceiling

Turn on Enable MCP endpoint, then select any combination of:

  • Read — inspect bounded home, device, history, energy, weather, and security context.
  • Write — discover writable properties and set a concrete device property.
  • Trigger — discover and run scenes or supported space-lighting actions.

An empty capability set is valid and exposes no tools or resources. The capability ceiling limits every client; a client can receive fewer capabilities, but never more.

Allow the endpoint hostname and any browser origin

Every request hostname must be loopback, the hostname configured by FB_APP_HOST, or the hostname of an entry in Allowed origins. If the copied LAN or reverse-proxy endpoint uses another hostname, either set FB_APP_HOST to that external HTTP(S) origin and restart the backend, or add the endpoint’s complete origin to Allowed origins. This hostname check also applies to server-side agents that send no Origin header.

For a browser-based client on another origin, also add the client’s exact normalized HTTP(S) origin, such as https://agent.example.com. Do not include a path, query, fragment, credentials, or wildcard.

Save and copy the endpoint

Save the configuration, then use Copy endpoint. Configuration changes apply immediately; a backend restart is not required.

write and trigger can affect physical devices. Before approving one of those tools, verify both the installation hostname and the installation name reported by the MCP server.

Create a Static Client Credential

Open MCP clients

Open MCP clients from the module’s Admin navigation and select Create client.

Name and restrict the client

Use a name that identifies the agent and host, for example Workshop Codex laptop. Select only the capabilities the client needs. The form prevents grants outside the current module ceiling.

Choose a finite lifetime

Set the credential lifetime in days. MCP credentials cannot be created without an expiry.

Copy the one-time token

After creation, copy the token immediately and place it in a password manager or the agent host’s secret store. The raw token cannot be retrieved after the dialog closes; Smart Panel stores only its normal token hash.

Capability Examples

Create separate clients when agents have different responsibilities.

Client profileGrantWhat it can doWhat it cannot do
Monitoring agentreadInspect context, device state, history, energy, weather, and securityChange properties or run actions
Direct device controllerwriteDiscover writable property metadata and set a propertyBrowse general state/history or run scenes
Automation runnertriggerDiscover trigger targets, run scenes, and set supported lighting modesBrowse general state or write a property directly
Trusted full-control agentread, write, triggerUse the complete curated catalogAccess arbitrary REST, configuration, users, files, or shell commands

For a new integration, begin with a read-only client. Add write or trigger only after reviewing the exact tools and the agent’s approval behavior.

Deploy Remote OAuth

OAuth is disabled by default. Complete the proxy and public-identity setup before enabling it.

Public URL and reverse-proxy requirements

The OAuth public base URL is the canonical external identity of this installation, not merely a proxy hint. It must be an absolute HTTPS URL without credentials, query, fragment, or trailing slash. Smart Panel derives the resource, issuer, authorization, token, revocation, and discovery URLs only from this stored value; Host, Forwarded, and X-Forwarded-* headers never choose the OAuth identity.

Use a dedicated public origin, such as https://panel.example.com, and preserve the complete request path when forwarding to Smart Panel. A path-prefixed public base URL is not supported: OAuth discovery can include the prefix, but the Admin router cannot complete the browser consent route beneath it.

The dedicated origin must forward the complete Smart Panel application, including these OAuth entry points:

PurposePublic and upstream path
MCP resource/api/v1/modules/mcp
Protected-resource discovery/.well-known/oauth-protected-resource/api/v1/modules/mcp
Authorization-server discovery/.well-known/oauth-authorization-server/api/v1/modules/mcp/oauth
Browser consent and Admin UI/mcp-oauth-consent and the Admin application’s routes/assets

The proxy must:

  • terminate TLS with a certificate trusted by every agent host;
  • preserve methods, query strings, response streaming, and browser cookies;
  • send X-Forwarded-Proto: https when it terminates TLS;
  • use long streaming timeouts and disable response buffering for the MCP resource; and
  • restrict the public routes with its normal firewall, rate limiting, and request-size controls.

If the proxy sends any Forwarded or X-Forwarded-* header, list its immediate socket IP address in the backend environment variable FB_MCP_OAUTH_TRUSTED_PROXIES. The value is a comma-separated list of individual IPv4 or IPv6 addresses; hostnames and CIDR ranges are not accepted.

FB_MCP_OAUTH_TRUSTED_PROXIES=172.18.0.2,127.0.0.1

Restart the backend after changing its environment. A request containing forwarded headers from any other immediate peer is rejected. Do not add a load balancer’s client-facing address when Smart Panel actually sees a sidecar or ingress address; trust only the address reported as the backend socket peer.

MCP also accepts forwarded headers from any peer the Remote access module already trusts — every Trusted proxies entry (while Trust forwarded headers is on) and every connected provider’s own proxy address, such as Tailscale Serve or Cloudflare Tunnel. These module contributions apply only while the module is enabled and the provider is connected. FB_MCP_OAUTH_TRUSTED_PROXIES stays useful for an operator who fronts Smart Panel with their own proxy but never enables the Remote access module; the two lists are additive, not exclusive.

Enable OAuth

Verify the public routes

Configure the proxy and confirm that the external MCP resource, both well-known paths, and browser consent route above reach the intended installation over HTTPS. Do not enable OAuth while DNS or certificates are incomplete.

Store the canonical identity

Go to Config → Modules → Model Context Protocol and set OAuth public base URL to the dedicated external origin, such as https://panel.example.com. If the Remote access module already has an HTTPS primary external URL — a connected Tailscale node, for example — Use remote access URL fills the field with it in one click. It only fills the field; it never saves or changes the stored value on its own, because changing it revokes every outstanding OAuth artifact.

Enable the complete profile

Turn on Enable MCP OAuth and save. Smart Panel reruns its readiness checks before opening the complete route set. A readiness failure keeps every OAuth route closed.

Changing the public base URL later revokes every OAuth artifact and closes OAuth subscriptions because it changes the resource and issuer identity. Static MCP clients remain active.

Pre-register an OAuth client

Open MCP OAuth access, select Pre-register OAuth client, and provide:

  • a name identifying the agent and device;
  • one or more exact redirect URIs; and
  • the maximum scopes the client may request: mcp:read, mcp:write, mcp:trigger, and optionally offline_access.

Smart Panel creates a public client ID, not a client secret. Redirect URIs must be absolute HTTPS URLs or HTTP loopback URLs. They match exactly, except that a 127.0.0.1 or [::1] loopback registration may use a different runtime port when its scheme, host, path, and query remain identical. localhost requires an exact port.

offline_access allows a consenting client to refresh access for at most 30 days. It is not a device capability and does not bypass the client, grant, or installation capability ceilings. Access tokens expire after 10 minutes.

Connect Codex with OAuth

Current Codex clients append a server-specific callback ID to their callback base. Configure a stable port in ~/.codex/config.toml:

mcp_oauth_callback_port = 41456

To discover the full callback URI safely, pre-register the client initially with http://127.0.0.1:41456/callback, copy its client ID, then add the server:

codex mcp add smart-panel \ --url https://panel.example.com/api/v1/modules/mcp \ --oauth-client-id '<client-id>' \ --oauth-resource https://panel.example.com/api/v1/modules/mcp codex mcp login smart-panel --scopes mcp:read,offline_access

The first authorization request is rejected because Codex appends a callback ID. Copy the full decoded redirect_uri from the browser’s authorization URL, edit the Smart Panel OAuth client, replace the temporary redirect with that exact URI, and run codex mcp login again. Never approve a redirect on another host or path.

The completed Phase 6 profile passed on Codex CLI 0.147.0. Use that release or a newer smoke-tested stable build and confirm codex mcp login --help lists --scopes. --oauth-resource is required for renewable access because it carries the canonical resource into refresh requests. The authorization URL may contain the same resource twice after discovery; Smart Panel accepts repeated identical indicators and still rejects any different resource. The older observed 0.136.0 client did not propagate the configured resource on refresh and received invalid_target from the strict token endpoint.

When offline_access is explicit and Codex omits an OAuth prompt, Smart Panel sends the request through its existing owner/admin consent interaction as prompt=consent. This does not broaden the requested scopes or bypass the configured client, grant, and module ceilings.

The ChatGPT desktop app, Codex CLI, and IDE extension on the same Codex host share this MCP configuration. Restart the app or extension after adding the server, then use /mcp or codex mcp list to verify it. See the official Codex MCP documentation  for current client controls.

Connect Claude Code with OAuth

Choose a fixed callback port and pre-register its exact loopback URI, for example http://localhost:41457/callback. Include offline_access in the client’s maximum scopes if Claude should refresh its access without another browser login. Add the public client with pinned capability scopes:

claude mcp add-json smart-panel \ '{"type":"http","url":"https://panel.example.com/api/v1/modules/mcp","oauth":{"clientId":"<client-id>","callbackPort":41457,"scopes":"mcp:read"}}'

Run Claude Code, enter /mcp, select smart-panel, and complete authentication in the browser. Claude Code adds offline_access when the server advertises it, so the pre-registered client ceiling must include that scope for the renewable profile. Use claude mcp get smart-panel to inspect the saved configuration. See the official Claude Code MCP documentation  for current installation scopes and OAuth options.

The consent page names the Smart Panel installation, requesting client, redirect destination, requested scopes, grant lifetime, and access-token lifetime. An owner or administrator must approve at least one MCP capability or deny the request. Treat write and trigger as physical access: they can change devices or run scenes. Approve offline_access only for a device that may retain renewable access.

A new client or redirect, a wider scope request, an expired/revoked grant, or a later authority change requires fresh consent. Resetting a Smart Panel password does not revoke existing OAuth grants; use MCP OAuth access to revoke the client, grant, access token, refresh family, or all OAuth access.

Migrate from a static credential

Do not paste a static bearer into an OAuth field or try to exchange it. The profiles are intentionally isolated:

  1. Leave the working static client enabled while deploying and testing HTTPS OAuth.
  2. Pre-register the remote agent as an OAuth client and complete browser consent with the minimum scopes.
  3. Verify discovery, tool listing, one expected tool call, and—if requested—refresh after the first access token expires.
  4. Revoke or delete the old static client only after the OAuth connection is proven.

Keep static credentials for trusted LAN/VPN agents if desired. Disabling OAuth revokes OAuth artifacts and closes only OAuth streams; it is the supported rollback when remote authorization must be withdrawn without interrupting static agents.

Protect Backups and Restored Installations

Smart Panel backups are not encrypted. Store and transfer them as credentials, restrict access, and securely remove obsolete copies after the retention period.

A complete backup contains the installation database and configuration directory. For MCP, that includes:

  • the installation UUID, static-client records and token hashes, and OAuth clients, grants, and artifact metadata in the database;
  • resolved write-only configuration secrets in config.yaml; and
  • .mcp-oauth-provider.json, containing the private OAuth signing key and interaction-cookie keys, after OAuth has first been activated.

Raw static and OAuth bearer values are stored only as hashes and cannot be recovered from the backup. The remaining identity, authorization, private-key, and configuration data is still security-sensitive.

Restore a replacement or create a clone

Decide whether the restored host replaces a failed installation or becomes a separate installation:

  • Replacement: Permanently retire or isolate the old host. A trusted backup preserves the installation identity and can preserve existing client access. Verify the public URL, TLS certificate, proxy trust, and known clients before reopening ingress. If the old host or backup may have been exposed, follow the compromise procedure below instead.
  • Separate clone: Keep the clone isolated from public ingress and MCP agent networks while recovering it. A database restore preserves the original installation UUID; do not run the original and clone concurrently with copied credentials.

Before exposing a separate clone:

  1. Assign its dedicated public origin and change OAuth public base URL. The identity change revokes copied OAuth grants and tokens and closes OAuth subscriptions.
  2. In MCP clients, rotate, revoke, or delete every copied static client. Copy replacement credentials only to agents intended for the clone.
  3. In MCP OAuth access, select Revoke all OAuth access, then disable copied OAuth clients that the clone should not accept.
  4. Complete fresh consent for every retained OAuth client and verify one minimum-scope tool call.
  5. Open public ingress only after old credentials fail against the clone and the original host can no longer answer for the clone’s public identity.

Revoke all and rotate OAuth server material

Revoke all OAuth access is the supported logical server-secret rotation. It advances the persistent authorization-server security epoch, revokes every grant, authorization code, access token, and refresh family, and closes every OAuth subscription before reporting success. Pre-registered public clients remain available for fresh consent, and static MCP credentials and streams remain active.

Use it after an unknown OAuth leak, owner/administrator compromise, risky restore, or before transferring an installation. Disabling OAuth also performs global OAuth invalidation, but leaves the remote profile closed until it is explicitly enabled again.

If the backup, Smart Panel host, or .mcp-oauth-provider.json itself was disclosed, also replace the cryptographic provider material:

  1. Isolate the host, revoke all OAuth access, and disable OAuth.
  2. Stop the backend. Never edit, remove, or replace provider material while it is running.
  3. Move .mcp-oauth-provider.json out of FB_CONFIG_PATH into access-controlled incident evidence, or securely remove it after evidence retention. Do not restore that file from a potentially exposed backup.
  4. Start the backend. Smart Panel creates new owner-only provider material when OAuth is next activated. It tightens permissions to 0600; malformed, incomplete, or symlinked material keeps OAuth fail-closed.
  5. Verify the public identity and proxy, enable OAuth, and require fresh browser consent. Rotate every other secret contained in the exposed configuration backup separately.

Respond to Credential or Account Compromise

Use the narrowest control that contains the known exposure:

ExposureImmediate action
One static bearerRotate that client credential; revoke or delete the client if it is no longer trusted
One OAuth access tokenRevoke that access token; it expires after at most 10 minutes
OAuth refresh token or one agent hostRevoke its refresh family and grant, or disable the OAuth client if all of its access is suspect
Unknown or installation-wide OAuth accessSelect Revoke all OAuth access
Backup, provider material, or backend hostIsolate the host, revoke all, replace provider material, rotate every static client and other copied configuration key
Owner or administrator accountRecover the account, revoke all OAuth access, rotate static clients, and remove or demote unknown administrative users

Preserve backend logs before cleanup. MCP audit events such as oauth_management, oauth_global_revocation, oauth_authorization_invalidation, and tool_execution identify actors, affected management IDs, and outcomes without recording raw bearer material.

Recover an owner or administrator account

Use the existing backend CLI to reset a privileged account when its Admin login cannot be trusted. On a pre-built image:

sudo smart-panel-service stop \ && sudo smart-panel-cli auth:reset <username> \ && sudo smart-panel-service start

Other installation methods must invoke the same auth:reset command through their backend CLI with the installation’s normal environment and database permissions. Stop every backend instance before invoking it and keep them stopped until the command reports success; this immediately closes live WebSocket sessions and prevents a concurrent login from creating new credentials during recovery. The command reads the replacement password from its masked terminal prompt; it never accepts the password as a command-line argument. Run it on a trusted local console.

The recovery command changes the password and revokes every active Admin login session and personal access token owned by that account before reporting success. Restarting the backend after that success cannot restore the disconnected sessions. The command deliberately does not revoke MCP OAuth grants, access tokens, refresh families, or static MCP credentials. After signing in, select Revoke all OAuth access, rotate every static client that the compromised account could have created or copied, review the registered clients and grants, and remove or demote unknown users. Demoting or deleting an approving owner/administrator automatically revokes grants that user approved, but it is not a substitute for global revocation when the exposure is uncertain.

Connect an Agent

The client must support Streamable HTTP and either a preconfigured bearer token or standards-based OAuth. Stdio-only, legacy HTTP+SSE-only, and persistent-session-only remote clients are not supported.

Codex CLI, app, or IDE extension with a static bearer

Keep the token in an environment variable available to the Codex process:

export SMART_PANEL_MCP_TOKEN='<copied-mcp-token>' codex mcp add smart-panel \ --url https://panel.example.lan/api/v1/modules/mcp \ --bearer-token-env-var SMART_PANEL_MCP_TOKEN

Confirm that the configuration entry exists:

codex mcp list

This command does not contact the endpoint. Start a Codex session and ask it to list the Smart Panel tools or call a read tool such as get_home_context; a successful tool list or call verifies endpoint reachability and authentication.

The Codex app, Codex CLI, and Codex IDE extension share the same local MCP configuration. Restart the app or extension after adding the server, then complete the connectivity check before approving tools.

The equivalent ~/.codex/config.toml entry is:

[mcp_servers.smart_panel] url = "https://panel.example.lan/api/v1/modules/mcp" bearer_token_env_var = "SMART_PANEL_MCP_TOKEN"

Other static-bearer agents

Configure a Streamable HTTP server with the copied endpoint and this request header:

Authorization: Bearer <copied-mcp-token>

Use the client’s secret or environment-variable support instead of committing the token to a repository. Claude Code and the official MCP TypeScript SDK have been verified with bearer-authenticated Streamable HTTP.

Curated Catalog

Only the following tools and resources are registered. Smart Panel does not convert OpenAPI operations into MCP tools, and enabling MCP does not grant access to arbitrary REST requests, SQL, files, configuration, extensions, users, backups, updates, restarts, reboots, or power controls.

Read tools

ToolPurpose
get_home_contextReturn a bounded installation or space overview
get_device_stateReturn one device with channels and current property values
get_property_timeseriesReturn bounded, downsampled history for one property
get_energy_summaryReturn a home or space energy summary
get_weatherReturn current conditions and a short forecast
get_security_statusReturn security state and bounded active alerts

Read resources are smart-panel://installation, smart-panel://home/context, and the smart-panel://spaces/{spaceId}/snapshot resource template. They are available only when read is effective.

Write tools

ToolPurpose
list_writable_propertiesReturn bounded identifiers and validation metadata needed for direct writes
set_device_propertySet one currently available, writable property

list_writable_properties belongs to the write capability even though discovery itself does not mutate state. This allows a write-only client to identify a safe target without gaining general read access.

Trigger tools

ToolPurpose
list_trigger_targetsReturn bounded enabled scenes and lighting-capable spaces
run_sceneRun one enabled scene
set_space_lightingApply a supported lighting mode to one space

set_space_lighting is advertised only when its optional provider is installed and available.

Rotate, Restrict, Revoke, or Delete a Client

  • Edit a client to reduce its capabilities. Active clients are notified and new operations use the reduced grant immediately.
  • Rotate when a token may have leaked or when moving an agent to a new host. The previous credential is revoked immediately, active streams are closed, and the replacement token is shown once.
  • Revoke to disable the current credential immediately. Connected streams for that client are closed.
  • Delete to revoke the credential and permanently remove the client record.

Changing the module capability ceiling applies to every client immediately. Disabling the module closes active MCP streams and makes the endpoint return 404 until it is enabled again.

Troubleshooting

The endpoint returns 404

The MCP module is disabled. Enable it under Config → Modules → Model Context Protocol and save.

The client receives 401 Unauthorized

Check that the client sends the MCP token as a bearer credential, the token has not expired or been rotated/revoked, and the credential belongs to this installation. User access tokens, personal access tokens, and display tokens do not work on the MCP endpoint.

For OAuth, confirm the public URL has not changed, the client is still enabled, the grant and token are active, and the agent is using the OAuth profile rather than a static bearer from another client.

The client receives 403 Forbidden

Smart Panel rejected the request’s Host or browser Origin. Ensure the endpoint hostname is loopback, matches the hostname in FB_APP_HOST, or belongs to an origin in Allowed origins. For a cross-origin browser client, add its exact normalized origin too. Do not use a wildcard.

For OAuth discovery or token requests behind a proxy, also confirm that the immediate proxy IP is listed in FB_MCP_OAUTH_TRUSTED_PROXIES. Smart Panel rejects every forwarded header from an untrusted peer.

Use a dedicated public origin without a path prefix. Confirm that the proxy forwards /mcp-oauth-consent and the Admin application’s routes and assets, in addition to the MCP resource and both well-known metadata paths.

The browser reports a redirect mismatch

Compare the complete runtime redirect_uri with the OAuth client’s registered value, including scheme, IP literal or hostname, path, query, and callback suffix. Only the runtime port may vary for 127.0.0.1 and [::1] registrations.

The client connects but shows no tools

Both the module and the client need the relevant capability. An enabled module or client with no capabilities is valid and intentionally advertises an empty catalog. set_space_lighting also requires its optional provider.

The one-time token was not saved

It cannot be recovered. Rotate the credential and copy the replacement token, or delete the client and create a new one.

A configuration change is not visible

Reconnect clients that do not consume MCP list-change notifications. Authorization is still rechecked for every tool execution, so a stale client cannot keep using a removed capability.

Upgrade Notes

Existing installations receive MCP through the incremental 1000000000008-AddMcpClients migration. Migrations run automatically during a normal update and create the installation identity and MCP client tables; no existing user, personal-access-token, display-token, or device records are converted.

The new configuration defaults are safe and do not expose an upgraded installation:

modules: mcp-module: enabled: false capabilities: - read allowed_origins: []

Back up the database and configuration before updating. After the update, an owner or administrator must explicitly enable MCP and create each finite-lived client credential. If an operator explicitly reverts this migration during a rollback, its down migration deletes MCP-owned credentials before older authentication code can load them.

What’s Next?

Last updated on