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

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

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:

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 (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: 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. 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.

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