Connecting an AI client
Once a version is published, a client that supports remote MCP over Streamable HTTP can connect to it, list its tools and call them. This page says how a client connects, which ones we have tested and what we haven't.
Before you start
- Publish a version. Agents read Production, not Draft. Until you publish, the endpoint returns no tools. If Production has no enabled tools, enable some in Build, then review and publish again.
- Decide how the client authenticates. A client access token for tools that use a service credential or no authentication. Per-user sign-in for tools that act as a user. See authentication.
The endpoint
Every project has an endpoint that Riviera serves. Open Access in your project to see its address and to create tokens. Copy the address exactly, including its path. The address of your own API is not the endpoint, and a client pointed at it will not find any tools.
An endpoint answers over remote MCP using Streamable HTTP. We haven’t tested stdio or the older SSE transport.
How a client connects
- In Access, choose how the client authenticates. For a machine client, create a client access token for this endpoint and copy it when it is shown. It is not shown again. For people signing in, configure user authorization first.
- The client connects to the endpoint address, with the token or the sign-in flow.
- The client asks for the tool list and receives Production’s tools, as that caller may run them.
- The client calls a tool. Riviera calls your API and returns the result, and the call is recorded.
Listing tools creates no tool call. Only a call that runs a tool is recorded.
Clients we have tested
| Client | Authentication tested | What was verified |
|---|---|---|
| Riviera’s Node recipe, using the official MCP TypeScript SDK 1.30.0 on Node 24.15.0 | A client access token, and per-user sign-in with authorization code and PKCE. | Connecting, listing the published tools and making explicit, confirmed calls. It is a developer client. It does not choose tools with a model. |
| ChatGPT, on a Plus plan | Per-user sign-in only. | Signing in at an authorization server, discovering tools and running read tools. The model that ChatGPT used was not visible to us. |
Other clients are not verified. A client that supports remote MCP over Streamable HTTP and one of the two authentication methods may work, but we haven’t tested it and don’t promise it. Clients, authorization servers and their interfaces change, so treat this table as a record of what we tested, not as a guarantee about today’s version of any product.
The Node recipe
The quickest check that an endpoint works is the recipe in your project. Open Access, choose Set up a client and pick the endpoint and how the client authenticates. The page lists the tools in Production, shows the configuration to use and gives you the client as a file to download.
npm install @modelcontextprotocol/sdk@1.30.0
node riviera-client.mjsSave the download as riviera-client.mjs in a new folder, install the pinned SDK in that folder, and read the file before you run it. Copy the configuration the page shows. It needs Node and npm.
- With no further options it connects and lists tools. Expect
Initializedand then a line saying how many published tools it listed. That confirms connection and discovery only. No tool has run yet. - A client access token is read from a hidden prompt. It is never placed in a command line, a file or a copied snippet.
- To call a tool, choose one that suits the access type, save its arguments in a local
arguments.jsonusing the input schema shown for Production, and run the call command the page gives you. It asks you to typeCALLbefore it runs once. Prefer a read operation, or a test environment, first. - For per-user sign-in, register the client at your authorization server with the exact redirect address the page shows. The recipe opens your server’s sign-in and keeps its grants in memory only, so restarting it signs in again.
ChatGPT
We connected ChatGPT to a Riviera endpoint using per-user sign-in. The steps depend on ChatGPT’s own interface for adding a custom connector, which changes, so follow its current documentation. What Riviera needs is the endpoint address, and an authorization server that meets the requirements for per-user OAuth with the client registered there.
Known quirk: ChatGPT showed a tool that only reads data under its write category, although the tool’s description said it reads. We record it here as observed behavior of the client.
ChatGPT was not tested with a client access token.
After you connect
Open Activity to see each call: its tool, the version that served it, the outcome and how long it took. A tool error is recorded as a failure and is never reported as success. If a connection fails after a call has started, the outcome can be unknown. Check your API’s state before you repeat a write.
Editing Draft does not change what connected clients see. They keep reading the published version until you publish again.
Troubleshooting
| What you see | What to check |
|---|---|
| The connection or the credentials are rejected | Use the exact endpoint address, including its path. A token only works for the endpoint it was created for. Create a replacement if it was revoked. |
| The client connects but lists no tools | Nothing is published, or Production has no enabled tools. Review and publish again. Also check that the access type can run the tools: a per-user sign-in does not list service tools, and a token does not list per-user tools. |
| Tools are listed but a call fails | Check the access type against the tool, then the tool's input against the schema in Production. Open Activity for the recorded outcome and, when your API answered with an error, its HTTP status. |
| Sign-in, consent or a refresh is rejected | Check the redirect address, the registered client, the issuer, the resource the token was requested for and the scopes at your authorization server. Whether the user was blocked or consent revoked also matters. |
| Calls stop before reaching your API | The workspace is at its monthly tool-call limit. It resets at the start of the next UTC month, or when the plan changes. |
| A setup that worked stops working | Authentication, configuration or your API's health may have changed. Check Activity first, then the credential and access settings. |
Known limitations
- Only the clients listed above were tested, with the authentication shown. We make no compatibility claim beyond them.
- The recipe is a developer client. It does not show how a model chooses between your tools.
- Tool selection by a model can be checked with model tests in Riviera, which don’t call your API.
- Stdio and SSE transports were not tested.
- One credential can’t unlock every tool: service, no-authentication and per-user tools need different access.
- Per-user sign-in needs an authorization server with the capabilities described in authentication.