Connecting to MCS
This guide is for MCS consultants and customer IT teams setting up the link between Rent Stream AI and an MCS system.
How Rent Stream AI talks to MCS
There are three links. Rent Stream AI makes the first two calls; MCS makes the third.
| Link | Direction | What it is for | How it is secured |
|---|---|---|---|
| MCS-connect | Rent Stream AI calls MCS | Reading: who a sender is, depots, purchase orders, anything a Look up in MCS step asks for | A login sent with every call (recommended) |
| XML gateway | Rent Stream AI calls MCS | Creating records, and filing documents against them | The gateway's own private address |
| Webhook | MCS calls Rent Stream AI | MCS confirms a record was created, with its number, or says why it was not | An API key sent by MCS |
Rent Stream AI ── reads (MCS-connect, HTTPS GET) ──────────────► MCS
Rent Stream AI ── creates (XML gateway, HTTPS POST) ───────────► MCS
Rent Stream AI ◄── confirms (webhook, HTTPS POST + API key) ──── MCS
A record only counts as created when the webhook confirms it. Rent Stream AI never sends the same record to the gateway twice by itself.
Before you start
| You need | Notes |
|---|---|
| MCS with MCS-connect running and licensed | Rent Stream AI reports "MCS-connect is not licensed on this MCS site" if not |
| The MCS-connect address, reachable from the internet over HTTPS | Rent Stream AI runs on Cloudflare and calls MCS over the public internet. Addresses must start https://. Cloudflare has no fixed outgoing IP addresses, so the link cannot be locked to an IP allow-list |
| The XML gateway address for the MCS system | Over HTTPS. The address contains a unique code that acts as its key: treat it as a secret |
Outgoing HTTPS from MCS to rentstream.onmcs.ai | For the webhook |
| Someone who can run SQL scripts on the MCS database | To install the endpoints and the webhook subscription |
| An admin in Rent Stream AI with Manage the MCS connection | To enter the connection details and download the scripts |
Live and test
Settings, MCS connection has a Live tab and a Test tab, each with its own addresses, login, webhook address and key.
- Workflows always use the live connection: lookups, Identify the contact, Create in MCS and File in MCS, including the workflow Test tab.
- The test connection is used for Check connection, Try it on an endpoint, and its own install script, so you can try endpoints on an MCS test system first.
Step 1: Choose a login for MCS-connect
Decide how MCS-connect checks who is calling. The same choice is written into MCS by the install script, so the two always match.
| Choice | What it means |
|---|---|
| Fixed login, sent in headers | Recommended. Rent Stream AI's own login name and password, sent with every call in the UID and PWD headers, never in the address |
| Fixed login, sent in the address | Works, but the password is part of every address, and MCS-connect writes addresses to its logs |
| None | Anyone who finds the address can read what Rent Stream AI's endpoints return. Check warns while it is like this |
| The site default | Whatever the MCS-connect site is set to. When nothing is set, that is no login at all |
Choose the login name and password yourself. They are created in MCS by the install script, not taken from an existing MCS user.
Step 2: Enter the MCS-connect details
In Settings, MCS connection, on the Live tab, under MCS-connect:
- MCS-connect address: the https address, with no login or
?in it. - How MCS-connect checks who is calling: your choice from step 1.
- Login name and Password, for a fixed login.
- Select Save changes.
The login is stored encrypted. Afterwards only its last characters are shown.
Step 3: Install the endpoints on MCS
Rent Stream AI reads MCS only through its own endpoints: read-only queries registered
in MCS-connect under the category RentStream.
- Go to Settings, MCS endpoints and select Download install script (live).
- Run the script on the MCS database, as a user allowed to write to it.
- Delete the file once it has run. It contains the MCS-connect login.
What the script does:
- Creates each Rent Stream AI endpoint in MCS-connect if it is missing, and updates it to match if it is there. It never deletes anything, so it is safe to run again.
- Sets every Rent Stream AI endpoint to use the login from step 1.
- Runs as one transaction: either everything is installed or nothing is.
It includes the standard endpoints (Describe, GetDepots, FindContact) and every endpoint your company has added. Every query is checked to make sure it only reads data before the script can be built.
Run the script again whenever you add or change an endpoint, or change the login.
Step 4: Check the connection
Select Check connection. Rent Stream AI calls the RentStream/Describe endpoint,
which returns a fingerprint of each installed endpoint's query (never the query or any
data), and compares them with its own:
| Status | Means |
|---|---|
| Installed | In MCS and up to date |
| Missing | Not in MCS. Run the install script |
| Different | In MCS, but not the latest. Run the install script again |
| Login refused | MCS refused the login. Check the login and that the script has been run |
| Open without login | The endpoint answered with no login. Anyone who finds the address could read it. Use a fixed login |
| Not checked | No check has been run yet |
Rent Stream AI also tries each check once with an empty login, which is how it finds endpoints that are open without one.
Then go to Settings, Depots and select Sync from MCS to bring in your depots.
Step 5: Enter the XML gateway address
Under XML gateway and webhook, enter the Gateway address and select Save changes. It must use https. Once saved, only the start of the address and its last characters are shown.
Rent Stream AI posts each record to this address as XML, built from MCS's own message definitions. MCS replies with a job reference, and the record is shown as Accepted by MCS while it waits for the webhook.
Step 6: Set up the webhook
Saving the first gateway address does two things:
- shows the Webhook address,
https://rentstream.onmcs.ai/hooks/mcs/followed by a code for this connection. It never changes; - makes an API key and shows it once, in a popup.
In the popup, either copy the key, or select Download webhook script, which has the address and key in it. Then select I have copied it. The key cannot be shown again; Rent Stream AI only keeps enough to recognise it.
Run the webhook script on the MCS database. It subscribes Rent Stream AI to every webhook MCS has, with the address and key, and switches the subscriptions on. It never touches other systems' webhook subscriptions, and it is safe to run again. Delete the file once it has run.
You can set up the subscription by hand in MCS's webhook settings instead: use the
webhook address, and the key as the API key. MCS sends the key in the X-APIKey header.
A call with a missing or wrong key is refused.
:::caution Things to know about the webhook
- If MCS adds new message types later, run the webhook script again so they are covered. That needs the key, so select Replace API key to get a new key and script, then run it.
- Replace API key stops the old key working at once. Run the new script straight away.
- If your live and test connections point at the same MCS database, the webhook script for one points every Rent Stream AI subscription in that database at itself. :::
Step 7: Our reference in MCS
Create a text custom field in MCS for the work item reference, then enter its ID, or its name, under Our reference in MCS. Rent Stream AI writes the work item reference into it on every record it creates, so you can always trace a record back to its work item.
Use the ID: quotes only accept the ID, while other records also accept the name. Leave it empty to send no reference.
Changing the connection later
- Replacing an existing login or gateway address needs a second admin to approve it in Settings, Approvals. Until then, the old one stays in use.
- After changing the login, run the install script again so MCS expects the new one.
- Replacing the gateway address does not change the webhook address or key.
When something goes wrong
| Message | What to do |
|---|---|
| MCS did not answer. Check the MCS-connect address | Check the address, that MCS-connect is running, and that it is reachable from the internet over HTTPS. Work items waiting on MCS carry on by themselves when it is back, or go to a person after an hour |
| MCS refused the login | Check the login and the method match what the install script set. Run the script again if the login changed |
| MCS answered, but our endpoints are not installed | Download the install script and run it on the MCS database |
| MCS-connect could not run our endpoint | Run the latest install script again |
| MCS-connect is not licensed on this MCS site | MCS-connect needs a licence on the MCS system |
| MCS refused it (on Create in MCS) | Read MCS's reason on the work item, fix it, then Send it again |
| We could not tell whether MCS received it | Check MCS for the record. Then choose It is in MCS, under number, or tick I have checked MCS and it is not there and Send it again |
| A work item waits at Create in MCS and never confirms | Check the webhook subscription is in MCS with the current key, and that MCS can reach rentstream.onmcs.ai |