Use MCP

This guide describes how a local agent or external automation can operate Monkeys through product APIs and MCP-style tool access. It complements the Product Data Assembly Guide.

The external operation model is simple:

1. Discover the product context.
2. Read before writing.
3. Use stable data, workflow, and tool contracts.
4. Trigger actions through product entrypoints.
5. Persist and inspect results.
6. Keep important actions traceable.

MCP is an operation entrypoint, not a shortcut around the product model. External agents should still respect ontology, views, permissions, workflow contracts, tool contracts, and artifact handling.

Operation Model

Before You Start

Confirm the agent has:

• A reachable Monkeys product endpoint.
• An MCP server or equivalent product-operation adapter.
• Authentication configured for the target product environment.
• A known workspace or team context when the operation requires one.
• Permission to read the data, execute workflows, upload files, or update records.
• A way to inspect tool schemas and API contracts.

Recommended first checks:

• Show the active connection context.
• List accessible workspaces or teams.
• List available workflows.
• Query a small data view sample.
• Inspect API docs or tool schema before using a generic API call.

Operating Principles

Read Before Write

External agents should inspect current product state before making changes.

Read:

• Available workspaces or teams.
• Relevant data repositories and views.
• Workflow definitions and required inputs.
• Existing execution history.
• API or tool schema.
• Existing records or artifacts that may be updated.

Then write only with explicit identifiers and scoped payloads.

Prefer Dedicated Tools

Use a dedicated MCP tool or product API when one exists.

Use generic API calls only when:

• No dedicated tool exists.
• The endpoint schema has been inspected.
• The request body is small, explicit, and reversible or easy to review.
• The agent can explain why the generic call is needed.

Keep Data Contracts Stable

Do not invent new record structures in prompts. Use ontology, schema, view, workflow, and tool contracts.

When the agent needs to write data, it should know:

• The target object.
• The target record or repository.
• Required fields.
• Allowed enum values.
• Artifact attachment rules.
• Permission and validation requirements.

Make Actions Traceable

For important operations, preserve:

• Who or what initiated the action.
• The target object.
• Input data.
• Workflow or tool version when available.
• Execution result.
• Created or updated artifacts.
• Error message and retry status when failed.

Current Operation Capabilities

Available capabilities may vary by deployment and MCP server version. The common operation categories are:

Common MCP Tool Patterns

The exact tool list may evolve, but the following names represent common current patterns:

Use the tool descriptions returned by the MCP client as the source of truth when the deployed server differs from this guide.

Connection And Context

Step 1: Confirm Connection

Ask the agent to show the current connection context.

Expected result:

• Endpoint or host is correct.
• Authentication is active.
• The agent can explain which product environment it is operating.

If connection fails:

• Check MCP server URL.
• Check authentication configuration.
• Check network access.
• Check whether the product API endpoint is reachable.

Step 2: Select Workspace Or Team Context

Many operations require a workspace or team identifier.

The agent should:

1. List available contexts.
2. Pick the intended one by name or identifier.
3. Reuse that identifier consistently in workflow, data, and file operations.

Do not guess identifiers from stale logs or screenshots if a discovery tool is available.

Data Operations

Query A Data View

Use data view query when the agent needs to inspect product data.

Recommended flow:

1. Identify the workspace or team context.
2. Identify the data repository or object.
3. Resolve the view by id or name.
4. Apply tag, field, search, or semantic filters when needed.
5. Request a small preview first.
6. Increase limit only after confirming the result shape.

The result should include:

• Selected repository or object.
• Selected view when available.
• Returned records.
• Count or pagination metadata.
• Warnings when view or tag resolution used a fallback.

Sample Data

Use sampling when the task needs representative records, especially for image-heavy or tag-heavy datasets.

Good uses:

• Pick reference images for generation.
• Review data quality.
• Inspect tag distribution.
• Create a small test input for workflow execution.

Avoid:

• Treating a random sample as a complete dataset.
• Writing updates based only on a sample unless the user asked for sampling.
• Ignoring warnings about unresolved tags or fallback views.

Update Data Through API

When no dedicated data-write MCP tool exists, use API discovery before a generic API call.

Flow:

1. List API docs.
2. Inspect the endpoint schema.
3. Confirm method, path, query, and body.
4. Read the target record first.
5. Send the smallest valid update.
6. Read back the updated record or view.

If the operation is destructive or broad, ask for explicit human confirmation before proceeding.

Workflow Operations

Find A Workflow

Flow:

1. List workflows with search.
2. Pick workflow by stable identifier, not only display name.
3. Get workflow detail.
4. Inspect variables, required inputs, tasks, and outputs.
5. Build input data from product records or explicit user input.

Execute A Workflow

Before execution:

