--- name: inferrex-connect-system description: Connect a system to an Inferrex workspace by the address of its API, prove the sign-in with a live read, wait for the first read and get it reviewed and approved. Use when the user asks to add, connect or onboard a system, API or data source in Inferrex. --- # Connect a system to Inferrex Inferrex connects a system by its API address. Nothing is saved, and nothing may be reported as working, until a live signed-in read has returned data. ## When to use - "Connect our order system to Inferrex." - "Add this API as a system." - "The system I added is stuck waiting for review." Do not use this to fix a system that used to work. Use `inferrex-diagnose-flow` or `inferrex-replace-credentials`. ## Prerequisites One of these must be available. Check before you start and say which you are using. - **InferrexMCP**: an MCP server at `https://mcp.inferrex.com/mcp`, connected by sign-in or with an API key in a header. Tool names below are InferrexMCP tools. - **InferrexAPI**: `https://api.inferrex.com` with the header `X-API-Key: $INFERREX_API_KEY`. The key needs the scopes `connections:read`, `connections:write` and `workspace:read`. You also need from the user: 1. The address of the system's API, starting `https://`. 2. The name their team uses for the system. 3. Its credentials. Best is the name of a secret saved in the app at Workspace settings, Secrets. The user may paste the credential instead: see Credentials below. ## Credentials Ask first for the name of a saved secret, and say why: the value then never passes through this tool. If the user wants to paste the credential here instead, that is allowed, after a warning: 1. Say this, or words close to it: "If you paste it here, this AI tool sees the value, and this conversation's history may keep it. Saving it in the app keeps it out. Do you still want to paste it?" 2. Go on only after a clear yes. Anything else is a no. 3. Pass the value in `credentials`, using the field names `connections_detect_auth` returned in `credentialFields`. Send it to nothing else: no other tool, file, log, commit or host. 4. Do not repeat the value back, in full or in part, and do not include it in your report. ## Steps 1. **Confirm the environment.** Call `workspace_get_active_environment`. Tell the user its `name` and `class` and ask if that is where the system belongs. If the user asked for a different environment, stop and say so. 2. **Check it is not already connected.** Call `connection_list`. If a system with the same address exists, stop and ask whether to use it. 3. **Ask the API how it signs in.** Call `connections_detect_auth` with `endpoint`. - If `addressCorrection` is set, show it and ask the user to confirm the corrected address. - If `authType` is `unknown`, ask the user which method the API uses. `unknown` does not mean the API is open. - If `signInWithProvider` is set, tell the user the provider offers its own sign-in page and that a person must complete it in the app (Systems, add a system, sign-in step). Stop here unless they choose to use a saved secret instead. 4. **Test.** Call `connections_test_connection` with `url`, `authType` and either `credentialRef` (the secret's name) or `credentials` (a pasted value, after the warning under Credentials). Add `readPaths` if the user knows a path that returns records, such as `/customers`. - Pass only when `outcome` is `signed-in` or `read-without-sign-in`. - Any other outcome is a fail. Report `outcome`, `httpStatus` and `detail` to the user and stop. Do not continue to step 5. - If `outcome` is `unverified`, ask for a path that returns records and test again. 5. **Connect.** Call `connection_infer` with the same `url`, `authType`, `credentialRef` or `credentials`, and `readPaths`, plus `displayName`. Keep the `connectionId` and `jobId`. 6. **Wait for the first read.** Call `connection_status` with `id`. While `status` is `inferring`, wait and call again. It takes a minute or two. Do not call more often than every few seconds. 7. **Summarise what was found.** When `status` is `awaiting-review`, call `connection_manifest`. List each object with its field count, and list the fields where `requiresCustomerReview` is true and the fields with a `sensitivity`. 8. **Apply the user's corrections.** For each correction the user gives, call `connection_approve_field` with `fieldPath` (`.`), `approved` and the corrected value. To leave fields out, call `connections_set_field_inclusion`. 9. **Approve only when the user says so.** Call `connection_approve`. If it answers `409 connection_not_proven`, call `connections_test_saved_connection`, and approve again only if that test passes. ## Checks before any write - Step 4 must pass before step 5. The test stores nothing, so it is always safe to run. - Step 9 needs an explicit yes from the user after they have seen the summary from step 7. - Use a new `displayName` only after step 2 shows no duplicate. ## Equivalents | Step | InferrexMCP tool | InferrexAPI | |---|---|---| | Environment | `workspace_get_active_environment` | `GET /v1/workspace/environment` | | List | `connection_list` | `GET /v1/connections` | | Detect sign-in | `connections_detect_auth` | `POST /v1/connections/detect-auth` | | Test | `connections_test_connection` | `POST /v1/connections/test` | | Connect | `connection_infer` | `POST /v1/connections/infer` | | Status | `connection_status` | `GET /v1/connections/:id/status` | | What was found | `connection_manifest` | `GET /v1/connections/:id/manifest` | | Correct a field | `connection_approve_field` | `POST /v1/connections/:id/approve-field` | | Leave fields out | `connections_set_field_inclusion` | `PATCH /v1/connections/:id/field-inclusion` | | Test saved sign-in | `connections_test_saved_connection` | `POST /v1/connections/:id/test` | | Approve | `connection_approve` | `POST /v1/connections/:id/approve` | ## Report back - The system's name, its `connectionId` and its `status`. - The test result: `outcome` and `provedBy`. - The objects found, the fields that need a person's review, and the sensitive fields. - What is still waiting for the user: review, approval, or a provider sign-in. ## Never - Never accept a pasted password, token or API key without giving the warning under Credentials and getting a clear yes. Ask for the name of a saved secret first. - Never echo, log, save or repeat a credential value. - Never say a system is connected or working unless a test returned `signed-in` or `read-without-sign-in`. - Never approve a system the user has not reviewed. - Never tell the user that Inferrex already knows, supports or recognises their system, and never offer a list of systems to pick from. Ask only for the API's address. - Never connect the same organisation twice. If a provider sign-in covers several organisations, each becomes its own system and the user chooses which. - Never send credentials to any host other than `api.inferrex.com` or `mcp.inferrex.com`.