# How to Configure MCP Servers for OAuth Authorization Using `kimi mcp`

> Configure MCP servers for OAuth authorization with the Kimi CLI. Easily register servers and complete the browser-based authorization flow using the kimi mcp command.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: how-to-guide
- Published: 2026-07-22

---

**The Kimi CLI enables OAuth-protected MCP server configuration through a three-step workflow: registering the server with `--auth oauth`, executing `kimi mcp auth <name>` to complete the browser-based authorization flow, and persisting tokens in `~/.kimi/mcp-oauth/` via the `TokenStorageAdapter`.**

The **Kimi CLI** from MoonshotAI provides native support for Model-Control-Protocol (MCP) servers that require OAuth authentication. When you configure MCP servers for OAuth authorization, the tool manages the entire token lifecycle—from initial registration in the global config file to secure storage and runtime injection into the `fastmcp` client.

## Registering an OAuth-Protected MCP Server

To add a new MCP server that requires OAuth, use the `kimi mcp add` command with the `--auth oauth` flag. This registers the server in `~/.kimi/mcp.json` and marks it as OAuth-protected.

```bash
kimi mcp add \
  --transport http \
  --auth oauth \
  linear https://mcp.linear.app/mcp

```

In [`src/kimi_cli/cli/mcp.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/mcp.py), the `mcp_add` function (lines 83-95) processes this command and adds the `"auth": "oauth"` field to the server definition. The global configuration file stores the server metadata, but tokens are not yet present at this stage.

## Executing the OAuth Authorization Flow

After registration, initiate the OAuth flow to obtain and store access tokens:

```bash
kimi mcp auth linear

```

This command invokes the `mcp_auth` function in [`src/kimi_cli/cli/mcp.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/mcp.py) (lines 52-66), which validates the server configuration and launches your default browser to complete the OAuth handshake. Upon successful authentication, the tokens are saved to the `~/.kimi/mcp-oauth/` directory using the `TokenStorageAdapter` from the `fastmcp` library.

## How OAuth Tokens Are Managed

The Kimi CLI implements a dedicated token management system in [`src/kimi_cli/mcp_oauth.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp_oauth.py). The `create_mcp_oauth_store` function (lines 22-34) initializes a `FileTreeStore` within the `~/.kimi/mcp-oauth/` directory to persist tokens securely.

When executing MCP commands, the `prepare_mcp_server_config` function (lines 64-73) detects the `"auth": "oauth"` placeholder in the server configuration and replaces it with a live `OAuth` object. This object automatically retrieves stored tokens from the file tree store before the `fastmcp` client initializes, ensuring seamless authenticated requests.

## Verifying Server Configuration

To confirm that OAuth tokens are present and the server is ready for use:

```bash
kimi mcp list

```

The `mcp_list` function (lines 45-48 in [`src/kimi_cli/cli/mcp.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/mcp.py)) checks for existing tokens via `_has_oauth_tokens`. If tokens are missing, the output appends a hint:

```text
linear (http): https://mcp.linear.app/mcp [authorization required - run: kimi mcp auth linear]

```

When tokens are valid, the server appears without the authorization warning, indicating it is ready to handle requests.

## Resetting Expired or Invalid Tokens

If tokens expire or authentication fails, clear the stored credentials and re-authorize:

```bash
kimi mcp reset-auth linear

```

This removes the token files from `~/.kimi/mcp-oauth/` for the specified server, allowing you to run `kimi mcp auth linear` again to generate fresh tokens.

## Summary

- **Register OAuth servers** using `kimi mcp add --auth oauth`, which stores the `"auth": "oauth"` flag in `~/.kimi/mcp.json` via the `mcp_add` function.
- **Authorize via browser** using `kimi mcp auth <name>`, implemented in `mcp_auth`, which stores tokens in `~/.kimi/mcp-oauth/` using `TokenStorageAdapter`.
- **Runtime injection** occurs through `prepare_mcp_server_config` in [`src/kimi_cli/mcp_oauth.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp_oauth.py), which converts the OAuth placeholder into a live client with valid credentials.
- **Token verification** happens automatically during `kimi mcp list`, which checks the `mcp-oauth/` directory before marking a server as ready.

## Frequently Asked Questions

### Where are OAuth tokens physically stored?

Tokens are persisted in the `~/.kimi/mcp-oauth/` directory as files managed by a `FileTreeStore` instance. The `create_mcp_oauth_store` function in [`src/kimi_cli/mcp_oauth.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp_oauth.py) initializes this storage, while `TokenStorageAdapter` from `fastmcp` handles the read/write operations for each server URL.

### Can I configure OAuth for multiple MCP servers simultaneously?

Yes. Each server entry in `~/.kimi/mcp.json` can specify `"auth": "oauth"`. Run `kimi mcp auth <server-name>` individually for each server to complete separate OAuth flows. The token storage isolates credentials by server URL, preventing conflicts between different OAuth providers.

### What happens if the OAuth browser flow fails or is interrupted?

If the browser flow fails, no tokens are written to `~/.kimi/mcp-oauth/`. Running `kimi mcp list` will continue to show the `[authorization required]` hint. You can safely re-run `kimi mcp auth <name>` to restart the flow, or use `kimi mcp reset-auth <name>` to clear any partial token state before retrying.

### How does the Kimi CLI handle token expiration at runtime?

The runtime configuration preparation in `prepare_mcp_server_config` (lines 64-73) injects a live `OAuth` object that reads from the file store on each invocation. If tokens are expired or invalid, the underlying `fastmcp` client will fail to authenticate, and you must run `kimi mcp auth <name>` again to refresh the credentials stored in the `mcp-oauth/` directory.