AI agents with MCP as backend

[Matanga1-2]

Description

Added a detailed explanation of how the AI agents work with MCP as a backend option.

Updated docs pages

Please also include the path for the updated docs

• ai-agent/overview
• ai-agent/build-ai-agent
• ai-agent/interact-with-ai-agent

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2667.d2ngvl90zqbob8.amplifyapp.com

[claude]

Claude finished @Matanga1-2's task —— View job

---

PR Review: AI agents with MCP as backend

I've completed my review of this PR according to CONTRIBUTING.md guidelines. Here's my comprehensive analysis:

Todo List:

• Read CONTRIBUTING.md for review guidelines
• Review docs/ai-agents/overview.md changes
• Review docs/ai-agents/build-an-ai-agent.md changes
• Review docs/ai-agents/interact-with-ai-agents.md changes
• Provide comprehensive review feedback

---

Overall Assessment

This PR successfully adds comprehensive documentation for the new MCP (Model Context Protocol) server backend capability for AI agents. The changes are well-structured and follow Port's documentation standards.

✅ Strengths

Content Quality:

• Clear explanation of MCP backend mode benefits (expanded data access, enhanced reasoning, broader tool access)
• Well-organized information architecture across the three modified files
• Comprehensive coverage of both standard and MCP backend modes
• Good use of visual elements (images, callouts, tabs) to enhance readability

Documentation Standards Compliance:

• Proper use of admonitions with descriptive titles (:::tip New capability)
• Consistent formatting with showLineNumbers for code blocks
• Appropriate use of tabs with queryString parameter
• Proper image sizing with width and border attributes
• Good use of expandable details sections for FAQs

Technical Accuracy:

• Accurate technical details about MCP server capabilities
• Clear distinction between interaction-level backend selection vs agent configuration
• Proper API documentation with cURL examples
• Comprehensive troubleshooting sections

⚠️ Areas for Improvement

Writing Style Issues:

1. docs/ai-agents/overview.md:36 - Missing hyphen in compound adjective:

   "enhanced MCP server backend mode" → "enhanced MCP-server backend mode"
   

2. docs/ai-agents/interact-with-ai-agents.md:66 - Consider more descriptive language:

   "Use MCP" toggle → "Enable MCP server backend" toggle
   

Content Suggestions:

3. docs/ai-agents/build-an-ai-agent.md:29-31 - The info callout could be more prominent. Consider using a tip callout instead to highlight this important feature.

4. docs/ai-agents/interact-with-ai-agents.md:101-103 - The info about Slack MCP availability feels buried. Consider moving this limitation higher in the Slack section.

Technical Clarifications:

5. docs/ai-agents/overview.md:46 - Link reference could be more specific:

   "when [interacting with them](/ai-agents/interact-with-ai-agents)" 
   → "when [interacting with them](/ai-agents/interact-with-ai-agents#backend-mode-selection)"
   

6. docs/ai-agents/interact-with-ai-agents.md:146-162 - The MCP parameter examples are excellent, but consider adding a brief explanation of when to use use_mcp=false explicitly.

🔧 Minor Technical Issues

7. Image References - All new images are properly placed in /static/img/ai-agents/ following conventions
8. Link Structure - All internal links use proper full paths as required
9. Code Examples - Bash examples properly formatted with syntax highlighting

📝 Content Completeness

The documentation comprehensively covers:

• ✅ Feature overview and capabilities
• ✅ Configuration instructions
• ✅ Multiple interaction methods
• ✅ API usage with examples
• ✅ Troubleshooting and FAQs
• ✅ Security considerations

🎯 Recommendations

1. Priority: High - Fix the compound adjective hyphenation issue
2. Priority: Medium - Enhance the visibility of MCP limitations in Slack
3. Priority: Low - Consider adding a "Quick Start with MCP" section to help users immediately understand the value

Final Verdict

✅ APPROVE - This PR adds valuable documentation for an important new feature. The content is comprehensive, well-structured, and follows Port's documentation standards. The suggested improvements are minor and don't block approval.

The documentation effectively explains the MCP server backend enhancement while maintaining backward compatibility information for existing users.