Model Access Gateway (MAG)

info

The Model Access Gateway (MAG) is currently available only to Genesis RFA Phase I teams that have been approved for MAG access. Please do not proceed with the instructions below until the project PI has completed the "Genesis RFA Phase I Teams: Genesis Resources Planning Questionnaire" and received confirmation that they are awarded a MAG exploratory project. AmSC will then contact the project PI with onboarding instructions once the project is approved for MAG.

Overview

The Model Access Gateway (MAG) gives you one place to access several AI models. It also supports advanced capabilities such as agentic workflows, data discovery, and model evaluations.

This guide shows you how to:

Request an Account
Request access to a project
Obtain a MAG PAT (Personal Access Token) for the project
Setup PAT (Personal Access Token) in your client
Verify your access
Find the models available to you
Connect applications such as LangChain, Claude Code, and Codex CLI

Before you begin

Ensure your project is approved for MAG.
Have installed applications of your choice such as LangChain, Claude Code, or Codex CLI (optional) to use MAG.

Quick Start

1. Request an Account

See Access and Login for details.

2. Request access to MAG project

If you are a project PI and your account is approved, follow the steps listed under Request an AmSC project.
If you are a project member, and you account is approved, follow the steps listed under Joining a project

3. Create a MAG PAT (Personal Access Token)

Once the project membership request is approved, login to the MAG LiteLLM portal https://portal-lite.genesis.american-science-cloud.org/. You may need to authorize Ping Identity (the AmSC IdP) to access your profile information.
In the project section, select your AmSC Genesis Mission RFA project and click "switch".
Go to the "Personal Access Tokens" section and click on "Generate PAT".
In the new window that opens, select your AmSC Genesis Mission RFA project and click "continue".
You will be presented with the PAT (Personal Access Token). Highlight the long string and copy it to your clipboard.

warning

Copy the key before closing the dialog. MAG displays the complete key only once. If you lose it, you must generate a new key.

IMPORTANT: A PAT grants access to your account and must be stored securely. Do not put raw PAT keys into your source code, share it, or commit it to a Git repository! Use environment variables.

See Best Practices for PAT Safety for more guidance.

4. Setup PAT in your client

In your terminal, replace <key> with the PAT you copied:

export AMSC_I2_API_KEY=<key>

This command sets the variable for the current terminal session. If you open a new terminal, you must set it again.

You can confirm that the variable exists without displaying the key:

if [ -n "$AMSC_I2_API_KEY" ]; then echo "MAG PAT is set"; else echo "MAG PAT is not set"; fi

You should see:

MAG PAT is set

5. Verify your access and list models

Run:

curl --request GET \
  --url https://i2-api.genesis.american-science-cloud.org/v1/models \
  --header "Authorization: Bearer $AMSC_I2_API_KEY" | jq

A successful response contains model information in JSON format. If you receive an authentication error, see Troubleshooting.

The live response is the best way to determine which models are currently available to your account. Syntax and interactive examples for other API calls are available at https://i2-api.genesis.american-science-cloud.org.

6. Send your first request

Use one of the returned chat models to send a message. This example uses the claude-sonnet alias:

curl --request POST \
  --url https://i2-api.genesis.american-science-cloud.org/v1/chat/completions \
  --header "Authorization: Bearer $AMSC_I2_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-sonnet",
    "messages": [
      {"role": "user", "content": "In one sentence, explain what an AI model is."}
    ]
  }' | jq

A successful JSON response includes the model's reply under choices → message → content. You are now ready to use MAG directly or connect it to an OpenAI-compatible application.

Understand model names and versions

Some model names, such as claude-sonnet, are aliases. An alias points to the latest available version in that model family, so its underlying model can change when a newer version is released.

Choose a name based on your needs:

Use an alias, such as claude-sonnet, to receive newer versions automatically.
Use an exact version, such as claude-sonnet-4-6, when your application must remain on a specific version.

To find the exact model used for a request, inspect the model property in the response.

