# Microsoft Agent 365 Tooling SDK

This package delegates Agent 365 discovery and token work to Microsoft's
`@microsoft/agents-a365-tooling` SDK.

## Why Microsoft Created It

Microsoft's package is part of the Agent 365 SDK surface for agents that run in
the Microsoft 365 / Agent 365 ecosystem.

It exists because Agent 365 tooling is not just "connect to this MCP URL." It
is a platform problem:

- discover which MCP tool servers are configured for a specific Agent 365
  agent identity;
- support local development through `ToolingManifest.json`;
- query the Agent 365 tooling gateway in production;
- resolve the active agent identity from `TurnContext` and/or auth token
  claims;
- perform token exchange through the Microsoft Agents SDK `Authorization`
  object and `authHandlerName`;
- attach the correct per-server bearer token headers, including per-audience
  tokens for newer server shapes;
- add platform headers such as channel ID, subchannel ID, user agent, and
  agent ID;
- optionally send chat history to the MCP platform for real-time threat
  protection.

That is why Microsoft named the package "tooling" rather than "mcp-client".
The MCP protocol client is only one piece. The package's main job is to bridge
Agent 365 platform state to MCP server configuration.

## What The Microsoft SDK Answers

The SDK answers this question:

> For this Microsoft 365 agent turn, which Agent 365 MCP servers should this
> agent be able to use, and what headers are needed to call them?

The output shape this adapter needs is:

```ts
{
  mcpServerName: "mail",
  url: "https://...",
  headers: {
    Authorization: "Bearer ..."
  }
}
```

That maps directly to agent-core's remote HTTP MCP config.

## Production Mode

In production, Microsoft's SDK can:

- inspect the active `TurnContext`;
- resolve the agent identity;
- use the host `Authorization` object;
- use the configured `authHandlerName`;
- acquire tokens for Agent 365 tooling gateway calls;
- query the Agent 365 tooling gateway;
- attach per-audience bearer tokens to returned MCP server configs.

The normal production path should omit `authToken`:

```ts
createA365ToolingCapabilityProvider({
  authorization,
  authHandlerName: "agentic",
});
```

When `authToken` is omitted, Microsoft's SDK performs token exchange from the
active turn and host authorization setup.

The production discovery endpoint is shaped around the Agent 365 platform:

```txt
GET https://agent365.svc.cloud.microsoft/agents/v2/{agenticAppId}/mcpServers
```

The SDK also knows how to build direct MCP server URLs under the platform base
URL when a manifest entry does not provide a custom `url`.

When framework-specific Microsoft extensions connect MCP servers, they merge
base platform headers from `Utility.GetToolRequestHeaders()` with each returned
server's headers. This adapter follows the same shape before handing configs to
agent-core MCP:

```txt
base platform headers -> server-specific headers
```

That order matters because per-server `Authorization` headers returned by the
SDK should override any shared gateway token header.

## Development Manifest Mode

When `NODE_ENV=development`, Microsoft's SDK reads `ToolingManifest.json`
instead of calling the cloud gateway.

That is useful for local examples and tests because it exercises the same
adapter path without requiring:

- Azure deployment;
- a live Agent 365 tenant;
- real OBO token exchange;
- a real Agent 365 gateway response.

The local example uses a minimal decoded token because the SDK still decodes an
agent identity, but it does not call the cloud gateway while using the manifest
path.

The manifest mode is the reason the examples can validate this adapter without
Azure: Microsoft's SDK still returns the same `MCPServerConfig[]` shape, and
this package still maps those configs into agent-core MCP.

## Host Inputs

| Option            | Meaning                                                             | Typical source                                                 |
| ----------------- | ------------------------------------------------------------------- | -------------------------------------------------------------- |
| `authorization`   | Microsoft Agents SDK `Authorization` object used for token exchange | M365 host application / `@microsoft/agents-hosting` setup      |
| `authHandlerName` | Name of the auth handler configured for Agent 365 token exchange    | Microsoft Agents SDK app configuration                         |
| `getTurnContext`  | Optional resolver for the active Microsoft `TurnContext`            | Defaults to `@cuylabs/channel-m365-agent-core` ambient context |
| `authToken`       | Optional pre-resolved gateway token                                 | Local development or specialized hosts                         |
| `toolOptions`     | Optional metadata such as `orchestratorName`                        | Host/application configuration                                 |

## Ambient TurnContext

By default, this package reads:

```ts
currentM365TurnContext()?.turnContext;
```

from `@cuylabs/channel-m365-agent-core`.

That means the provider must run inside an M365 channel turn unless the host
passes `getTurnContext`.

For tests or non-standard hosts:

```ts
createA365ToolingCapabilityProvider({
  authorization,
  authHandlerName: "agentic",
  getTurnContext: () => myTurnContext,
});
```

Custom hosts should return a real Microsoft `TurnContext` or a compatible
object with the activity fields Microsoft's SDK needs, including conversation
and agent identity metadata.

## How This Differs From Agent-Core MCP

agent-core MCP starts after a server config is already known:

```ts
{
  transport: "http",
  url: "https://...",
  headers: { Authorization: "Bearer ..." },
}
```

Microsoft's Agent 365 tooling SDK is what obtains that config for an Agent 365
turn. It determines the `url`, `mcpServerName`, and `headers` from Microsoft
platform state.

So the layering is:

```txt
Microsoft Agent 365 platform
  -> @microsoft/agents-a365-tooling discovers authorized MCP server configs
  -> @cuylabs/agent-a365-tooling maps those configs to agent-core capabilities
  -> agent-core/mcp connects and executes tools
```