How to use MCP
Connect your AI to Port OS with MCP (Model Context Protocol).
Prerequisites
- A Port OS account.
- An AI client that supports remote MCP servers and OAuth sign-in.
- A connected device or a simulator light to test.
1. Add the MCP server
Open your AI client's MCP connector page. Enter this server URL:
https://api.portoperatingsystem.com/mcpChoose Streamable HTTP if the client asks for a transport.
If your AI client asks you to set up a client yourself, use dynamic client registration (DCR) or client ID metadata documents (CIMD). Both let your AI client register itself, with nothing to copy. If your client supports neither, register an OAuth client on the clients page and enter its details in your AI client.
2. Authorize your AI
Click your AI client's Connect button and sign in to your Port OS account.
Review the permissions and grant the access you want your agent to have. For example, you can let the agent list devices without letting it control them.
3. Test the connection
Ask your AI to list your connected devices. Then, if you granted control access, try:
Turn off the simulator light via @Port OS.
Use the name of your test light. Check that its state changes to off.
Congratulations!
Your AI is now connected to Port OS with MCP.
What your AI can do
Control devices
Turn off lights, play music, run the vacuum, or set the thermostat.
List your devices
Ask which devices you have and what each one can do.
Manage your devices
Rename, merge, disable, or delete devices.
Work with groups
List your groups, then rename, merge, disable, or delete them.
Connection problems
| Problem | What to check |
|---|---|
| Sign-in is requested again | Reconnect using the client's authorization flow. The previous access may have expired. |
| Access is denied | Check the account and endpoint access rules. |
| No matching devices | Check Your devices and see if the device is there. Connect the provider if the device is missing there too. |
| A command is rejected | Check the device's declared messages and payload schema in the capability reference. |
| Device state is unavailable | Check that the device is online and plugged in, and that the provider connection is stable. |
Next steps
Add real devices
Connect a provider to control your own devices.
Add a simulator light
No device yet? Test with a simulator.
AI connection guides
Connect ChatGPT, Claude, Muse, Grok, Codex or a custom MCP client.
MCP reference
Every MCP tool, what it does and the scope it needs.
Task guides
Task guides your AI reads as MCP resources.
Skills
The connected-home skill for clients that only support tools.
Verify a device action
Check a command's result against fresh device state.
Event subscriptions
Let your AI react when something happens at home.
REST API
Use the REST API for non-MCP integrations.