Available Models

The following tables are a convenient reference. Because availability can change, use the /v1/models endpoint shown in Step 3 for the current list available to your account.

Chat / Completion Models

Anthropic Claude	OpenAI GPT-5	Open-weight & Other
claude-haiku	gpt-5	devstral
claude-haiku-4-5	gpt-5-chat	devstral-2
claude-haiku-4-5-high	gpt-5-high	gpt-oss-120b
claude-haiku-high	gpt-5-mini	gpt-oss-120b-high
claude-opus	gpt-5-mini-high	gpt-oss-120b-safeguard
claude-opus-4-5	gpt-5-nano	gpt-oss-120b-safeguard-high
claude-opus-4-5-high	gpt-5-nano-high	gpt-oss-20b
claude-opus-4-6	gpt-5.1	gpt-oss-20b-high
claude-opus-4-6-high	gpt-5.1-chat	gpt-oss-20b-safeguard
claude-opus-high	gpt-5.1-high	gpt-oss-20b-safeguard-high
claude-sonnet	gpt-5.2	llama-4-maverick
claude-sonnet-4-5	gpt-5.2-chat	llama-4-scout
claude-sonnet-4-5-high	gpt-5.2-high	mistral-large
claude-sonnet-4-6	gpt-5.2-pro	mistral-large-3
claude-sonnet-4-6-high	gpt-5.4	nemotron-nano-3
claude-sonnet-high	gpt-5.4-high	nemotron-nano-vl
	gpt-5.4-mini	nemotron-super-3
	gpt-5.4-nano	nova-micro-1
	gpt-5.4-pro	nova-pro-1
	gpt-5.4-xhigh

Embedding Models

Model
cohere-embed-english-v3
cohere-embed-multilingual-v3
cohere-embed-v4
nova-2-embed-multimodal
text-embedding-ada-002
titan-embed-image-v1
titan-embed-text-v1
titan-embed-text-v2

Use MAG with applications

The following examples show how to configure common libraries and coding tools to use MAG.

Use the OpenAI-compatible API

MAG provides an OpenAI-compatible interface. Applications that support a custom OpenAI base URL can usually connect by using these environment variables:

export OPENAI_API_KEY="$AMSC_I2_API_KEY"
export OPENAI_BASE_URL="https://i2-api.genesis.american-science-cloud.org/v1"

Use MAG with LangChain

Install the LangChain OpenAI integration if it is not already installed:

python -m pip install langchain-openai

Make sure OPENAI_API_KEY is set as shown. Then save the following Python script as mag_langchain.py:

mag_langchain.py
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="claude-sonnet",  # Alias for the latest Sonnet version
    base_url="https://i2-api.genesis.american-science-cloud.org/",
)

response = llm.invoke("In one sentence, explain what an AI model is.")
print(response.content)

From the same terminal where you set OPENAI_API_KEY, run:

python mag_langchain.py

The script prints the model's response in your terminal.

Replace claude-sonnet with another chat model returned by the models API when needed.

Using Claude Code

Claude Code can connect to MAG through its Anthropic-compatible set.

1. Set Environment Variables

Set the following variables in your environment:

# Set authorization and base URL
export ANTHROPIC_AUTH_TOKEN=$AMSC_I2_API_KEY
export ANTHROPIC_BASE_URL=https://i2-api.genesis.american-science-cloud.org

# Model selection -- set to latest version of each model
# NOTE: You will need to update these each time a new model is released
# NOTE: Other models can be used, but Claude Code will incorrectly calculate API costs
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6

# Default conversation model
export ANTHROPIC_MODEL=claude-sonnet-4-6

# Default subagent model
export CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5

# Recommended setting
export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1

# Recommended setting
export DISABLE_TELEMETRY=1

# Recommended setting for compatibility
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# Recommended setting to reduce model throttling
# Higher max output tokens can be used but may cause prompts to be rejected with "too many tokens" error
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192

2. Verify Environment Variables

