> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agent-auth`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Overview: MCP server authentication

Model Context Protocol (MCP) is an open standard that gives AI apps a consistent, secure way to connect to external tools and data sources. A helpful way to picture it is USB‑C for AI integrations: instead of building a custom connector for every service, MCP provides one interface that works across different models, platforms, and backends. That makes it much easier to build agent-style apps that can actually do work, but it also makes authorization a bigger deal, because once an agent can act on your behalf, you need clear, tight control over what it can access and what actions it’s allowed to take.

At its core, MCP follows a client-server architecture where a host application can connect to multiple servers:

- **MCP hosts**: AI applications like Claude Desktop, IDEs, or custom AI tools that need to access external resources
- **MCP clients**: Protocol clients that maintain connections between hosts and servers
- **MCP servers**: Lightweight programs that expose specific capabilities (tools, data, or services) through the standardized protocol
- **Data sources**: Local files, databases, APIs, and services that MCP servers can access

This architecture enables a ecosystem where AI models can seamlessly integrate with hundreds of different services without requiring custom code for each integration.

## The path to secure MCP: OAuth 2.1 integration

Recognizing these challenges, the MCP specification evolved to incorporate robust authorization mechanisms. The Model Context Protocol provides authorization capabilities at the transport level, enabling MCP clients to make requests to restricted MCP servers on behalf of resource owners.

The **MCP specification chose OAuth 2.1 as its authorization framework** for several compelling reasons

|  |  |
|---------|-------------|
| Industry standard | OAuth 2.1 is a well-established, widely-adopted standard for delegated authorization, with extensive tooling and ecosystem support. |
| Security best practices | OAuth 2.1 incorporates lessons learned from OAuth 2.0, removing deprecated flows and enforcing security measures like PKCE (Proof Key for Code Exchange). |
| Flexibility | Supports multiple grant types suitable for different MCP use cases:<br/> **Authorization code**: When AI agents act on behalf of human users<br/> **Client credentials**: For machine-to-machine integrations |
| Ecosystem compatibility | Works with existing identity providers and authorization servers, making it easier for enterprises to integrate MCP into their existing security infrastructure. |

This authorization mechanism is based on established specifications listed below, but implements a selected subset of their features to ensure security and interoperability while maintaining simplicity:

- **OAuth 2.1**: Core authorization framework with enhanced security
- **OAuth 2.0 Authorization Server Metadata (RFC8414)**: Standardized server discovery
- **OAuth 2.0 Dynamic Client Registration Protocol (RFC7591)**: Automatic client registration
- **OAuth 2.0 Protected Resource Metadata (RFC9728)**: Resource server discovery
- **Client ID Metadata Document (CIMD)**: Lets authorization servers fetch client metadata directly from a client-hosted document for authorization

## The authorization flow in practice

Now let's zoom in and see how the MCP OAuth 2.1 flow unfolds step-by-step:

### Discovery phase

1. **MCP client** encounters a protected MCP server
2. **Server** responds with `401 Unauthorized` and `WWW-Authenticate` header pointing to Scalekit Auth Server
3. **Client** discovers Scalekit Auth Server capabilities through metadata endpoints

```d2 pad=36

title: "MCP Login Discovery Phase" {
  near: top-center
  shape: text
  style.font-size: 18
}

shape: sequence_diagram

MCP Client
Your MCP Server
Scalekit Auth Server
Your Customer's User

