Provider Setup & API Integration

Once Magpie AI is installed, your first milestone is connecting your model providers. Once configured, you can effortlessly allocate any backend model to any AI coding assistant (such as Claude Code, Codex, Gemini CLI, or OpenCode) via the menu bar or terminal.

Magpie AI supports two primary integration approaches:

1. Commercial APIs: Directly register official or third-party API keys (such as Anthropic, OpenAI, DeepSeek, Moonshot/Kimi, Zhipu GLM, SiliconFlow, or arbitrary OpenAI-compatible proxies).
2. Shared Subscriptions: Mount existing ChatGPT Plus, Claude Pro, or GitHub Copilot web accounts and OAuth sessions, eliminating the need to spend extra budget on separate commercial API tokens.

This tutorial guides you through setting up and validating providers using the CLI, interactive TUI, or the desktop menu bar.

Method 1: Instant Addition via CLI (Recommended)#

Magpie AI's command-line interface provides built-in vendor autocompletion and concise syntax:

1. Add Common Vendors Using Built-in Presets

For major model providers, Magpie AI already contains endpoint URLs and protocol mapping templates. You only need the vendor name and your API key:

# Add official DeepSeek API
magpie provider add deepseek sk-xxxxxxxxxxxxxxxxxxxxxxxx

# Add Moonshot / Kimi API
magpie provider add kimi sk-xxxxxxxxxxxxxxxxxxxxxxxx

# Add Zhipu GLM API
magpie provider add zhipu xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Add SiliconFlow API
magpie provider add siliconflow sk-xxxxxxxxxxxxxxxxxxxx

You can inspect all available vendor presets anytime:

# List all known provider presets and their supported models
magpie presets

2. Add Custom OpenAI-Compatible Endpoints (Relays & Self-Hosted)

If you run self-hosted open-weights models (via vLLM, Ollama, or LocalAI) or utilize custom enterprise API gateways, define your custom Base URL and available model list:

# Register a custom relay provider
magpie provider add my-custom-relay \
  --base-url https://api.my-relay.com/v1 \
  --key sk-custom-key-123456 \
  --models deepseek-r1,gpt-4o,claude-3-5-sonnet

3. Mount Web Subscriptions (Shared Subscriptions)

If you already have active ChatGPT Plus, Claude Pro, or GitHub Copilot plans, you can link your browser sessions directly:

# Mount Claude Pro subscription session
magpie accounts add claude

# Mount ChatGPT Plus subscription session
magpie accounts add chatgpt

The terminal will guide you through browser authorization. Once authenticated, Magpie stores session tokens locally and securely multiplexes them to your CLI agents.

Method 2: macOS Menu Bar & GUI#

If you prefer graphical workflows:

1. Open the Provider View: Click the Magpie icon in your macOS menu bar (or open the desktop app and navigate to Providers), then click 「Add Provider」.
2. Select Provider Type:
   • Preset: Pick Anthropic, OpenAI, DeepSeek, Moonshot, or Zhipu from the dropdown. The system automatically populates the official Base URL and recommended models.
   • Custom OpenAI: Enter your custom provider name, Base URL, and API Key.
   • Web Account: Select web subscription linking and follow the in-app authorization prompt.
3. Set Display Name & Aliases: Name your provider (e.g., deepseek-prod, kimi-backup) for easy reference.
4. Test & Save: Click 「Test Connection」 to verify credentials. When verified green, click 「Save」.

Method 3: Terminal TUI Setup#

Run magpie tui in your terminal:

1. Press Tab to navigate focus to the 「Providers」 pane.
2. Press a (Add) to open the provider addition dialog.
3. Use the arrow keys to choose a preset, paste your API key, and press Enter to confirm.
4. The pane instantly updates with real-time ping latency and model availability.

Verification & Usage#

After adding providers, run these checks to confirm readiness:

1. View Configured Providers

# Display all configured providers and models
magpie providers

This outputs provider aliases, target endpoints, authentication statuses, and model identifiers.

2. Send a Health Check Probe

Run a quick test before assigning the provider to production workflows:

# Test connectivity and response latency
magpie test deepseek

Receiving an HTTP 200 with latency metrics (e.g., 182ms) confirms the gateway can communicate smoothly with upstream servers.

3. Assign to an Agent Immediately

Assign your new provider to an AI coding assistant in a single command:

# Connect Claude Code to DeepSeek
magpie claude deepseek/deepseek-v4-pro

# Connect Codex to Kimi
magpie codex kimi/moonshot-v1-auto

Troubleshooting & FAQ#

Q: Why do I get a 401 Unauthorized on a third-party relay?

A: Check that there are no accidental trailing spaces or line breaks in your key. Also verify whether the relay requires a /v1 suffix in the Base URL (e.g., https://relay.com/v1).

Q: Are my API keys uploaded to external servers?

A: Never. Magpie AI operates strictly locally. All keys are encrypted and stored inside your operating system's native secure storage (macOS Keychain, Linux Secret Service, or Windows DPAPI) and never transit remote servers.

Q: Do web subscriptions encounter concurrency limits?

A: Web subscriptions follow standard plan limits (such as Anthropic's message caps per 5 hours). To maintain uninterrupted coding flow, configure Magpie's Routing Groups & Failover to automatically balance between multiple accounts.