Integrate Scout

Scout provides three access paths: the FactVerse web application, platform MCP, and REST API. Use the web application for guided investigation and review, MCP for governed Scout tools in an AI client, and REST API for application integration and automation.

Choose an integration path

Path	Best fit	Authentication
FactVerse web application	Create tasks, review evidence, approve, and publish	Platform user sign-in
Platform MCP	Read tasks and call authorized tools from an external AI client	Platform MCP credential and X-API-Key
REST API	Connect Scout operations to a business system or automation	Platform credential supported by the deployment

All paths share the same tenant, tasks, permissions, and audit records. Use the tool definitions or API documentation returned by the deployed environment for exact request fields.

Prerequisites and Inputs

• FactVerse host and target tenant
• Scout and platform MCP enabled in that environment
• A platform credential bound to an active account, purpose, and least-privilege scope
• The business question and equipment or dataset scope
• Task and resource identifiers returned by authorized service calls

Begin with read-only access to list capabilities and tasks, then confirm that the client is connected to the intended tenant.

Connect an MCP client

Use a client that supports remote MCP over Streamable HTTP and custom request headers. The Scout endpoint is:

https://your-factverse-host/mcp/scout/

1. Ask the tenant administrator to issue a platform MCP credential. For the first connection, use purpose READ and scope scout.read.
2. Add the remote MCP service to the client. For a private deployment, enter the customer platform address.
3. Add X-API-Key to the client's protected header configuration, using the platform MCP credential as its value.
4. Connect and refresh the tools. Call scout_capabilities, scout_mission_list, and then scout_mission_get.
5. Confirm the returned tasks, assets, source options, and tenant context.

Tool	Purpose
scout_capabilities	List available workflows, business objectives, and authorized source options
scout_mission_list	List Scout tasks visible in the current tenant, with pagination
scout_mission_get	Read the selected task stage, blockers, next action, and evidence references

Use the input definition shown by the client. An empty task list means no task is visible in the current query scope; create a task in the web application or ask an administrator to review access.

Assign credential purposes

Responsibility	Credential purpose	Scout scopes
View tasks and evidence	READ	scout.read
Create tasks, investigate, and validate	OPERATOR	scout.read, scout.write
Review publication evidence	APPROVER	scout.read, scout.approve
Apply approved publication or supported recovery	DEPLOYER	scout.read, scout.deploy

The platform also checks account status and the related data, MDM, model, and DFS permissions. Where publication requires separation of duties, configure separate access for the approver and release operator.

Example: investigate equipment signals

Ask the AI client:

Inspect one week of vibration, temperature, and battery data for this motor. Confirm the physical asset, X/Y/Z directions, measurement type, and units. Present the evidence and open questions before suggesting matches.

1. Call scout_capabilities to see available workflows and objectives.
2. Find the task with scout_mission_list, then read its scope and current stage with scout_mission_get.
3. Follow the tool definition to investigate authorized sources and review candidate evidence.
4. Add equipment manuals, installation records, or confirmation from the field owner.
5. Complete candidate review, validation, approval, and publication under the appropriate roles.
6. Inspect actual readings for the selected time range and the application result.

Example: review a business-data delivery

Check this authorized delivery against the published business objective. Identify datasets, suggest field meaning and identity keys, inspect duplicate records and relationships, and list definitions that require domain review.

Use the capability response to select the business objective and source. Follow the task through inventory, profiling, field and MDM decisions, dry run, approval, and publication. For recurring deliveries, compare with the active version first; see Subsequent deliveries.

REST API endpoints

The following paths are relative to the FactVerse host. Obtain resource identifiers from authorized responses in the current tenant.

Method and path	Purpose
GET /api/v1/scout/missions	List tasks
GET /api/v1/scout/missions/{missionId}	Read a task
POST /api/v1/scout/missions/{missionId}/discovery	Start discovery
GET /api/v1/scout/missions/{missionId}/semantic-model-proposals/options	Get model draft, asset, property, and compatible class options
POST /api/v1/scout/missions/{missionId}/semantic-model-proposals	Submit a model proposal for review
POST /api/v1/scout/missions/{missionId}/semantic-model-proposals/{id}/review	Record a model-proposal decision
POST /api/v1/scout/missions/{missionId}/semantic-model-proposals/{id}/apply-to-draft	Apply an approved proposal to a model draft
POST /api/v1/scout/missions/{missionId}/semantic-execution/dry-runs	Validate a model and reference publication plan

Model endpoints also require the relevant model, MDM, and DFS permissions. After a draft change is applied, continue through the independent publication approval and execution workflow.

Handle retries and errors

For endpoints that require Idempotency-Key, reuse the same key for the same logical request and content. After a timeout, read the operation state before retrying an explicitly supported idempotent action.

Response	Client action
401	Renew or restore platform authentication
403	Check tenant, module, action, and related data permissions
404	Query again with a resource identifier returned for the current tenant
409	Read the latest version, then validate and review again
429	Back off according to the response
Timeout or service error	Query the existing operation and preserve request correlation data

Rotate client credentials

1. Issue a new credential with the appropriate account, purpose, and scopes.
2. Validate read-only access with scout_capabilities and scout_mission_list.
3. Update the protected X-API-Key configuration and reconnect the client.
4. Revoke the old credential and confirm the expected access result for both credentials.
5. Record the credential label, owner, purpose, and rotation date.

Platform MCP credentials and model-provider credentials are managed separately. Follow the customer security process to revoke access promptly after exposure or personnel changes.