• Confirm workflow identifier and version if relevant.
• Confirm input data matches workflow variables.
• Confirm selected records are the intended inputs.
• Confirm output expectations.

Execute:

• Call the workflow execution tool with structured input.
• Capture the returned execution identifier.
• Poll execution status or query it later.

After execution:

• Inspect terminal status.
• Inspect output payload.
• Locate generated artifacts.
• Confirm whether outputs were persisted into records or repositories.
• Record follow-up actions if needed.

Update A Workflow

Workflow updates are product configuration changes. Treat them carefully.

Before updating:

• Read the current workflow detail.
• Preserve required version or locking fields.
• Identify exactly which fields, variables, tasks, or outputs change.
• Avoid broad rewrites when a small update is enough.
• Confirm that downstream applications still understand the output.

After updating:

• Read back workflow detail.
• Run a small test execution if safe.
• Check execution history or logs.

File And Artifact Operations

Upload A File

Flow:

1. Confirm the target workspace or team context.
2. Confirm intended purpose: source input, workflow input, generated result, or documentation artifact.
3. Upload the file.
4. Capture file identifier, URL, MIME type, size, and metadata.
5. Link the artifact to a record, workflow, or output when relevant.

Avoid orphan files. If a file carries product meaning, it should be connected to product data.

Download A File

Flow:

1. Resolve the file or artifact identifier.
2. Download the file or base64 payload.
3. Preserve metadata.
4. Use it only for the requested operation.

Do not treat downloaded artifacts as authoritative if a newer record or workflow result exists.

Generic API Calls

Generic API calls are useful but sharp. Use them as a fallback.

Before calling a generic endpoint, confirm:

• Dedicated MCP tool does not cover the task.
• API docs have been inspected.
• The method and path are correct.
• Required query and body fields are present.
• The body does not contain unrelated fields.
• The operation is not destructive or broad without review.

Recommended pattern:

{
  "method": "GET",
  "path": "/api/example",
  "query": {
    "limit": 10
  }
}

For write calls, keep the body small and read back the result.

Cookbook

Cookbook: Inspect A Data View

1. Show connection context.
2. List workspaces or teams.
3. Query the data view by view name or id.
4. Ask for a small limit first.
5. Summarize returned records and warnings.
6. If needed, query again with stricter filters.

Cookbook: Trigger A Workflow From Selected Records

1. Query the source view.
2. Select records by explicit identifiers.
3. List workflows and find the intended workflow.
4. Get workflow detail and inspect required input.
5. Build input data using selected records.
6. Execute workflow.
7. Poll execution.
8. Inspect output and artifacts.
9. Confirm whether output was persisted.

Cookbook: Create Or Update A Workflow

1. List existing workflows to avoid duplicates.
2. Get similar workflow detail if available.
3. Build a minimal definition.
4. Create or update with explicit fields.
5. Read back the saved workflow.
6. Run a small test execution if safe.
7. Document assumptions and output contract.

Cookbook: Upload A File As An Artifact

1. Confirm target context.
2. Upload file.
3. Capture metadata.
4. Link it to the intended record or workflow input.
5. Query the related view or record to confirm visibility.

Cookbook: Troubleshoot A Failed Execution

1. Get execution by identifier.
2. Check terminal status and error message.
3. Search execution history for related runs.
4. Inspect workflow detail.
5. Compare input data against workflow variables.
6. Check whether required artifacts or records were missing.
7. Retry only after the likely cause is addressed.

Error Handling

Safety Checklist

Before a local agent changes product state, confirm:

• The target workspace or team is correct.
• The target record, workflow, view, or file is identified by stable id.
• The operation has been read first when possible.
• The request body is minimal and scoped.
• The operation follows product data contracts.
• The action can be audited or explained.
• Destructive or broad changes have explicit human approval.
• The agent will read back the result after the write.

Agent Prompt Template

Use this template when asking a local agent to operate Monkeys:

Goal:
<what should change or be inspected>

Context:
- Product endpoint:
- Workspace/team:
- Data repository or view:
- Workflow:
- Relevant records or files:

Rules:
- Read before writing.
- Prefer dedicated MCP tools.
- Use stable identifiers.
- Keep writes minimal.
- Preserve artifacts and action history.
- Report warnings and exact output identifiers.

Expected output:
- Summary of actions
- Records/workflows/files touched
- Execution ids or artifact ids
- Any unresolved risks

Completion Criteria

An external operation is complete when:

• The agent can explain what it read.
• The agent can identify exactly what it changed or triggered.
• Workflow executions have terminal or follow-up status.
• Artifacts are linked when they carry product meaning.
• Results are visible through product data or execution APIs.
• Errors and skipped steps are reported clearly.