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

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.

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

In 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:

kimi mcp auth linear

This command invokes the mcp_auth function in 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. 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:

kimi mcp list

The mcp_list function (lines 45-48 in src/kimi_cli/cli/mcp.py) checks for existing tokens via _has_oauth_tokens. If tokens are missing, the output appends a hint:

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:

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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}