Add design principles for line-of-business MCP apps

[kaul-vineet]

Summary

This PR adds detailed design and technical guidance for building line-of-business (LOB) MCP apps for Microsoft 365 Copilot. The article is intended for developers and architects integrating Copilot with enterprise systems such as Salesforce, ServiceNow, HubSpot, Dynamics 365, SAP, Workday, Jira, and Coupa.

LOB applications present challenges that aren't fully addressed by general MCP app guidance. They commonly have large and highly customized data models, complex record relationships, controlled values, long system-generated record IDs, source-specific permissions, consequential business actions, API throttling, and environment-specific workflows. Two organizations using the same LOB product can expose different fields, values, relationships, permissions, and processes.

The article provides reusable architecture and implementation patterns for addressing these challenges without reproducing the full LOB application inside Copilot. It recommends using the conversation to establish business context and focused app widgets for structured review, exploration, and action.

Guidance covered

The article explains how to map the target LOB data model before defining tools and how to keep agent instructions, MCP tool handlers, the LOB integration layer, and app widgets aligned with that model. It separates the responsibilities of each component so that business rules, validation, authorization, and API communication are enforced in the appropriate layer.

It describes how to select an authentication model based on the capabilities of the target LOB system, including delegated identity, application identity, and shared credentials. The guidance highlights the differences in downstream authorization and attribution for each model.

The user-experience guidance recommends building a contextual experience rather than replicating the LOB application or its screens. It covers focused app widgets, on-demand traversal of related business entities, avoiding heavy traversal screens for independent operations, and prefilling create forms with information already supplied through the conversation.

The tool-design guidance recommends exposing a focused set of recognizable business operations instead of mirroring an entire enterprise API. It also recommends reusing a small set of optimized list, detail, and form app widgets rather than creating a separate widget for every tool or entity.

The article introduces a two-call name-to-ID resolution pattern for viewing and editing records. The first call searches with recognizable business text and returns lightweight candidate records with stable IDs. If one record matches, the second call uses its ID directly. If multiple records match, the app widget displays a list with View or Edit controls bound to the corresponding IDs. This prevents an operation from being applied to the first or wrong matching record.

Additional patterns cover:

• Mapping user-facing controlled values to the codes required by the LOB API.
• Handling dependencies between controlled-value fields.
• Translating natural-language conditions into validated server-side filters.
• Preserving filters during multi-turn refinement.
• Applying result limits, predictable sorting, pagination, and short-lived caching.
• Including query and security context in cache keys.
• Avoiding N+1 requests when resolving related-record names.
• Performing large aggregations on the MCP server instead of in Copilot or the app widget.
• Resolving relationship names to authorized record IDs before creating records.
• Preserving form state when a related record is ambiguous.
• Protecting consequential relationship changes during updates.
• Using dedicated tools for business operations with broader effects, such as converting a lead or resolving an incident.

Reference implementations

The guidance is based on implementation patterns demonstrated by the Salesforce CRM, ServiceNow ITSM, and HubSpot CRM samples in the mcp-interactiveUI-samples repository. It also links to the completed LOB MCP apps distributed through the Microsoft Copilot Agent Kit.

Seven supporting images demonstrate related-record exploration, conversation-prefilled forms, filtered lists, server-side aggregation, relationship fields, relationship-resolution suggestions, and dedicated business actions.

Documentation placement

The article is added to the existing MCP server guidance in the Microsoft 365 Copilot extensibility documentation. It appears immediately after UX guidelines for MCP apps and before Add citations:

MCP servers → UX guidelines for MCP apps → Design line-of-business MCP apps → Add citations

Expected published URL:

https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/plugin-mcp-apps-lob-design-principles

Files changed

• Adds docs/plugin-mcp-apps-lob-design-principles.md.
• Adds seven article images under docs/assets/images/lob-mcp-apps/.
• Updates docs/TOC.yml to add the article to the MCP app guidance.
• Updates cspell.json with valid LOB terminology used by the article.

Validation

The article was validated with the repository-specific Markdown and spelling configurations:

markdownlint docs/plugin-mcp-apps-lob-design-principles.md --config .markdownlint.json
cspell docs/plugin-mcp-apps-lob-design-principles.md --config cspell.json --no-progress
git diff --check

All targeted checks passed. All seven article images are referenced, and the local article and image links resolve.