# Agent-Core MCP Integration

This package builds on two agent-core concepts:

- `capabilityProviders`
- `createMCPManager()`

It does not replace agent-core MCP. It uses agent-core MCP at turn time.

## Capability Providers

agent-core exposes `capabilityProviders` on `createAgent()`:

```ts
const agent = createAgent({
  model,
  capabilityProviders: [provider],
});
```

A provider contributes MCP tools at the start of each user turn with an
`AgentCapabilityContext`:

```ts
{
  sessionId,
  turnId,
  message,
  cwd,
  abort,
  baseToolIds,
  baseMcpToolNames,
}
```

The provider can return from `contributeMcpTools()`:

- `mcpTools`: MCP-backed AI SDK tools for the current turn.
- `cleanup`: a callback agent-core runs after the turn completes or fails.

Those tools are merged into the model loop for only the active turn. They are
not persisted on the agent and are not visible to other sessions or future
turns.

## How This Package Uses Capabilities

`createA365ToolingCapabilityProvider()` returns an agent-core
`AgentCapabilityProvider`.

On each turn it:

1. reads the active M365 `TurnContext`;
2. asks Microsoft's Agent 365 tooling SDK for MCP server configs;
3. merges Microsoft base platform headers with each returned server's headers;
4. maps those configs into agent-core MCP config;
5. calls `createMCPManager()`;
6. returns the MCP tools from `manager.getTools()`;
7. returns `cleanup: () => manager.close()`.

## Static MCP Config vs A365 Capabilities

agent-core already supports static MCP configuration. Use static MCP when the
server list is known when the agent is created:

```ts
const manager = createMCPManager({
  search: {
    transport: "http",
    url: "https://example.com/mcp",
  },
});
```

Agent 365 tooling is different. The server list is resolved from the current
Microsoft turn and may depend on:

- tenant;
- user;
- agent identity;
- A365 gateway configuration;
- auth handler and token exchange state.

That makes it turn-scoped, not static.

Put another way: `agent-core/mcp` is the engine that connects and executes MCP
tools. It does not discover Agent 365 servers or perform Microsoft token
exchange. Microsoft's `@microsoft/agents-a365-tooling` package does that
platform-specific discovery/auth work, and this package adapts its output into
agent-core's MCP engine.

## Tool Names

agent-core namespaces MCP tools by server name:

```txt
<serverName>__<toolName>
```

For example:

```txt
mail__search_messages
calendar__create_event
```

The server name comes from Microsoft's `mcpServerName` field.
The prefixing happens inside agent-core's MCP manager. This package only passes
the Microsoft server name through as the MCP server `name`.

## Cleanup Semantics

agent-core runs capability cleanup after `onChatEnd` middleware.

For the default connector, cleanup closes the per-turn MCP manager. That closes
the MCP clients opened for this turn.

Cleanup is best-effort across providers. agent-core attempts all cleanup
callbacks and logs cleanup errors instead of hiding the original turn result.