amsc-mcp

FastMCP server exposing the IRI Facility API as MCP tools, designed to connect with LiteLLM.

Features

• Full coverage of IRI endpoints: Facility, Status, Compute, Filesystem
• Dynamic OpenAPI spec learning (learn_iri_api) from any live IRI deployment URL
• Smart elicitation: asks for resource_id, path, or executable when missing
• Secure Bearer token flow: user provides their IRI token once via elicitation; never stored on disk
• Async task polling for filesystem operations
• Three transport modes: HTTP (default), SSE, STDIO

Setup

cd amsc-mcp
uv venv
uv pip install -e .

Environment Variables

Variable	Default	Description
IRI_BASE_URL	https://iri-dev.ppg.es.net/api/v1	IRI Facility API base URL
IRI_MCP_API_KEY	(unset = auth disabled)	Static key for LiteLLM → MCP auth
MCP_HOST	0.0.0.0	Bind host
MCP_PORT	8006	Bind port
LOG_LEVEL	INFO	Python logging level

Running the Server

# HTTP (default, for LiteLLM)
IRI_MCP_API_KEY=mysecretkey uv run server.py

# SSE transport
IRI_MCP_API_KEY=mysecretkey uv run server.py --sse

# STDIO (for Claude Desktop / local MCP clients)
uv run server.py --stdio

Connecting with LiteLLM

Add to your LiteLLM config.yaml:

mcp_servers:
  - name: amsc-iri
    url: http://localhost:8006/mcp
    transport: http
    auth:
      type: bearer
      token: "mysecretkey"   # matches IRI_MCP_API_KEY on the server

The server will elicit your personal IRI Bearer token the first time you call any IRI tool. That token is forwarded to the IRI API and held in server memory only — it is never written to disk.

Connecting with Claude Desktop

{
  "mcpServers": {
    "amsc-iri": {
      "command": "uv",
      "args": ["run", "/path/to/amsc-mcp/server.py", "--stdio"],
      "env": {
        "IRI_BASE_URL": "https://your-facility.example.com/api/v1"
      }
    }
  }
}

Tool Reference

Discovery

Tool	Description
discover_resources	List available resources with IDs, types, status
learn_iri_api(spec_url)	Fetch OpenAPI spec from URL → markdown endpoint summary

Facility

Tool	Description
get_facility_info	Facility name, description, contacts
list_sites	List facility sites
get_site(site_id)	Details for a specific site

Status

Tool	Description
get_resource(resource_id)	Resource details and capabilities
list_incidents	Active/historical incidents
get_incident(incident_id)	Incident details with events
list_events	Status change events

Compute

Tool	Description
submit_job	Submit a job (elicits resource_id and executable if missing)
get_job_status(resource_id, job_id)	Job state, timing, exit code
list_jobs	All jobs on a resource
cancel_job(resource_id, job_id)	Cancel a job

Filesystem (all ops poll async tasks automatically)

Tool	Description
ls	List directory
stat	File metadata
file_type	File type
head / tail / view	Read file content
checksum	SHA-256 checksum
mkdir / rm	Create / delete
cp / mv / symlink	Copy / move / link
chmod / chown	Permissions
download / upload	Transfer files
compress / extract	Archive operations

Auth

Tool	Description
clear_iri_token	Remove cached IRI token (re-elicits on next call)
refresh_api_cache	Clear OpenAPI spec cache

Example Session

User: Show me what compute resources are available

→ discover_resources(resource_type="compute")
  Returns table: nersc-perlmutter | compute | ✅ ok | ...

User: Submit a quick test job on perlmutter that runs hostname

→ submit_job(resource_id="nersc-perlmutter", executable="/bin/hostname",
             job_name="test", walltime_minutes=5)
  Returns: job_id = "12345678"

User: Check if it's done

→ get_job_status(resource_id="nersc-perlmutter", job_id="12345678")
  Returns: ✅ COMPLETED, exit code 0

User: Download the output file

→ download(resource_id="nersc-perlmutter-fs", path="/scratch/user/hostname.out")
  Returns: file content as text