MCP Resources

MCP Resources provide standardized access to workflow files through the workflow:// URI scheme. This enables AI assistants to read uploaded CSV files, access intermediate artifacts, and sample large datasets efficiently.

Overview

The MCP Resource system exposes two primary capabilities:

resources/list - Discover all files associated with a workflow
resources/read - Read file contents with optional CSV sampling

All workflow files are accessed through the workflow:// URI scheme with the format:

workflow://{workflow_id}/{type}/{filename}

Where:

workflow_id - UUID from generate_url_for_upload
type - Either uploads or artifacts
filename - The file name

Resource Types

Uploads

Files uploaded to the workflow session via generate_url_for_upload. These are user-provided input files, typically CSV data for analysis.

URI Pattern:

workflow://{workflow_id}/uploads/{filename}

Example:

workflow://550e8400-e29b-41d4-a716-446655440000/uploads/customers.csv

Artifacts

Generated outputs from workflow operations. Artifacts are automatically created by L2 tools and stored in structured formats (JSON, CSV, or Parquet).

URI Pattern:

workflow://{workflow_id}/artifacts/{artifact_name}.{format}

Supported formats:

.json - JSON representation of artifact data
.csv - CSV export (converted from Parquet if needed)
.parquet - Raw Parquet file (return presigned download URL)

Example:

workflow://550e8400-e29b-41d4-a716-446655440000/artifacts/resolved_identities.csv

Listing Resources

Use resources/list to discover all files in a workflow.

MCP Request:

