MCP Integration

Use the Model Context Protocol (MCP) to connect AI tools (Cursor, VS Code, Claude Desktop, etc.) to ViaFoundry.

To get started, you’ll need an MCP token (a PAT that starts with via_mcp_). If you haven’t created one yet, see Personal Access Tokens (PATs).

Configure Your Client

Required configuration values

MCP URL – where the MCP server is hosted (example: https://your-viafoundry.com/mcp)
Headers – hostname + token
X-ViaFoundry-Hostname: your ViaFoundry base URL (example: https://your-viafoundry.com). Note: This is only needed for localhost/development (open mode). Production uses a fixed hostname, so this header is not required for production.
X-ViaFoundry-Token: your MCP token (must start with via_mcp_)

MCP prefix is required

MCP tokens must start with via_mcp_. The MCP server validates this prefix and rejects tokens without it.

Cursor

Save the following to ~/.cursor/mcp.json, then restart Cursor:

Production:

{
  "mcpServers": {
    "viafoundry": {
      "url": "https://your-mcp-viafoundry.com/mcp",
      "headers": {
        "X-ViaFoundry-Token": "via_mcp_your-token-here"
      }
    }
  }
}

Localhost:

{
  "mcpServers": {
    "viafoundry": {
      "url": "http://localhost:8081/mcp",
      "headers": {
        "X-ViaFoundry-Hostname": "https://your-viafoundry.com",
        "X-ViaFoundry-Token": "via_mcp_your-token-here"
      }
    }
  }
}

VS Code (Continue)

Update ~/.continue/config.json with an MCP server entry:

{
  "mcpServers": {
    "viafoundry": {
      "url": "https://your-viafoundry.com/mcp",
      "headers": {
        "X-ViaFoundry-Token": "via_mcp_your-token-here"
      }
    }
  }
}

Claude Desktop

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "viafoundry": {
      "url": "https://your-viafoundry.com/mcp",
      "headers": {
        "X-ViaFoundry-Token": "via_mcp_your-token-here"
      }
    }
  }
}

If tools don’t appear

Fully quit and reopen your IDE/app after editing MCP config files.

MCP Server Basics

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to interact with external tools and data sources. ViaFoundry’s MCP server allows AI tools to:

Fetch report data and files
List/search pipelines and runs
Upload/download report files
Query metadata and collections

High-level architecture

AI Client (Cursor/VS Code/Claude)
  └─ MCP request (HTTP/SSE) + headers
        ├─ X-ViaFoundry-Hostname (Only for localhost)
        └─ X-ViaFoundry-Token (via_mcp_...)
             ↓
MCP Server
  ├─ Validates via_mcp_ token prefix
  ├─ Routes tool calls to ViaFoundry SDK
  └─ Handles authentication middleware
             ↓
ViaFoundry Python SDK
  ├─ ViaFoundryClient
  ├─ Reports, Process, Metadata modules
  └─ Handles API communication
             ↓
ViaFoundry Backend API
  ├─ Authenticates PAT tokens
  ├─ Processes data requests
  └─ Returns reports, files, metadata

Security & Tool Confirmation

Human-in-the-Loop Confirmation

When an AI assistant decides to call an MCP tool, the IDE (Cursor, Claude Desktop, etc.) presents a confirmation dialog before execution. This prevents runaway agents and ensures you always know which tools are being called and with what parameters.

Tool Annotations

Each tool includes MCP annotations that hint to clients how to handle confirmations:

Annotation	Purpose	Tools
`readOnlyHint=True`	Safe to auto-execute (read-only)	`list_`, `get_`, `search_`, `fetch_`
`destructiveHint=True`	Always require confirmation	`launch_app`
`openWorldHint=True`	Modifies external systems	`create_`, `upload_`

Note: Client support varies. Some IDEs may auto-approve read-only tools, while others (like Cursor) require confirmation for all MCP tools regardless of annotations.

Tool Categories

Category	Confirmation	Examples
Read-Only	May auto-execute	`list_runs`, `fetch_report`, `search_datasets`
Write	Requires Accept	`create_process`, `upload_file`, `add_files_to_dataset`
High-Risk	Always requires Accept	`launch_app` (starts pipeline execution)

Available MCP Tools

ViaFoundry provides 41 tools across several categories:

Report Management: fetch_report, list_processes, list_files, download_file, load_file, upload_file, get_report_dirs, get_all_report_paths
Run Management: list_runs, get_run
Process/Pipeline Management: list_all_processes, get_process_details, get_process_revisions, list_process_parameters, get_process_parameters, duplicate_process, create_process_config, create_process, create_process_parameter
Menu Group Management: create_menu_group, list_menu_groups, get_menu_group_by_name
Dataset & Collections: search_datasets, search_collections, get_collection_details, create_collection, add_files_to_dataset, get_collection_fields
Canvas/Visualization: search_canvas, get_canvas_details, get_canvas_fields, create_canvas
Metadata Fields: search_metadata_fields, get_field_details, create_metadata_field
Metadata Records: search_metadata_records, get_metadata_record, create_metadata_record
App Management: list_apps, discover_app_endpoints, launch_app

Quick Reference

Client config locations

Client	Config File
Cursor	`~/.cursor/mcp.json`
Claude Desktop (Mac)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\\Claude\\claude_desktop_config.json`
VS Code Continue	`~/.continue/config.json`

Troubleshooting

Token / auth issues

Symptom	Likely cause	Suggested Solution
“Invalid token”	MCP token missing `via_mcp_` prefix	Generate an MCP token and retry
“Token expired”	Expiration date reached	Create a new token
“Authentication failed”	Hostname header mismatch	Ensure `X-ViaFoundry-Hostname` matches your ViaFoundry base URL

Do not reuse leaked tokens

If a token is exposed (logs, screenshots, chat transcripts), assume it is compromised and rotate it immediately.

Connection issues

Symptom	Likely cause	Suggested Solution
Server not responding	MCP server unreachable	Verify URL and network access
Tools not showing	Client didn’t reload config	Fully restart the IDE/app
Long operations fail	Streaming/timeouts	Retry, and contact your admin if persistent