Restart your shell and verify that the environment variables are now present:

env | grep ANTHROPIC

You should see each ANTHROPIC_ variable configured above.

3. Start Claude Code

Now start Claude Code in your project directory:

cd my-project
claude

4. Optional: Install VS Code Extension

If you are a VS Code user, install the Claude Code for VSCode extension. When claude is run through the VS Code terminal, it will use VS Code to display highlighted diffs for approval.

Troubleshooting

The most common issue is that the environment variables are not configured correctly. You may need to log out / log-in again to ensure the variables are picked up and propogated correctly into all sub-processes.

Note on API Cost Optimization

note

Claude models can be expensive to operate, however, many optimizations exist that can substantially reduce cost.

According to Anthropic, the average cost of using Claude Code is $6 per day. Incorrect usage patterns can cause token utilization to be higher. Common issues include:

Having too many MCP servers
Over-use of CLAUDE.md instead of skills
Not using language-aware code intelligence plugins
Not clearing context between tasks
Using an overpowered model for the task

A comprehensive overview is available here: https://code.claude.com/docs/en/costs

Using Codex CLI

Codex CLI can connect to MAG through its OpenAI-compatible settings.

1. Set Environment Variables

Set the following variables in your environment:

# Map AMSC credentials to OpenAI-compatible env vars
export OPENAI_API_KEY=$AMSC_I2_API_KEY
export OPENAI_BASE_URL=https://i2-api.genesis.american-science-cloud.org

2. Verify Environment Variables

Restart your shell and verify that the environment variables are now present:

env | grep OPENAI

You should see OPENAI_API_KEY and OPENAI_BASE_URL.

3. Start Codex

Now start Codex in your project directory:

cd my-project
codex

4. Model Selection

The gpt-5.3-codex model is supported and recommended for best performance.

The model can be set via a .codex config file or by passing the --model argument. For convenience, you can alias the command:

alias codex='codex -m gpt-5.3-codex'

For more information see the OpenAI Codex CLI repository.

Test all available models

The quick-start request is enough for most users to confirm access. To test every available chat, completion, and embedding model, use the script below.

caution

This script sends a request to every available model. Running it will consume a small part of your token allocation.

Save the following code as test-mag-models.sh:

test-mag-models.sh
#!/bin/bash

# Configuration
API_BASE="https://i2-api.genesis.american-science-cloud.org"

# Try LITELLM_MASTER_KEY first, then fallback to LITELLM_API_KEY
API_KEY="${AMSC_I2_API_KEY:-$OPENAI_API_KEY}"

echo "🔍 Fetching detailed model info from AmSC AI gateway..."

# 1. Fetch data from /model/info and store the JSON
model_info=$(curl -s -X GET "$API_BASE/model/info" \
     -H "Authorization: Bearer $API_KEY")

if [ -z "$model_info" ] || [ "$model_info" == "null" ]; then
    echo "❌ No models found or failed to connect. Check your API_BASE and API_KEY."
    exit 1
fi

# 2. Extract model IDs based on their 'mode'
completion_models=$(echo "$model_info" | jq -r '.data[] | select(.model_info.mode == "chat" or .model_info.mode == "completion") | .model_name')
embedding_models=$(echo "$model_info" | jq -r '.data[] | select(.model_info.mode == "embedding") | .model_name')

echo "✅ Completion Models: $(echo $completion_models | tr '\n' ' ')"
echo "✅ Embedding Models: $(echo $embedding_models | tr '\n' ' ')"
echo "------------------------------------------"