{
  "method": "resources/list",
  "params": {
    "cursor": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Response:

{
  "resources": [
    {
      "uri": "workflow://550e8400-e29b-41d4-a716-446655440000/uploads/customers.csv",
      "name": "customers.csv",
      "description": "Uploaded file: customers.csv",
      "mimeType": "text/csv",
      "metadata": {
        "type": "upload"
      }
    },
    {
      "uri": "workflow://550e8400-e29b-41d4-a716-446655440000/artifacts/resolved_identities.csv",
      "name": "resolved_identities.csv",
      "description": "Workflow artifact: resolved_identities",
      "mimeType": "text/csv",
      "metadata": {
        "type": "artifact"
      }
    }
  ]
}

Pagination:

The cursor parameter serves as the workflow ID for simple pagination. To list resources for a specific workflow, pass the workflow ID as the cursor.

Reading Resources

Use resources/read to access file contents.

Basic Read

MCP Request:

{
  "method": "resources/read",
  "params": {
    "uri": "workflow://550e8400-e29b-41d4-a716-446655440000/uploads/customers.csv"
  }
}

Response:

{
  "contents": [
    {
      "uri": "workflow://550e8400-e29b-41d4-a716-446655440000/uploads/customers.csv",
      "mimeType": "text/csv",
      "text": "email,phone,name,company\nalice@example.com,555-0001,Alice,Acme\nbob@example.com,555-0002,Bob,Beta\n..."
    }
  ]
}

CSV Sampling

For large CSV files, use query parameters to sample specific rows without loading the entire file.

URI with Sampling:

workflow://{workflow_id}/uploads/{filename}?offset=0&limit=100

Parameters:

offset - Row number to start from (0-indexed, default: 0)
limit - Maximum number of rows to return (default: 10)
format - Output format: csv, json, or jsonl (default: csv)

Example Request:

{
  "method": "resources/read",
  "params": {
    "uri": "workflow://550e8400-e29b-41d4-a716-446655440000/uploads/customers.csv?offset=0&limit=10"
  }
}

Response:

{
  "contents": [
    {
      "uri": "workflow://550e8400-e29b-41d4-a716-446655440000/uploads/customers.csv",
      "mimeType": "text/csv",
      "text": "email,phone,name,company\nalice@example.com,555-0001,Alice,Acme\nbob@example.com,555-0002,Bob,Beta\n..."
    }
  ]
}

Use Cases:

Schema detection: ?offset=0&limit=5 to examine headers and first few rows
Data preview: ?offset=0&limit=100 for quick inspection
Pagination: ?offset=100&limit=100 to read next batch
Tail sampling: ?offset=9900&limit=100 for end-of-file inspection

Artifact Format Selection

Artifacts can be accessed in different formats by specifying the file extension.

JSON Format:

workflow://550e8400-e29b-41d4-a716-446655440000/artifacts/resolved_identities.json

CSV Format:

workflow://550e8400-e29b-41d4-a716-446655440000/artifacts/resolved_identities.csv

CSV artifacts support sampling just like uploaded CSVs:

workflow://550e8400-e29b-41d4-a716-446655440000/artifacts/enriched_profiles.csv?offset=0&limit=50

Common Workflows

Schema Detection

Before processing a CSV, inspect its structure:

1. resources/read uri=workflow://.../uploads/data.csv?offset=0&limit=5
2. Analyze headers and sample rows
3. Identify email/phone/address columns

Iterative Analysis

Access intermediate results for refinement:

1. resources/list cursor={workflow_id}
2. Identify artifact URIs from list response
3. resources/read uri=workflow://.../artifacts/lift_scores.csv
4. Analyze results and adjust parameters

Data Validation

Verify processing results:

1. resources/read uri=workflow://.../artifacts/resolved_identities.csv?offset=0&limit=10
2. Check resolution quality and format
3. Sample additional rows if needed

Migration from get_workflow_state

MCP Resources replace the deprecated get_workflow_state tool with a more flexible, protocol-native approach.

Old Approach (get_workflow_state):

{
  "name": "get_workflow_state",
  "arguments": {
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

New Approach (resources/list + resources/read):

{
  "method": "resources/list",
  "params": {
    "cursor": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Key Improvements:

Protocol Native - Uses standard MCP resource methods instead of custom tools
Selective Access - Read only the files you need, not entire workflow state
CSV Sampling - Efficiently inspect large files without full downloads
Format Flexibility - Choose JSON or CSV for artifacts based on use case
Better Caching - MCP clients can cache individual resources

Migration Checklist:

✅ Replace get_workflow_state calls with resources/list
✅ Use resources/read to access specific files
✅ Add CSV sampling for schema detection workflows
✅ Update error handling for resource-specific failures
✅ Leverage format selection for artifacts (.json vs .csv)

Error Handling

Common Errors:

File Not Found:

{
  "error": {
    "code": -32002,
    "message": "Upload file not found: customers.csv"
  }
}

Invalid URI:

{
  "error": {
    "code": -32602,
    "message": "Invalid workflow URI format. Expected: workflow://{workflowId}/{type}/{filename}"
  }
}

Workflow Not Found:

{
  "resources": []
}

When a workflow doesn't exist, resources/list returns an empty array rather than an error.

Best Practices

Always Sample First - Use ?offset=0&limit=10 for CSV schema detection
List Before Read - Use resources/list to discover available artifacts
Choose Format Wisely - Use JSON for structured data, CSV for tabular inspection
Use generate_download_url for Full Files - For complete file downloads, use the generate_download_url tool instead of resources/read
Cache Listings - Workflow file lists change infrequently, cache list responses

Example: Complete Schema Detection Workflow

// 1. List workflow resources
const listResponse = await client.request("resources/list", {
  cursor: workflowId
});

// 2. Find the uploaded CSV
const csvResource = listResponse.resources.find(r =>
  r.uri.includes("/uploads/") && r.uri.endsWith(".csv")
);

// 3. Sample the CSV for schema detection
const readResponse = await client.request("resources/read", {
  uri: `${csvResource.uri}?offset=0&limit=5`
});

// 4. Parse CSV headers and sample
const csvText = readResponse.contents[0].text;
const lines = csvText.split("\n");
const headers = lines[0].split(",");
const sampleRows = lines.slice(1);

// 5. Detect identifier columns
const emailColumns = headers.filter(h =>
  sampleRows.some(row => row.includes("@"))
);

Next Steps

Use resources with MCP Prompts for guided workflows
Explore Core Tools for data processing
Review API Integration for caching guidelines

On this page