# @gammainfra/mcp-server

Model Context Protocol (MCP) server for [GammaInfra](https://gammainfra.com) — intelligent LLM routing across every major provider via one OpenAI-shape API.

Drop this server into Claude Code, Claude Desktop, Cursor, Cline, Continue, or any MCP-compatible host, and your agent gets direct tool access to:

- **`chat_completions`** — call any supported model (or `gammainfra/auto` for smart routing) with cost, latency, and quality controls. Routing metadata (which provider served, exact cost in USD, fallback chain) is returned as a structured `routing_meta` field.
- **`list_models`** — full model catalog with pricing and capability flags.
- **`get_balance`** — managed + BYOK balances.
- **`get_status`** — overall + per-provider health, 24h request count.

## Quickstart

1. Get a GammaInfra API key — sign up free at <https://gammainfra.com/signup> ($3 trial credit, no credit card).
2. Add the server to your MCP client config (instructions per client below).
3. Restart the client. The four tools become available to your agent immediately.

## Installation

The server runs via `npx` — no manual install needed. The first invocation downloads and caches the package.

### Claude Code

```bash
claude mcp add gammainfra \
  --env GAMMAINFRA_API_KEY=sk-gammainfra-... \
  -- npx -y @gammainfra/mcp-server
```

Or edit `~/.claude.json` and add to the `mcpServers` block:

```json
{
  "mcpServers": {
    "gammainfra": {
      "command": "npx",
      "args": ["-y", "@gammainfra/mcp-server"],
      "env": { "GAMMAINFRA_API_KEY": "sk-gammainfra-..." }
    }
  }
}
```

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "gammainfra": {
      "command": "npx",
      "args": ["-y", "@gammainfra/mcp-server"],
      "env": { "GAMMAINFRA_API_KEY": "sk-gammainfra-..." }
    }
  }
}
```

Restart Claude Desktop. The "GammaInfra" server should appear in the tools menu.

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gammainfra": {
      "command": "npx",
      "args": ["-y", "@gammainfra/mcp-server"],
      "env": { "GAMMAINFRA_API_KEY": "sk-gammainfra-..." }
    }
  }
}
```

### Cline (VS Code)

Open Cline's settings (gear icon → MCP Servers tab) and add:

```json
{
  "gammainfra": {
    "command": "npx",
    "args": ["-y", "@gammainfra/mcp-server"],
    "env": { "GAMMAINFRA_API_KEY": "sk-gammainfra-..." },
    "disabled": false
  }
}
```

## Environment variables

| Var | Required | Default | Description |
|---|---|---|---|
| `GAMMAINFRA_API_KEY` | yes | — | Your GammaInfra API key, format `sk-gammainfra-{32_chars}`. |
| `GAMMAINFRA_BASE_URL` | no | `https://api.gammainfra.com/v1` | Override for staging/dev. |

## Tool reference

### `chat_completions`

Send a chat completion request and receive the model response plus routing metadata.

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | `gammainfra/auto` for smart routing, `gammainfra/fast`/`gammainfra/cheap` for tier shortcuts, or pin a specific model like `openai/gpt-5-mini`. |
| `messages` | array | yes | OpenAI-shape conversation messages. |
| `temperature` | number | no | 0..2. |
| `max_tokens` | int | no | |
| `max_completion_tokens` | int | no | GPT-5 family requires this instead of `max_tokens`. |
| `cost_quality` | float | no | 0.0..1.0 continuous dial. Sent as `X-GammaInfra-Cost-Quality`. |
| `max_latency_ms` | int | no | 60..600000. Caps total wall-clock incl. fallback retries. Also enforced client-side as a hard request abort. |
| `preference` | string | no | `quality`, `cost`, or `latency`. |
| `region` | string | no | `us`, `eu`, `apac`, or specific AWS region. |
| `tools`, `tool_choice`, `response_format`, `top_p`, `frequency_penalty`, `presence_penalty` | various | no | Standard OpenAI fields, forwarded as-is. |

**Returns:** `{ response: <OpenAI response>, routing_meta: { provider, endpoint, cost_usd, input_cost_usd, output_cost_usd, router_version, logical_model, fallback_chain, attempted_count, request_id, ... } }`

**Timeout note:** Every request has a 10-minute client-side hard timeout (via `AbortController`) so a hung upstream can't wedge the MCP process. For `chat_completions`, a supplied `max_latency_ms` replaces that default as the hard abort bound.

**Streaming note:** MCP tool responses are non-streaming. The server always sends `stream: false` to the upstream and does not accept a `stream` parameter on the tool input (it's rejected by schema validation). For streaming, use the GammaInfra HTTP API directly.

### `list_models`

No parameters. Returns the full model catalog including direct-pin slugs, per-token pricing, and capability flags (`supports_tools`, `supports_vision`).

### `get_balance`

| Name | Type | Required | Description |
|---|---|---|---|
| `include_byok` | boolean | no | Default `false`. Also fetch the BYOK balance. Off by default to avoid an extra request — and a guaranteed 404 — for customers without BYOK enrollment. |

Returns `{ managed_balance_usd, byok_balance_usd, currency }`. With `include_byok` omitted/false, `byok_balance_usd` is `null` and no BYOK request is made (no `byok_error`). With `include_byok: true`, if BYOK isn't enrolled, `byok_balance_usd` is `null` and a `byok_error` field describes the cause.

### `get_status`

No parameters. Returns GammaInfra's current overall health, per-provider state and live p50 latency, and 24h request count.

## Development

```bash
git clone https://github.com/yuz0101/gammainfra-mcp-server.git
cd gammainfra-mcp-server
npm install
npm run test          # 30 tests, ~1s
npm run build         # tsc → dist/
npm run typecheck
```

## License

MIT — see [LICENSE](./LICENSE).