Clients¶

Local clients start ameriflux-mcp themselves over stdio; hosted deployments are reached over Streamable HTTP. The install script (scripts/install.sh) writes the stdio entries below for Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Goose and OpenCode in one step; this page shows them for manual setup. The examples use ameriflux-mcp on your PATH (see Install); replace it with an absolute path such as /home/me/ameriflux-mcp/.venv/bin/ameriflux-mcp (Windows: C:\\Users\\me\\ameriflux-mcp\\.venv\\Scripts\\ameriflux-mcp.exe) when the client does not share your shell's PATH. JSON-configured clients do not expand ~ or $HOME, so use absolute paths there.

The examples register the server without a download identity, which is all that discovery, variables, citations and local previews need. To enable downloads, add the variables from Download identity to the same env block (or -e options); keep them in the client's environment settings, never in a shared or committed file.

Claude Code¶

claude mcp add ameriflux -s user -- ameriflux-mcp --transport stdio
claude mcp list

-s user makes the server available in every project¹. Add -e NAME=value options before -- for the download identity.

Claude Desktop¶

Edit claude_desktop_config.json and restart the app:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ameriflux": {
      "command": "/absolute/path/to/ameriflux-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Codex CLI¶

codex mcp add ameriflux -- ameriflux-mcp --transport stdio
codex mcp list

This writes the server into ~/.codex/config.toml²; restart running sessions. Without the CLI, add the table yourself:

[mcp_servers.ameriflux]
command = "/absolute/path/to/ameriflux-mcp"
args = []

# only for downloads:
# [mcp_servers.ameriflux.env]
# AMERIFLUX_USER_ID = "your-username"

Gemini CLI¶

gemini mcp add --scope user ameriflux ameriflux-mcp
gemini mcp list

or add the entry to ~/.gemini/settings.json³ (.gemini/settings.json in a project):

{
  "mcpServers": {
    "ameriflux": {
      "command": "/absolute/path/to/ameriflux-mcp",
      "args": []
    }
  }
}

Goose¶

Add an extension to ~/.config/goose/config.yaml (Windows: %APPDATA%\Block\goose\config\config.yaml)⁴, then restart Goose Desktop or start a new CLI session. goose configure → Add Extension → Command-line Extension does the same interactively.

extensions:
  ameriflux:
    enabled: true
    type: stdio
    name: ameriflux
    cmd: /absolute/path/to/ameriflux-mcp
    args: []
    envs: {}
    timeout: 300

OpenCode¶

Add to ~/.config/opencode/opencode.json⁵. This is the layout OpenCode's documentation shows. The install script writes "mcp": {"servers": {…}} instead unless opencode --version reports 1.x; if your OpenCode does not pick the server up, move the entry to the layout its documentation gives.

{
  "mcp": {
    "ameriflux": {
      "type": "local",
      "command": ["/absolute/path/to/ameriflux-mcp", "--transport", "stdio"],
      "enabled": true
    }
  }
}

VS Code¶

Add to .vscode/mcp.json in a workspace, or to your user configuration⁶. For downloads, inputs prompts keep your identity out of the file:

{
  "inputs": [
    { "type": "promptString", "id": "amf-user", "description": "AmeriFlux user ID" },
    { "type": "promptString", "id": "amf-email", "description": "Email registered with AmeriFlux", "password": true }
  ],
  "servers": {
    "ameriflux": {
      "type": "stdio",
      "command": "/absolute/path/to/ameriflux-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "AMERIFLUX_USER_ID": "${input:amf-user}",
        "AMERIFLUX_USER_EMAIL": "${input:amf-email}"
      }
    }
  }
}

Leave out inputs and env to run without downloads.

Any other stdio client¶

Run ameriflux-mcp --transport stdio (bare ameriflux-mcp does the same), with the download identity in the environment if you want downloads. The server speaks MCP 2026-07-28 and still accepts clients on earlier protocol revisions over stdio.

A hosted server (HTTP)¶

claude mcp add --transport http ameriflux https://ameriflux-mcp.example.org/mcp

A hosted server offers the eight tools that need no identity and read no local files: site search, site details, availability, the two variable tools, citations, BADM and amf_ping. Downloads and the local file tools exist only on stdio, and no identity is accepted over HTTP, by header or otherwise.