npm package: @pmtuan0206/orbit-mcp-server
Description: MCP (Model Context Protocol) server for integrating Orbit into Antigravity and other MCP-compatible clients
Author: Orbit Systems
Latest version: 1.0.0

# Orbit MCP Server

**Model Context Protocol (MCP) server for integrating Orbit into Antigravity and other MCP-compatible AI clients.**

## 🎯 What is this?

This MCP server allows you to use **Orbit's AI routing capabilities** inside **Google Antigravity** (or any other MCP-compatible client). It acts as a bridge between Antigravity and Orbit, enabling you to:

- ✅ Use multiple AI providers (Claude, Gemini, GLM, DeepSeek, etc.) through Antigravity
- ✅ Leverage Orbit's smart routing (e.g., request Claude but actually use Gemini)
- ✅ Access Orbit's account pooling and auto-failover
- ✅ Track usage analytics across all providers

## 📦 Installation

### Option 1: Global Installation (Recommended)

```bash
npm install -g @orbitsystems/mcp-server
```

### Option 2: Local Development

```bash
cd packages/mcp-server
npm install
npm run build
```

## 🚀 Quick Start

### 1. Configure Orbit API Key

```bash
export ORBIT_API_KEY="orbit_sk_your_api_key_here"
```

Or create a config file at `~/.orbit/mcp-config.json`:

```json
{
  "apiKey": "orbit_sk_your_api_key_here",
  "baseUrl": "https://api.orbit.cloud",
  "useLocalCCS": false
}
```

### 2. Add to Antigravity

Create or edit `mcp_config.json` in your Antigravity settings directory:

**Windows**: `C:\Users\<USERNAME>\AppData\Roaming\Antigravity\mcp_config.json`  
**macOS**: `~/Library/Application Support/Antigravity/mcp_config.json`  
**Linux**: `~/.config/Antigravity/mcp_config.json`

```json
{
  "mcpServers": {
    "orbit": {
      "command": "orbit-mcp",
      "env": {
        "ORBIT_API_KEY": "orbit_sk_your_api_key_here"
      }
    }
  }
}
```

### 3. Restart Antigravity

Restart Antigravity to load the MCP server. You should now see Orbit tools available in the MCP panel.

## 🛠️ Available Tools

### `orbit_chat`

Send a chat message to Orbit AI proxy.

**Parameters:**
- `message` (required): The message to send
- `profile` (optional): Routing profile to use (e.g., "gemini-as-claude")
- `model` (optional): Model to request (e.g., "claude-3-5-sonnet-20241022")
- `stream` (optional): Enable streaming responses

**Example:**
```json
{
  "message": "Write a hello world in Python",
  "profile": "gemini-as-claude",
  "model": "claude-3-5-sonnet-20241022"
}
```

### `orbit_list_profiles`

List all available routing profiles.

**Example:**
```json
{}
```

### `orbit_get_usage`

Get usage statistics (requests, tokens, cost).

**Parameters:**
- `start_date` (optional): Start date (ISO 8601)
- `end_date` (optional): End date (ISO 8601)

**Example:**
```json
{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31"
}
```

### `orbit_switch_provider`

Temporarily switch to a specific provider.

**Parameters:**
- `provider` (required): Provider name (gemini, claude, glm, deepseek, etc.)

**Example:**
```json
{
  "provider": "gemini"
}
```

## 📚 Available Resources

### `orbit://config`

Current Orbit configuration and routing profiles.

### `orbit://providers`

List of all available AI providers and their status.

### `orbit://usage`

Current usage statistics and quotas.

## 🔧 Configuration Options

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ORBIT_API_KEY` | Orbit Cloud API key | (required) |
| `ORBIT_BASE_URL` | Orbit API base URL | `http://localhost:3000` |
| `ORBIT_USE_LOCAL_CCS` | Use local CCS instead of cloud | `false` |
| `ORBIT_DEFAULT_PROFILE` | Default routing profile | (none) |

### Config File Locations

The MCP server looks for config files in the following order:

1. `./orbit-mcp.config.json` (current directory)
2. `./orbit-mcp.config.yaml` (current directory)
3. `~/.orbit/mcp-config.json` (home directory)
4. `~/.orbit/mcp-config.yaml` (home directory)

### Example Config File

```json
{
  "apiKey": "orbit_sk_abc123xyz",
  "baseUrl": "https://api.orbit.cloud",
  "useLocalCCS": false,
  "defaultProfile": "gemini-as-claude"
}
```

## 🏠 Using Local CCS

If you have CCS installed locally, you can use it instead of Orbit Cloud:

```json
{
  "useLocalCCS": true
}
```

This will delegate all requests to your local `ccs` CLI installation.

## 🐛 Troubleshooting

### MCP Server Not Showing in Antigravity

1. Check that `mcp_config.json` is in the correct location
2. Verify the JSON syntax is valid
3. Restart Antigravity completely
4. Check Antigravity logs for errors

### Authentication Errors

1. Verify your `ORBIT_API_KEY` is correct
2. Check that the API key has not expired
3. Ensure you have network connectivity to Orbit Cloud

### Command Not Found: `orbit-mcp`

1. Ensure the package is installed globally: `npm install -g @orbitsystems/mcp-server`
2. Check your PATH includes npm global bin directory
3. Try using the full path: `npx orbit-mcp`

## 📖 MCP Protocol

This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) specification, which enables:

- **Tools**: Callable functions that perform actions
- **Resources**: Read-only data sources
- **Prompts**: Reusable prompt templates (coming soon)

## 🤝 Contributing

See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.

## 📄 License

MIT License - see [LICENSE](../../LICENSE)

## 🔗 Links

- [Orbit Cloud](https://orbit.cloud)
- [MCP Specification](https://modelcontextprotocol.io/)
- [Antigravity](https://deepmind.google/technologies/gemini/antigravity/)