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/mcpChoose an Authorization Profile
| Profile | Intended network | Authentication | Operational behavior |
|---|---|---|---|
| Static bearer | Trusted LAN or VPN | One-time installation-local token copied to the agent host | Finite credential; rotate or revoke it from MCP clients |
| OAuth | Remote access through public HTTPS | Browser login and explicit owner/administrator consent | Short-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
readunless 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 profile | Grant | What it can do | What it cannot do |
|---|---|---|---|
| Monitoring agent | read | Inspect context, device state, history, energy, weather, and security | Change properties or run actions |
| Direct device controller | write | Discover writable property metadata and set a property | Browse general state/history or run scenes |
| Automation runner | trigger | Discover trigger targets, run scenes, and set supported lighting modes | Browse general state or write a property directly |
| Trusted full-control agent | read, write, trigger | Use the complete curated catalog | Access 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:
| Purpose | Public 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: httpswhen 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.1Restart 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 optionallyoffline_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 = 41456To 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_accessThe 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.
Review consent
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:
- Leave the working static client enabled while deploying and testing HTTPS OAuth.
- Pre-register the remote agent as an OAuth client and complete browser consent with the minimum scopes.
- Verify discovery, tool listing, one expected tool call, and—if requested—refresh after the first access token expires.
- 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:
- Assign its dedicated public origin and change OAuth public base URL. The identity change revokes copied OAuth grants and tokens and closes OAuth subscriptions.
- In MCP clients, rotate, revoke, or delete every copied static client. Copy replacement credentials only to agents intended for the clone.
- In MCP OAuth access, select Revoke all OAuth access, then disable copied OAuth clients that the clone should not accept.
- Complete fresh consent for every retained OAuth client and verify one minimum-scope tool call.
- 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:
- Isolate the host, revoke all OAuth access, and disable OAuth.
- Stop the backend. Never edit, remove, or replace provider material while it is running.
- Move
.mcp-oauth-provider.jsonout ofFB_CONFIG_PATHinto access-controlled incident evidence, or securely remove it after evidence retention. Do not restore that file from a potentially exposed backup. - 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. - 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:
| Exposure | Immediate action |
|---|---|
| One static bearer | Rotate that client credential; revoke or delete the client if it is no longer trusted |
| One OAuth access token | Revoke that access token; it expires after at most 10 minutes |
| OAuth refresh token or one agent host | Revoke its refresh family and grant, or disable the OAuth client if all of its access is suspect |
| Unknown or installation-wide OAuth access | Select Revoke all OAuth access |
| Backup, provider material, or backend host | Isolate the host, revoke all, replace provider material, rotate every static client and other copied configuration key |
| Owner or administrator account | Recover 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 startOther 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_TOKENConfirm that the configuration entry exists:
codex mcp listThis 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
| Tool | Purpose |
|---|---|
get_home_context | Return a bounded installation or space overview |
get_device_state | Return one device with channels and current property values |
get_property_timeseries | Return bounded, downsampled history for one property |
get_energy_summary | Return a home or space energy summary |
get_weather | Return current conditions and a short forecast |
get_security_status | Return 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
| Tool | Purpose |
|---|---|
list_writable_properties | Return bounded identifiers and validation metadata needed for direct writes |
set_device_property | Set 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
| Tool | Purpose |
|---|---|
list_trigger_targets | Return bounded enabled scenes and lighting-capable spaces |
run_scene | Run one enabled scene |
set_space_lighting | Apply 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.
The browser consent page is not found
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?
- Configuration — manage core module settings
- Users & Roles — understand owner and administrator access
- Updating & Backup — back up the installation before an upgrade