AI Agents & MCP Tool Calling

FlaskTrack exposes an MCP-compatible tool interface that allows AI agents to dynamically discover available tools, inspect schemas, and execute authenticated operations against laboratory workflows, samples, batches, reports, and other organizational resources.

This enables agents to:

Discover available API tools automatically
Inspect typed input/output schemas
Select the correct tool for a user request
Execute workflow actions safely
Complete scheduled protocol steps
Query reports and analytics
Operate using organization-scoped permissions

MCP Endpoints

List Available Tools

GET /mcp/tools

Returns all registered tools with:

Tool name
Description
Input schema
Output schema
Input transport type (query, json, path)
HTTP route
HTTP method

Example:

curl https://your-domain.com/mcp/tools \
  -H "x-organization: YOUR_ORG_ID" \
  -H "x-api-key: YOUR_API_KEY"

Call Tool

POST /mcp/call

Executes a tool dynamically.

Example:

{
  "tool": "list_batches",
  "input": {
    "q": "contaminated"
  }
}

List Raw Routes

GET /mcp/routes

Returns the underlying HTTP route definitions exposed by the MCP registry.

Useful for:

Agent planning
SDK generation
Route debugging
Tool inspection

Authentication

All MCP requests require authentication.

Example:

x-organization: ORG_ID
x-api-key: API_KEY

The authenticated organization scopes:

All data visibility
Compliance permissions
Workflow actions
Report access
Step execution

Recommended Agent Flow

An agent should generally follow this process:

1. Receive user request
2. Fetch available tools
3. Select the most appropriate tool
4. Construct typed input payload
5. Execute tool call
6. Interpret structured response
7. Continue workflow if additional actions are needed

Example: Batch Completion Agent

User Request

Complete the next step for batch TissueCulture-42

Step 1 — Discover Tools

curl https://your-domain.com/mcp/tools \
  -H "x-organization: YOUR_ORG_ID" \
  -H "x-api-key: YOUR_API_KEY"

The agent may discover:

{
  "name": "list_batches",
  "description": "List and search all batches for your authenticated organization"
}

{
  "name": "view_batch_schedule",
  "description": "View the scheduled workflow steps for a batch"
}

{
  "name": "complete_batch_run_step",
  "description": "Complete a scheduled workflow step for a batch"
}

Step 2 — Find Batch

POST /mcp/call

{
  "tool": "list_batches",
  "input": {
    "q": "TissueCulture-42"
  }
}

Response:

{
  "items": [
    {
      "id": "9f67c6f0-7f18-4ff4-b76f-58c3c91c2c9f",
      "name": "TissueCulture-42"
    }
  ]
}

Step 3 — View Schedule

{
  "tool": "view_batch_schedule",
  "input": {
    "batch_id": "9f67c6f0-7f18-4ff4-b76f-58c3c91c2c9f"
  }
}

Response:

{
  "steps": [
    {
      "step_run_id": "2ab83917-f4a2-4dcb-8e9f-9c0918d1e3c7",
      "title": "Transfer to rooting media",
      "status": "Ready"
    }
  ]
}

Step 4 — Inspect Required Shape

If the step requires structured form data:

{
  "tool": "get_protocol_step_shape",
  "input": {
    "protocol_id": "PROTOCOL_ID",
    "step_id": "STEP_ID"
  }
}

Example response:

{
  "requires_data_form": true,
  "data_schema": {
    "type": "object",
    "properties": {
      "temperature_c": {
        "type": "number"
      },
      "notes": {
        "type": "string"
      }
    }
  }
}

Step 5 — Complete Step

{
  "tool": "complete_batch_run_step",
  "input": {
    "batch_id": "9f67c6f0-7f18-4ff4-b76f-58c3c91c2c9f",
    "batch_step_run_id": "2ab83917-f4a2-4dcb-8e9f-9c0918d1e3c7",
    "data": {
      "temperature_c": 24.5,
      "notes": "Media transferred successfully"
    }
  }
}

Response:

{
  "completed": true,
  "target_type": "batch",
  "target_id": "9f67c6f0-7f18-4ff4-b76f-58c3c91c2c9f"
}

Example Python Agent

import requests

BASE = "https://your-domain.com"

HEADERS = {
    "x-organization": "ORG_ID",
    "x-api-key": "API_KEY",
}


def list_tools():
    r = requests.get(
        f"{BASE}/mcp/tools",
        headers=HEADERS,
    )
    r.raise_for_status()
    return r.json()


def call_tool(tool, input_payload):
    r = requests.post(
        f"{BASE}/mcp/call",
        headers=HEADERS,
        json={
            "tool": tool,
            "input": input_payload,
        },
    )

    r.raise_for_status()
    return r.json()


tools = list_tools()

batches = call_tool(
    "list_batches",
    {
        "q": "TissueCulture-42"
    }
)

print(batches)

Tool Selection Guidance

Agents should:

Prefer tool execution over generating assumptions
Inspect schemas before constructing payloads
Use search/list tools before operating on entities
Use schedule tools before completing steps
Respect compliance and permission failures
Treat returned IDs as canonical references

Structured Step Forms

Some protocol steps require structured data submission.

Agents should:

Call get_protocol_step_shape
Read the returned schema
Generate or collect the required fields
Submit the completed payload to the completion endpoint

The server merges submitted values with protocol-defined defaults automatically.

Safety Recommendations

Agents should avoid:

Blindly completing workflow steps
Repeating failed actions automatically
Guessing entity IDs
Generating SQL manually when report tools exist
Ignoring compliance or validation errors

Recommended behavior:

Search first
Validate state
Execute one step at a time
Interpret structured responses
Surface compliance failures clearly

Common Tools

Tool	Purpose
`list_batches`	Search batches
`list_species`	Search species
`list_protocols`	Search protocols
`list_workflows`	Search workflows
`lookup_samples`	Search samples
`view_batch_schedule`	Inspect scheduled batch steps
`view_sample_schedule`	Inspect scheduled sample steps
`get_protocol_step_shape`	Fetch required form schema
`complete_batch_run_step`	Finalize batch workflow steps
`complete_sample_run_step`	Finalize sample workflow steps
`list_reports`	Query saved reports

Typical AI Workflow Pattern

Search Entity
    ↓
Inspect State
    ↓
Fetch Shape (if required)
    ↓
Generate Structured Payload
    ↓
Execute Action
    ↓
Read Structured Result