MCP Client -> Your MCP Server: POST /mcp\n(Without Authorization Header)
Your MCP Server -> MCP Client: 401 Unauthorized\n(WWW-Authenticate: resource_metadata="...")
MCP Client -> Your MCP Server: GET /.well-known/oauth-protected-resource\n(Fetch protected MCP Server's metadata)
Your MCP Server -> MCP Client: Returns resource metadata\n(authorization server URL, scopes)
MCP Client -> Scalekit Auth Server: GET /.well-known/oauth-authorization-server
Scalekit Auth Server -> MCP client: Scalekit Auth Server metadata\n
```

### Authorization phase

4. **Client** registers with Scalekit Auth Server (if using DCR)
5. **Scalekit Auth Server** issues client credentials (if using DCR)
6. **Client** initiates appropriate OAuth flow
7. **User** grants consent (for Authorization Code flow)
8. **Scalekit Auth Server** issues access token with appropriate scopes

### Client registration
#### Dynamic client registration

MCP clients and authorization servers SHOULD support the OAuth 2.1 Dynamic Client Registration Protocol to allow MCP clients to obtain OAuth client IDs without user interaction. This enables seamless onboarding of new AI agents without manual configuration.

```d2 pad=36
title: "MCP DCR Authorization Phase" {
  near: top-center
  shape: text
  style.font-size: 18
}

shape: sequence_diagram

MCP Client
Your MCP Server
Scalekit Auth Server
Your Customer's User

MCP Client -> Scalekit Auth Server: POST /res_123../client_register
Scalekit Auth Server -> MCP Client: return with client_id and client_secret
MCP Client -> Scalekit Auth Server: redirect to oauth/authorize
Scalekit Auth Server -> Your Customer's User: Prompt to Authenticate & Consent
Your Customer's User -> Scalekit Auth Server: Authenticates & Consents
Scalekit Auth Server -> MCP Client: Returns authorization code
MCP Client -> Scalekit Auth Server: POST /oauth/token
Scalekit Auth Server -> MCP Client: Issues access_token, id_token, scopes
```

#### Client ID Metadata Document (CIMD)

MCP clients SHOULD support the Client ID Metadata Document (CIMD) specification, which allows clients to publish their OAuth client metadata at a well-known URL under their control. This enables authorization servers to automatically retrieve and validate client metadata without requiring an explicit dynamic registration request, simplifying onboarding for new AI agents while maintaining secure, decentralized client configuration.

```d2 pad=36
title: "MCP CIMD Authorization Phase" {
  near: top-center
  shape: text
  style.font-size: 18
}

shape: sequence_diagram

MCP Client
Your MCP Server
Scalekit Auth Server
Your Customer's User

MCP Client -> Scalekit Auth Server: Redirect to oauth/authorize with PKCE Challenge
MCP Client <-> Scalekit Auth Server: Authorization server fetches client metadata
Scalekit Auth Server -> Your Customer's User: Prompt to Authenticate & Consent
Your Customer's User -> Scalekit Auth Server: Authenticates & Consents
Scalekit Auth Server -> MCP Client: Returns authorization code
MCP Client -> Scalekit Auth Server: POST /oauth/token with PKCE verifier and auth code
Scalekit Auth Server -> MCP Client: Issues access_token, id_token, scopes
```

### Access phase

9. **Client** includes access token in requests to MCP server
10. **MCP server** validates token and enforces scope-based permissions
11. **Server** processes request and returns response
12. **All interactions** are logged for audit and compliance

```d2 pad=36

title: "Access and Refresh Token Phase" {
  near: top-center
  shape: text
  style.font-size: 18
}

shape: sequence_diagram

MCP Client
Your MCP Server
Scalekit Auth Server

access_phase: {
  MCP Client -> Your MCP Server: Tool call with Bearer token
  Your MCP Server -> Your MCP Server: Validate token
  Your MCP Server -> MCP Client: Authorized response
}

refresh_phase: {
  MCP Client -> Scalekit Auth Server: POST /oauth/token\n(grant_type=refresh_token)
  Scalekit Auth Server -> MCP Client: New access token & refresh token
}

```

## Key security enhancements in MCP OAuth 2.1

MCP’s OAuth 2.1 profile reduces a few common risks in the authorization code flow. The key enhancements are:

- **Mandatory PKCE**: Clients must use PKCE to help prevent authorization code interception.
- **Strict redirect URI validation**: Servers must only allow pre-registered redirect URIs and enforce an exact match to reduce redirect attacks.
- **Short-lived tokens**: Authorization servers should issue short-lived access tokens to limit impact if a token leaks.
- **Granular scopes**: Use narrow scopes (for example, `todo:read`, `todo:write`) so apps request only what they need and users can understand what they’re granting.

---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |