> For the complete documentation index, see [llms.txt](https://ai.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai.ortusbooks.com/introduction/release-history/3.8.0.md).

# 3.8.0

BoxLang AI Module 3.8.0 (unreleased). OAuth sign in for MCP servers, one account or one per person, and gateway turns keyed by user and conversation.

**Released:** not yet released

BoxLang AI 3.8.0 teaches the MCP client to **sign in with OAuth**. Servers that ask each person to sign in (mail, calendars, issue trackers) can now be used, and one shared client can sign in every person on their own, so an agent that serves many people uses each person's own account.

It also fixes a memory mix-up in gateways: every chat on every platform used to share one conversation. Each turn is now keyed by user and conversation.

> This page is updated as new items land on `development`.

***

## ⚠️ Migration

* **A gateway turn is now keyed by user and conversation.** `GatewaySession` ran every turn with only `{ threadId }`, so the agent's memory (keyed by user and conversation) was one shared bucket: every chat on every platform saw every other chat's messages. Each turn now runs with a `conversationId` and, when the platform names the sender, a `userId`. The conversation is the chat namespaced by its gateway (`telegram:42`), plus the platform thread when there is one (`telegram:42:topic-7`), so a Telegram forum topic or a Slack thread is its own conversation. `threadId` still names the run (queueing, cancel, steer, checkpoints).
* **Conversations a gateway kept in the old shared bucket are not found under the new keys.** Override the public `resolveConversationId( message, sourceGateway )` to move a chat to another conversation, or `turnOptions( message, sourceGateway, threadId )` to name the identity another way, for example with a platform-qualified user id. See [Gateway Sessions](https://ai.ortusbooks.com/main-components/gateway-sessions.md).
* **If you wrote your own `IMCPClient`**, add the optional argument `struct context = {}` to `send( tool, args, context )`. `MCPTool` now passes it. Without `withOAuth()` nothing else changes.

***

## ✨ New Features

### 🔑 OAuth for MCP Clients

`withOAuth()` follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/latest/basic/authorization). The client finds the authorization server from the MCP server's metadata, gets a client id (one you give, a Client ID Metadata Document, or Dynamic Client Registration), signs the person in with PKCE and the `resource` parameter, checks the issuer in the callback, and sends `Authorization: Bearer` on every request. A token that is about to expire is refreshed first, and a `401` refreshes it and tries once more.

```javascript
mcpClient = MCP( "https://mail.example.com/mcp" ).withOAuth( {
    redirectUri : "https://app.example.com/oauth/callback"
} )

// send the person to sign in
started = mcpClient.startAuthorization( "alice" )
location( started.authorizationUrl )

// at your callback route
mcpClient.completeAuthorization( url.code, url.state, url.iss ?: "" )

// from now on the calls carry Alice's token
mcpClient.send( "inbox", {} )
```

Your code does the browser step (sending the person and receiving them back). The client does the rest.

### 👤 One Client, Every Person

The `subject` option says whose tokens a call uses. `send( tool, args, context )` has a new optional `context`, and the tools an agent builds from an MCP server pass `{ chatRequest }`:

```javascript
mcpClient = MCP( "https://mail.example.com/mcp" ).withOAuth( {
    redirectUri : "https://app.example.com/oauth/callback",
    subject     : ( context ) => context.chatRequest.getUserId()
} )
```

Each person signs in once, and from then on the agent reads **their** mail, not anyone else's. With `withHandshake( true )` each person also gets an MCP session of their own.

### 🗄️ Token Stores

Tokens, the client registration and the sign ins waiting for their callback live in an `IMCPTokenStore`: three methods (`get`, `set`, `remove`), so a store that encrypts is easy to write.

| Store           | Where                                                                      | Choose it with                                         |
| --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
| Cache (default) | A BoxLang cache: memory, or Redis and others                               | `store: "cache"`, `storeOptions: { cacheName }`        |
| File            | One JSON file per record, owner-only permissions where the system has them | `store: "file"`, `storeOptions: { path }`              |
| JDBC            | A table, created when missing                                              | `store: "jdbc"`, `storeOptions: { datasource, table }` |
| Your own        | A class that implements `IMCPTokenStore`                                   | `store: "my.Store"` or an instance                     |

The file and JDBC stores keep tokens as plain text. Protect them, or write a store that encrypts.

### 🤖 Agents

`oauth` works in an agent's MCP server config:

```javascript
agent = aiAgent(
    name       : "mail-agent",
    model      : aiModel( provider: "openai" ),
    mcpServers : [
        { url: "https://mail.example.com/mcp", oauth: { redirectUri: "https://app.example.com/oauth/callback", subject: ( context ) => context.chatRequest.getUserId() } }
    ]
)
```

A server nobody has signed in to yet cannot list its tools, so the agent starts without them. After signing in, hand the signed in client to the agent with `agent.withMCPServer( mcpClient )`.

### 📡 A New Event

`onMCPAuthorizationRequired` fires when a person has to sign in or grant more scope, with `reason` (`no_token`, `unauthorized` or `insufficient_scope`), `subject`, `scope` and the `client`. See the [event reference](https://ai.ortusbooks.com/advanced/events.md#72-onmcpauthorizationrequired).

📖 Read [OAuth Sign In](https://ai.ortusbooks.com/model-context-protocol-mcp/client/oauth.md) for the full flow, the options, the errors and how to write your own store.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ai.ortusbooks.com/introduction/release-history/3.8.0.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
