# How Logto's Model Context Protocol Integration Works: A Technical Deep Dive

> Explore Logto's Model Context Protocol integration. Discover how AI agents pass structured context during OIDC authentication for pre-scoped tokens, improving efficiency.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: deep-dive
- Published: 2026-07-05

---

**Logto's Model Context Protocol (MCP) integration enables AI agents to pass structured context payloads during OIDC/OAuth 2.1 authentication, persisting them in the `oidc_model_instances` table and issuing tokens pre-scoped to specific model contexts without requiring additional lookup requests.**

The logto-io/logto repository extends beyond traditional web and mobile authentication to support AI-driven architectures through its Model Context Protocol implementation. This internal convention allows AI models and autonomous agents to inject contextual metadata directly into the authentication flow, ensuring that issued tokens carry precise model-level permissions from the moment of issuance.

## What Is the Model Context Protocol?

The **Model Context Protocol** is a Logto-specific extension to standard OIDC/OAuth 2.1 flows designed for agent-based AI architectures. It defines a structured payload containing critical contextual information such as the **tenant ID**, **target model name**, and optional metadata including user-role hints, request origins, or UI prompt directives.

When an AI service initiates authentication, this protocol conveys the exact operational context the model requires, allowing Logto to bind the resulting authentication session to a specific model instance rather than issuing a generic token.

## How the Model Context Protocol Integration Works

### Client-Side Context Injection

Logto's client libraries automatically serialize the context payload and attach it to authentication requests. When calling `getAuthorizationUrl()` or exchanging codes via `openIdClient.callback()`, the SDK includes the data as a JSON-encoded value in the `model_context` query parameter for GET requests, or within the request body for POST flows.

The payload structure includes:

- `tenantId`: The isolated tenant boundary for multi-tenant AI deployments
- `modelName`: The specific AI model identifier (e.g., "Chatbot")
- `meta`: Optional key-value pairs for role hints, language preferences, or purpose specifications

### Server-Side Persistence

Upon receiving the request, Logto's OIDC provider implementation in `packages/core/src/oidc/provider/*` parses the `model_context` parameter and creates a temporary "model-instance" row in the `oidc_model_instances` table. This table, defined in [`packages/schemas/tables/oidc_model_instances.sql`](https://github.com/logto-io/logto/blob/main/packages/schemas/tables/oidc_model_instances.sql), stores the model name, tenant ID, and serialized context JSON, effectively linking the authentication session to that specific model instance.

The persistence layer ensures that downstream services can retrieve the exact model context after the user completes sign-in, maintaining state across the authentication lifecycle.

### Token Scoping for AI Agents

By establishing the model context during the initial authentication request, Logto issues tokens that are **already scoped** to the particular model instance. This eliminates the need for AI platforms to perform post-authentication lookups to determine which model or tenant context applies to the token, significantly reducing latency in agent-based architectures and guaranteeing that permissions are correctly bounded at the moment of token issuance.

## Implementing Model Context Protocol in Your Application

### Node.js SDK Implementation

The following example demonstrates how to initialize a Logto client with model context and retrieve a model-scoped authorization URL:

```typescript
import { createLogtoClient } from '@logto/client'

// Initialize the Logto client
const logto = createLogtoClient({
  endpoint: 'https://example.logto.io',
  appId: 'your-app-id',
})

// Build the model-context object
const modelContext = {
  tenantId: 'tenant_123',
  modelName: 'Chatbot',
  meta: {
    purpose: 'answer-user-question',
    language: 'en',
  },
}

// Include the model context when requesting a sign-in URL
const signInUrl = logto.getAuthorizationUrl({
  redirectUri: 'https://myapp.com/callback',
  // The SDK automatically serialises this into the `model_context` query-parameter
  modelContext,
})

// After the user authenticates, exchange the code for a token
const tokenResponse = await logto.openIdClient.callback(
  'https://myapp.com/callback',
  { code: returnedCode },
  { modelContext } // ensures the same context is used for token issuance
)

```

### Querying Persisted Model Instances

To inspect or verify stored model contexts, query the `oidc_model_instances` table directly:

```sql
SELECT *
FROM oidc_model_instances
WHERE model_name = 'Chatbot'
  AND tenant_id = 'tenant_123';

```

## Key Files and Architecture

According to the logto-io/logto source code, the Model Context Protocol integration relies on these critical components:

- **[`README.md`](https://github.com/logto-io/logto/blob/main/README.md)** (lines 46 and 79): Declares MCP support as a core feature, stating the platform is "Ready for Model Context Protocol and agent-based architectures"

- **[`packages/schemas/tables/oidc_model_instances.sql`](https://github.com/logto-io/logto/blob/main/packages/schemas/tables/oidc_model_instances.sql)**: Defines the database schema that stores model-context payloads, tenant IDs, and model names for each authentication session

- **`packages/core/src/oidc/provider/*`**: Implements the OIDC provider logic that handles the `model_context` parameter, creates model instances, and manages session binding

- **`packages/toolkit/core-kit/src/models/*`**: Exposes utility functions for creating and retrieving model instances from the API layer, facilitating interactions with the persistence layer

## Summary

- The **Model Context Protocol** extends standard OIDC flows by allowing AI agents to inject structured context during authentication.
- Context data passes via the `model_context` parameter and persists in the **`oidc_model_instances`** table.
- Logto creates temporary model instances that bind authentication sessions to specific AI models and tenant contexts.
- Tokens issued through MCP are pre-scoped with model-level permissions, eliminating post-authentication lookups for agent architectures.
- Client SDKs in `packages/toolkit/core-kit` and OIDC provider logic in `packages/core` handle the complete flow automatically.

## Frequently Asked Questions

### What is Model Context Protocol in Logto?

Model Context Protocol is an internal Logto convention that extends OIDC/OAuth 2.1 authentication to support AI-driven services. It allows structured context payloads containing tenant IDs, model names, and metadata to travel alongside standard authentication requests, enabling the issuance of tokens specifically scoped to AI model instances.

### How does Logto store model context data?

Logto stores model context in the **`oidc_model_instances`** table defined in [`packages/schemas/tables/oidc_model_instances.sql`](https://github.com/logto-io/logto/blob/main/packages/schemas/tables/oidc_model_instances.sql). Each row contains the model name, tenant ID, and serialized JSON context data. The OIDC provider implementation creates these temporary records when parsing the `model_context` parameter from incoming authentication requests.

### Can I use Model Context Protocol with any OIDC client?

While the protocol is designed to work with Logto's official SDKs, any OIDC-compliant client can implement MCP by manually including a JSON-encoded `model_context` parameter in authorization requests or token exchange payloads. The backend logic in `packages/core/src/oidc/provider/*` handles parsing regardless of the client origin.

### What are the benefits of Model Context Protocol for AI agents?

Model Context Protocol reduces authentication latency for AI agents by eliminating the need for separate model lookup requests after token issuance. By binding the model context to the initial authentication session stored in `oidc_model_instances`, agents receive tokens that already carry the correct permissions and contextual metadata, streamlining the transition from authentication to model execution.