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

# Authentication Overview

> Authentication architecture for mcp-agent cloud deployments

mcp-agent cloud supports multiple authentication modes so you can choose the right balance between security and accessibility. This page introduces the architecture and flows; the detailed configuration lives in the sub-pages.

## Components

| Component                             | Role                                                                                                                               |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization server**              | Issues API keys today; OAuth 2.1 support (authorization code flow) is in development. Hosted in LastMile’s control plane.          |
| **Resource server (your deployment)** | Exposes MCP endpoints (`call_tool`, `read_resource`, etc.) and validates tokens. Powered by FastMCP + `MCPApp`.                    |
| **Clients**                           | MCP clients (Claude Desktop, Cursor, ChatGPT Apps), custom code (Python, cURL), or other MCP servers calling downstream resources. |
| **Secrets service**                   | Stores deployment/user secrets, eliminating the need to embed credentials in clients.                                              |

<img src="https://github.com/user-attachments/assets/80d63b71-d9ba-46a0-b2a6-8ccf1bfb6296" alt="Agents exposed as MCP servers, sitting between MCP clients and downstream MCP servers" width="593" height="406" />

## Modes at a glance

| Mode                       | Use case                                                   | How                                                                                                    | Docs                                                           |
| -------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| **Bearer token** (default) | Internal deployments, quick sharing within a team          | `mcp-agent login` → provides `MCP_API_KEY`. Clients send `Authorization: Bearer`.                      | [Deployment auth →](/cloud/authentication/deployment-auth)     |
| **Unauthenticated**        | Public endpoints, ChatGPT Apps                             | Deploy with `mcp-agent deploy ... --no-auth`.                                                          | [Deployment auth →](/cloud/authentication/deployment-auth)     |
| **OAuth 2.1 (Upcoming)**   | Enterprise SSO, fine-grained scopes                        | Follows MCP OAuth spec (RFC 9728 + RFC 8414).                                                          | (Coming soon)                                                  |
| **External MCP auth**      | Your agent needs to authenticate to downstream MCP servers | Configure `mcp_agent.config.yaml -> mcp.servers.<name>.auth` for API keys or OAuth client credentials. | [External MCP auth →](/cloud/authentication/external-mcp-auth) |

## Current flow (Bearer tokens)

1. Developer or user runs `mcp-agent login`.
2. Browser-based auth returns an API key (`lm_mcp_api_*`), stored locally.
3. CLI and MCP clients use the key in the `Authorization: Bearer` header.
4. Deployment validates the token before executing tools/workflows.

## Upcoming OAuth architecture

The forthcoming OAuth implementation follows the MCP Authorization specification:

* `/.well-known/oauth-authorization-server` metadata endpoint (RFC 8414).
* Authorization endpoint (`/oauth2/authorize`) supporting Google, GitHub, and custom IdPs.
* Token endpoint (`/oauth2/token`) returning access + refresh tokens.
* Resource server metadata (`/.well-known/oauth-protected-resource`) for deployments advertising supported methods (`bearer_methods_supported`, scopes).
* Token introspection and JWKS endpoints for JWT validation.

We aim to make the default configuration zero-touch for mcp-agent cloud deployments while still allowing you to point at other OAuth providers if you self-host.

## Choosing an authentication mode

* **Internal tools or staging** → keep bearer tokens (fastest path).
* **Publishing to ChatGPT Apps** → deploy with `--no-auth`, optionally combine with rate limiting in code.
* **Customer-facing apps** → use bearer tokens initially, migrate to OAuth when available to integrate with existing identity providers.
* **Agents calling other MCP servers** → configure outbound auth in `mcp_agent.config.yaml`. This is independent of how end-users authenticate to your deployment.

## Related guides

* [Configure deployment auth (bearer, unauthenticated, OAuth preview) →](/cloud/authentication/deployment-auth)
* [Authenticate to external MCP servers →](/cloud/authentication/external-mcp-auth)
* [Manage secrets →](/cloud/mcp-agent-cloud/manage-secrets)