How to connect a custom MCP client

Use this guide to connect any MCP client that is not covered by a dedicated guide, including a client you build yourself. The client must support remote MCP servers over Streamable HTTP and OAuth 2.0 with PKCE. You need a Port OS account with at least one connected device.

Connection details

Enter this server URL:

MCP server URL

https://api.portoperatingsystem.com/mcp

Then use these settings:

Setting	Value
Transport	Streamable HTTP
Authentication	OAuth

A cloud-hosted client needs this public HTTPS endpoint. Use a localhost URL only with a client that runs on your own computer.

1. Add the server in your client

Open your client's MCP or integration settings and add a server named Port OS. Choose Streamable HTTP, paste the server URL above and choose OAuth. If your client is configured with a file, it usually takes an entry like this:

MCP client configuration

{
  "mcpServers": {
    "portos": {
      "url": "https://api.portoperatingsystem.com/mcp"
    }
  }
}

2. Let the client discover OAuth

Port OS publishes standard OAuth discovery, so a compliant client needs no other setting:

The client sends a request to the server URL. Port OS answers with a WWW-Authenticate header that points to its protected-resource metadata.
The client reads that metadata (/.well-known/oauth-protected-resource/mcp) and finds the authorization server.
The client reads the authorization server metadata (/.well-known/oauth-authorization-server) for the authorization, token and registration endpoints.

The client must send the MCP resource it discovered when it starts authorization, so the token it receives is valid for MCP. A token issued for the REST API does not work on MCP, and the reverse.

3. Register the client

Port OS needs to know your client before it shows a consent page. Use the first method your client supports:

Client ID metadata document (CIMD). The client uses an HTTPS URL it hosts as its client ID, and Port OS fetches the document at that URL. Nothing is copied.
Dynamic client registration (DCR). The client registers itself with the registration endpoint from the authorization server metadata. Nothing is copied.
A registered client. If your client supports neither, register an OAuth client on the clients page. Enter the client ID and, if shown, the secret in your client, and add its redirect URL when you register.

Use the redirect URL your client documents. Port OS only returns the user to a redirect URL that matches the registration.

Connect the server from your client. A Port OS authorization window opens. Sign in with the Port OS account that owns your devices, check that the requesting client is the one you expect, review the permissions and click Allow. You can uncheck permissions you do not want to grant; the matching features will be unavailable.

5. Check your devices

Ask the client to list your Port OS devices and compare the names with Your Devices. Try a read, such as the state of one light, before you request a device change.

Troubleshooting

If the client reports a missing registration, it supports neither CIMD nor DCR. Register a client on the clients page instead.
If authorization succeeds but calls fail with an invalid_target or audience error, the client authorized the wrong resource. Authorize again using the resource from the protected-resource metadata.
If the redirect fails, the redirect URL differs from the one registered for the client.
If devices are missing, confirm you signed in to the same account as Your Devices and that the connection has permission to read them.