How to connect Codex

Connect Codex to your Port OS devices using a remote MCP server and OAuth. You need a Port OS account with at least one connected device and a Codex client that supports Streamable HTTP MCP servers.

Connection details

Enter this server URL:

https://api.portoperatingsystem.com/mcp

Then use these settings:

1. Add Port OS

In the desktop app or IDE extension, open Settings → MCP servers → Add server. Name the server Port OS, choose Streamable HTTP, and paste the server URL above. Save and restart the MCP connection, then choose Authenticate when prompted.

If you use the Codex CLI, add the cloud server from your terminal:

codex mcp add portos --url https://api.portoperatingsystem.com/mcp
codex mcp login portos

Codex stores user MCP configuration in ~/.codex/config.toml. The CLI, desktop app and IDE extension share the configuration on the same host. You can instead add this table to that file, keeping your existing servers:

[mcp_servers.portos]
url = "https://api.portoperatingsystem.com/mcp"

Then run codex mcp login portos to authenticate. You do not need a Google client ID, a client secret, or a Port OS access key for this flow.

2. Sign in and approve access

Complete sign-in in the browser opened by Codex. Review the requested scopes and target-device permissions on the Port OS consent page before choosing Allow. Keep the Codex client running until the browser callback completes.

Port OS supports OAuth discovery and client registration. Codex can register its client automatically; do not copy another application's OAuth credentials into the configuration.

3. Verify the connection

Run codex mcp list, or use /mcp in the Codex terminal conversation, to check the server. Start a conversation and ask “Use Port OS to list my devices.” Compare the names with Your Devices.

Try a read such as “What is the current state of my bedroom light?” before requesting a device change. The tools available to Codex depend on the permissions you approved and the capabilities advertised by each device.

Troubleshooting

• If authentication is required, run codex mcp login portos again and finish the browser consent flow.
• If no devices appear, confirm you signed in to the same Port OS account as Your Devices and that it has connected devices.
• If an operation is denied, review scopes and resource permissions; a connected server does not automatically have permission to operate every device.
• For a remote Codex host, complete the callback flow supported by that host. A localhost URL refers to the host running the MCP client, so use the public cloud server URL above.

References

1. Official Codex MCP configuration and OAuth instructions
2. Port OS authentication guide