Skip to content
Learning Outcomes
  • Configure an MCP-compatible client (Cursor / VS Code / Claude Code / Claude Desktop).
  • Understand the MCP request/response flow at a high level.
  • Troubleshoot common auth and connection issues.

MCP Integration

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

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 – the Foundry Connect MCP endpoint (example: https://your-mcp-viafoundry.com/mcp). This may differ from your main Foundry Connect base URL.
  • Headers – hostname + token
  • X-Foundry-Connect-Hostname: your Foundry Connect 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-Foundry-Connect-Token: your MCP token (must start with via_mcp_)

Legacy header names

The server also still accepts the legacy X-ViaFoundry-Token / X-ViaFoundry-Hostname headers, so existing configurations keep working — you don't need to change anything already set up.

MCP prefix is required

MCP tokens must start with via_mcp_. The MCP server validates this prefix and rejects tokens without it, on every authentication path — the X-Foundry-Connect-Token header, the legacy X-ViaFoundry-Token header, and Authorization: Bearer <token> alike. A General Purpose PAT is therefore rejected for MCP no matter how you send it; create the token with the MCP usage type.

Tokens issued by the OAuth Connect to Claude flow carry the same via_mcp_ prefix — that path creates a real MCP token for you (see Personal Access Tokens).

Cursor / VS Code

Foundry Connect generates a ready-to-use config snippet when you create your MCP token — select Cursor or VS Code from the dropdown and click Copy Code. Alternatively, save the following to ~/.cursor/mcp.json (Cursor) or your MCP extension config file (VS Code), then restart the IDE:

Production:

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

Localhost:

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

Claude Code

Claude Code supports MCP servers at two levels — project-scoped (shared with your team) and global (available across all your projects).

Option A: CLI command — The fastest way to add the Foundry Connect MCP server:

# Add globally (available in all projects)
claude mcp add --transport http --scope user foundry \
  --header "X-Foundry-Connect-Token: via_mcp_your-token-here" \
  https://your-mcp-viafoundry.com/mcp

# Or add to the current project only
claude mcp add --transport http --scope project foundry \
  --header "X-Foundry-Connect-Token: via_mcp_your-token-here" \
  https://your-mcp-viafoundry.com/mcp

Already added it as viafoundry?

Earlier instructions named the server viafoundry. The name is just a local alias in your own Claude config, so an existing connector keeps working — but if you re-add it as foundry without removing the old one, you will have two servers exposing the same tools. Remove the old entry first:

claude mcp remove viafoundry

Run /mcp in Claude Code to see which servers are currently connected. The Foundry Connect plugin also registers its server as foundry, so the name is consistent either way.

Option B: Manual configuration — Add the config JSON directly to the appropriate file:

Project-level — Create a .mcp.json file in your project root. This makes Foundry Connect tools available to anyone who opens this project in Claude Code:

{
  "mcpServers": {
    "foundry": {
      "type": "http",
      "url": "https://your-mcp-viafoundry.com/mcp",
      "headers": {
        "X-Foundry-Connect-Token": "via_mcp_your-token-here"
      }
    }
  }
}

Global — Add the same configuration to ~/.claude.json to make Foundry Connect tools available across all your projects:

{
  "mcpServers": {
    "foundry": {
      "type": "http",
      "url": "https://your-mcp-viafoundry.com/mcp",
      "headers": {
        "X-Foundry-Connect-Token": "via_mcp_your-token-here"
      }
    }
  }
}

MCP URL depends on deployment

For GCP-hosted instances, use https://mcp.gcp.viafoundry.com/mcp instead. Check with your Foundry Connect administrator for the correct URL.

Claude Desktop

Edit the Claude Desktop configuration file:

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

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

Restart Claude Desktop after saving for the changes to take effect.

VS Code Continue

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

{
  "mcpServers": {
    "foundry": {
      "url": "https://your-mcp-viafoundry.com/mcp",
      "headers": {
        "X-Foundry-Connect-Token": "via_mcp_your-token-here"
      }
    }
  }
}
If tools don't appear

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

GitHub Copilot CLI

Copilot installs the Foundry Connect plugin from a marketplace and takes your instance from an environment variable rather than from this file:

copilot plugin marketplace add UMMS-Biocore/foundry-connect-plugin
copilot plugin install foundry-connect@foundry-connect
export instance_host=foundry.your-org.edu

Set instance_host to a bare hostname, with no scheme, no trailing slash and no /mcp, then start a new session. Full walkthrough: GitHub Copilot.

An invalid entry is dropped silently

A malformed server in ~/.copilot/mcp-config.json does not raise an error. It is simply absent from copilot mcp list, so a missing server is much more likely than a broken one.

Codex

Codex stores a bundled server's address exactly as written and never expands a variable inside it, so the connection is added by hand rather than carried by the plugin:

codex mcp add foundry --url https://foundry.your-org.edu/mcp
codex mcp login foundry

Keep the name foundry, which then takes precedence over the plugin's placeholder entry. codex mcp login requires Foundry Connect 2.22.0 or later; on an older instance use a token with --bearer-token-env-var. Full walkthrough: Codex.

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. Foundry Connect'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 Code/Claude Desktop)
  └─ MCP request (HTTP/SSE) + headers
        ├─ X-Foundry-Connect-Hostname (Only for localhost)
        └─ X-Foundry-Connect-Token (via_mcp_...)
             ↓
MCP Server
  ├─ Validates via_mcp_ token prefix
  ├─ Routes tool calls to Foundry Connect SDK
  └─ Handles authentication middleware
             ↓
Foundry Connect Python SDK
  ├─ ViaFoundryClient
  ├─ Reports, Process, Metadata modules
  └─ Handles API communication
             ↓
Foundry Connect 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 Code, 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_*, update_*, 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, update_process, upload_file, add_files_to_dataset, update_metadata_records
High-Risk Always requires Accept launch_app (starts pipeline execution)

Available MCP Tools

Foundry Connect provides 61 tools across several categories.

Doing science rather than building integrations?

You only need the first three groups. Start with get_started — it returns the tool chain for whichever journey you are on, so you don't have to pick from this list. See the worked example.

  • Getting oriented: get_started, list_featured_pipelines, recommend_pipeline, plan_run
  • Preparing an analysis: prepare_samples, make_sample_sheet, create_vmeta_dataset, preflight_run
  • Configuring and launching a run: duplicate_run, update_run, initiate_run, get_run_details
  • Watching a run: watch_run, get_run_log
  • Reading the results: summarize_results, list_results, suggest_apps
  • 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, update_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, update_metadata_record, update_metadata_records
  • App Management: list_apps, discover_app_endpoints, launch_app

Updating metadata records

update_metadata_record changes fields on one existing record, and update_metadata_records changes fields on many records in one collection, such as setting a group on every sample in a dataset. Only the fields you send change; everything else on the record keeps its value.

  • The batch tool checks every row before it writes anything. If any row has a missing or repeated record id, an empty update, or a reserved key, no record changes and the response lists the rows to fix.
  • Once writing starts, each record gets its own result, and one failure does not stop the rest. Check the failed count and any rows with ok: false.
  • Both tools refuse _id, owner, perms and DID, so an update can never change a record's identity or who can see it.
  • Both are writes. The Foundry Connect plugin tells the assistant to show a table of every record and its new value and ask once before a batch update.

Quick Reference

Client config locations

Client Config File
Claude Code (project) .mcp.json (project root)
Claude Code (global) ~/.claude.json
Claude Desktop (Mac) ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows) %APPDATA%\Claude\claude_desktop_config.json
Cursor ~/.cursor/mcp.json
VS Code Continue ~/.continue/config.json
GitHub Copilot CLI ~/.copilot/mcp-config.json
Codex (global) ~/.codex/config.toml
Codex (project) .codex/config.toml

Troubleshooting

Token / auth issues

Symptom Likely cause Suggested Solution
"Invalid token format: … must start with via_mcp_" You used a General Purpose PAT, not an MCP one Create a new token with the MCP usage type — the prefix cannot be added by hand
"Invalid token" MCP token missing via_mcp_ prefix Generate an MCP token and retry
"Token expired" Expiration date reached Create a new token. If you connected via OAuth, the Claude connection token lasts 90 days — reconnect from Profile → Connect to Claude
Worked before, now fails to authenticate The Claude connection token expired or was deleted Reconnect from Profile → Connect to Claude; no reinstall needed
"Authentication failed" Hostname header mismatch Ensure X-Foundry-Connect-Hostname matches your Foundry Connect 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