# 3. Test Completion Models
for model in $completion_models; do
    echo "🤖 Testing Chat/Completion: $model"

    response=$(curl -s -X POST "$API_BASE/v1/chat/completions" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $API_KEY" \
        -d "{
            \"model\": \"$model\",
            \"messages\": [{\"role\": \"user\", \"content\": \"Reply with "OK". No other commentary.\"}]
        }")

    answer=$(echo "$response" | jq -r '.choices[0].message.content' | xargs)

    if [ "$answer" == "null" ] || [ -z "$answer" ]; then
        echo "   ⚠️ Error: Could not get a response for $model"
    else
        echo "   📩 Response: $answer"
    fi
    echo "------------------------------------------"
done

# 4. Test Embedding Models
for model in $embedding_models; do
    echo "🔢 Testing Embeddings: $model"

    response=$(curl -s -X POST "$API_BASE/v1/embeddings" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $API_KEY" \
        -d "{
            \"model\": \"$model\",
            \"input\": \"The quick brown fox jumps over the lazy dog\"
        }")

    # Check for the existence of the data array
    vector_check=$(echo "$response" | jq -r '.data[0].embedding[0:5]')
    vector_length=$(echo "$response" | jq -r '.data[0].embedding | length')

    if [ "$vector_check" == "null" ] || [ -z "$vector_check" ]; then
        echo "   ⚠️ Error: Could not get embeddings for $model"
    else
        echo "   ✅ Success: Received vector (length: $vector_length) starting with $vector_check..."
    fi
    echo "------------------------------------------"
done

Make the script executable and run it:

chmod +x test-mag-models.sh
./test-mag-models.sh

API Token Allocation and Usage

Token allocation and usage information is coming soon.

Troubleshooting

The API returns `401 Unauthorized` or an authentication error

Confirm that you copied the complete token string from Generate PAT.
Confirm that AMSC_I2_API_KEY is set in the same terminal where you run the command.
Generate a new key if the original key was revoked or expired.

A command cannot find the PAT

Environment variables set with export apply only to the current terminal session and its child processes. Set the variable again in the current terminal, then restart the application from that terminal.

A model request fails

Call /v1/models again and confirm that the model is available to your account.
Check the model name for spelling.
If you use an exact model version, try its family alias to determine whether that version is still available.

Claude Code or Codex does not use MAG

Start the tool from the terminal where you set its environment variables.
Verify the appropriate variable names using the commands in the tool's section.
Check that the base URL exactly matches the value shown in this guide.

Overview​

Before you begin​

Quick Start​

1. Request an Account​

2. Request access to MAG project​

3. Create a MAG PAT (Personal Access Token)​

4. Setup PAT in your client​

5. Verify your access and list models​

6. Send your first request​

Understand model names and versions​

Available Models​

Chat / Completion Models​

Embedding Models​

Use MAG with applications​

Use the OpenAI-compatible API​

Use MAG with LangChain​

Using Claude Code​

1. Set Environment Variables​

2. Verify Environment Variables​

3. Start Claude Code​

4. Optional: Install VS Code Extension​

Troubleshooting​

Note on API Cost Optimization​

Using Codex CLI​

1. Set Environment Variables​

2. Verify Environment Variables​

3. Start Codex​

4. Model Selection​

Test all available models​

API Token Allocation and Usage​

Troubleshooting​

The API returns 401 Unauthorized or an authentication error​

A command cannot find the PAT​

A model request fails​

Claude Code or Codex does not use MAG​

Overview

Before you begin

Quick Start

1. Request an Account

2. Request access to MAG project

3. Create a MAG PAT (Personal Access Token)

4. Setup PAT in your client

5. Verify your access and list models

6. Send your first request

Understand model names and versions

Available Models

Chat / Completion Models

Embedding Models

Use MAG with applications

Use the OpenAI-compatible API

Use MAG with LangChain

Using Claude Code

1. Set Environment Variables

2. Verify Environment Variables

3. Start Claude Code

4. Optional: Install VS Code Extension

Troubleshooting

Note on API Cost Optimization

Using Codex CLI

1. Set Environment Variables

2. Verify Environment Variables

3. Start Codex

4. Model Selection

Test all available models

API Token Allocation and Usage

Troubleshooting

The API returns `401 Unauthorized` or an authentication error

A command cannot find the PAT

A model request fails

Claude Code or Codex does not use MAG