> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# CLI and MCP

> Use the Phaseo CLI for terminal automation or connect the authenticated MCP server to AI clients for live Phaseo data and, if you allow it, account management.

# CLI and MCP

Use Phaseo from your terminal with the CLI, or connect an AI client through MCP. Both use Phaseo OAuth, but they are designed for different jobs.

| Interface | Best for | Access |
| - | - | - |
| Phaseo CLI | Terminal workflows, CI, administration, and automation | Read and write, limited by your scopes and workspace role |
| Phaseo MCP | Live Phaseo data inside Codex, Claude, ChatGPT, and other MCP clients, and optional account management | Authenticated; read-only unless you connect with account management |
| Docs MCP | Looking up current Phaseo documentation while coding | Documentation-only and read-only |
| Phaseo plugin | Installing the Phaseo MCP, the Docs MCP, and the Phaseo skills in Claude Code or Codex at once | Same as each MCP server |

## Phaseo CLI

Use the CLI when you need to create or change Phaseo resources, script a workflow, or inspect account data from a shell.

### Install and sign in

```bash theme={null}
npm install -g @phaseo/cli
phaseo login
phaseo whoami
```

Interactive terminals use browser OAuth by default. For SSH, CI, and headless environments, use device authorization:

```bash theme={null}
phaseo login --device-code
```

### Common workflows

```bash theme={null}
phaseo models list --limit 20
phaseo pricing models
phaseo credits get
phaseo workspaces list
phaseo keys create --name "Local development"
phaseo logs list --since 1h --status error --json
```

Use `--json` when another tool or script needs structured output. Secret values are displayed only by commands that explicitly create or reveal them.

> [card] [Phaseo CLI guide](https://phaseo.app/docs/v1/guides/integrations/phaseo-cli.md)
>
> See authentication options, key management, workspaces, guardrails, and the complete command workflow.

## Phaseo MCP

Connect the Phaseo MCP server when you want an AI client to answer questions using live model, pricing, provider, usage, and workspace data.

### Server URL

`https://mcp.phaseo.app/mcp`

### Connect from Codex

```bash theme={null}
codex mcp add phaseo --url https://mcp.phaseo.app/mcp
codex mcp login phaseo
```

The login command opens Phaseo OAuth. Choose a workspace and approve the requested read scopes, then confirm the connection:

```bash theme={null}
codex mcp list
```

For another MCP client, add the same URL as a remote Streamable HTTP server. The client must support OAuth discovery, authorization code with S256 PKCE, and the MCP `resource` parameter.

### What the MCP can read

* models, providers, benchmark rankings, pricing, and cost estimates
* credits, activity, analytics, request logs, and generation metadata

These tools are read-only. They never return prompts, responses, or secret values.

### Manage your account (optional)

To let an agent change your Phaseo workspace, connect with the manage URL instead:

`https://mcp.phaseo.app/mcp?access=manage`

```bash theme={null}
codex mcp add phaseo --url "https://mcp.phaseo.app/mcp?access=manage"
codex mcp login phaseo
```

When you sign in, the consent screen lists each permission the connection asks for, such as managing API keys or deleting budgets, and marks it **Read**, **Write**, or **Delete**. Untick any you do not want. The agent only gets tools for the permissions you allow, and Phaseo still checks your workspace role on every change, so a member who is not an owner or admin cannot change admin-only settings this way.

If you already connected with the read-only URL, switch the client to the manage URL and sign in again. To go back to read-only access, reconnect with the plain URL or revoke the app under **Settings → Connected Apps**.

| Area | Tools | Permissions |
| - | - | - |
| API keys | `api_keys_list`, `api_key_get`, `api_key_create`, `api_key_update`, `api_key_rotate`, `api_key_delete` | `keys:read`, `keys:write`, `keys:delete` |
| Budgets | `budgets_list`, `budget_create`, `budget_update`, `budget_delete` | `budgets:read`, `budgets:write`, `budgets:delete` |
| Spend rules | `spend_rules_list`, `spend_rule_create`, `spend_rule_update`, `spend_rule_delete` | `spend_rules:read`, `spend_rules:write`, `spend_rules:delete` |
| Provider keys (BYOK) | `provider_keys_list`, `provider_key_create`, `provider_key_update`, `provider_key_delete` | `provider_credentials:read`, `provider_credentials:write`, `provider_credentials:delete` |
| Guardrails | `guardrails_list`, `guardrail_get`, `guardrail_create`, `guardrail_update`, `guardrail_delete`, `guardrail_keys_set` | `guardrails:read`, `guardrails:write`, `guardrails:delete` |
| Presets | `presets_list`, `preset_get`, `preset_create`, `preset_update`, `preset_version_publish` | `presets:read`, `presets:write` |
| Settings | `settings_get`, `settings_update` (routing mode, privacy and ZDR, logging, provider restrictions) | `settings:read`, `settings:write` |
| Webhooks | `webhooks_list`, `webhook_create`, `webhook_delete` | `settings:read`, `settings:write` |
| Observability destinations | `observability_destinations_list`, `observability_destination_create`, `observability_destination_delete` | `settings:read`, `settings:write` |

Tools that change or delete something are marked as such, so MCP clients that support it ask you before each call. A new API key or webhook signing secret is shown once in the tool result and cannot be shown again. Stored provider keys and destination credentials are never returned.

The MCP has no billing, payment, workspace, member, management-key, or OAuth-app tools. Use the dashboard, CLI, or Management API for those.

## Docs MCP

The Docs MCP is a separate endpoint for searching and reading Phaseo documentation. It does not access your account or workspace.

```bash theme={null}
codex mcp add phaseoDocs --url https://phaseo.app/docs/mcp
```

Use it when a coding assistant needs current API examples, integration guidance, or feature documentation.

> [card] [Docs MCP guide](https://phaseo.app/docs/v1/guides/integrations/docs-mcp.md)
>
> Connect the documentation server to Codex, Claude Code, Cursor, OpenCode, or VS Code.

## Phaseo plugin

The Phaseo plugin bundles the Phaseo MCP, the Docs MCP, and the Phaseo agent skills for integration, migration, model selection, usage monitoring, the SDKs, and the CLI. Install it once instead of connecting each piece yourself.

### Claude Code

```bash theme={null}
claude plugin marketplace add phaseoteam/skills
claude plugin install phaseo@phaseo
```

Run `/mcp` and sign in to `plugin:phaseo:phaseo` to connect your Phaseo account. Skills load when a request matches them, or you can run one directly, such as `/phaseo:phaseo-gateway`.

### Codex

```bash theme={null}
codex plugin marketplace add phaseoteam/skills
codex plugin add phaseo@phaseo
codex mcp login phaseo
```

The last command opens Phaseo OAuth for the Phaseo MCP. Skills load when a request matches them.

## Choose the right interface

* Use the **CLI** to create keys, change settings, manage workspaces, or automate administrative workflows.
* Use the **Phaseo MCP** to give an AI client safe access to live Phaseo data.
* Use the **Docs MCP** to give a coding assistant current Phaseo documentation without account access.
* Use the **Phaseo plugin** to set up both MCP servers and the Phaseo skills in Claude Code or Codex at once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.